proto-socket/skills/code-review/SKILL.md

name	description
code-review	Review completed implementation work for toki_socket. Reads PLAN.md and CODE_REVIEW.md from the active task, reviews the actual changed source files, appends a verdict to CODE_REVIEW.md, then archives both files as .log. If Required issues are found, writes a new PLAN.md and CODE_REVIEW.md stub so the loop continues immediately.

Code Review

Overview

This skill is the third step in the plan → code → review loop:

plan skill → implementing agent → code-review skill (this)
     ↑                                      |
     └──────── (issues found) ── new PLAN.md┘

Directory state signals:

State	Meaning
PLAN.md + CODE_REVIEW.md both present	Ready for code review ← run this skill
Only *.log files	Task complete

Note: PLAN.md and CODE_REVIEW.md are always present together. The implementing agent does not rename or delete either file — archiving is this skill's responsibility.

---

Step 1 — Find the Active Task

1. Glob tasks/*/CODE_REVIEW.md.
2. If exactly one exists: that is the active task. Record task_name. Confirm PLAN.md is also present in the same directory.
3. If no CODE_REVIEW.md found: nothing to review. Stop and report.
4. If multiple: list them and ask the user which to review. Stop.

---

Step 2 — Load Context

The reading strategy depends on whether this is the first review or a follow-up.

2-1. Determine review round

Count tasks/{task_name}/code_review_*.log files.

• Count = 0 → First review: no prior diff to reference. Read the full codebase as described in 2-2A.
• Count ≥ 1 → Follow-up review: use git diff to anchor the search, then expand as described in 2-2B.

2-2A. First review — full analysis

No git narrowing. Read everything relevant to the plan:

1. tasks/{task_name}/CODE_REVIEW.md
2. tasks/{task_name}/PLAN.md
3. Every source file listed in the plan's "수정 파일 및 체크리스트" — read the whole file.
4. Every test file that exercises the changed code.
5. Every file that imports or is imported by the changed files.

2-2B. Follow-up review — diff-anchored + expansion

Start with git to identify what changed, then expand outward to connected code.

Collect the diff:

git rev-parse HEAD 2>/dev/null && git diff HEAD || (git diff && git diff --cached)
git diff main..HEAD    # if on a feature branch
git log --oneline -10

Expand beyond the diff — for each changed file or symbol, also read:

• Files that import the changed file (callers may be broken by signature changes)
• Files that implement or extend a changed interface or abstract class
• Test files that exercise the changed logic, even if not modified themselves
• Any file the plan's "수정 파일 및 체크리스트" lists that does not appear in the diff (planned but possibly missing)

The diff scopes where to start; it does not limit where to stop. Follow the connections.

---

Step 3 — Pre-Review Checklist

Complete every item before writing the verdict. Use the git diff as the primary reference — only reach outside it when a specific check demands it.

• Compare git diff against the plan's "수정 파일 및 체크리스트" — are all planned changes present? Are there unplanned changes?
• For every symbol renamed or removed in the diff: git grep <old_name> on the pre-change tree (or Grep on current tree) to confirm no stale references remain outside the diff.
• For every new test added in the diff: confirm the test name matches the plan, and the assertion is non-trivial (not just "no exception thrown").
• Scan the diff for code quality issues: debug prints, dead code, leftover TODOs, commented-out blocks.
• Check for unintended diff noise: formatting-only changes, unrelated file edits, accidentally committed debug code.
• Cross-check the claimed dart analyze / go test output in CODE_REVIEW.md against what the diff actually introduces.

---

Step 4 — Append Verdict to CODE_REVIEW.md

Append the following section to the existing CODE_REVIEW.md. Every field is required.

---

## 코드리뷰 결과

### 종합 판정

**[ PASS | WARN | FAIL ]**

> <1–2 sentences summarising the overall assessment.>

### 차원별 평가

| 차원 | 판정 | 비고 |
|------|------|------|
| 정확성 (Correctness) | Pass/Warn/Fail | |
| 완성도 (Completeness) | Pass/Warn/Fail | |
| 테스트 커버리지 | Pass/Warn/Fail | |
| API 계약 | Pass/Warn/Fail | |
| 코드 품질 | Pass/Warn/Fail | |
| 계획 대비 이탈 | Pass/Warn/Fail | |
| 검증 신뢰도 | Pass/Warn/Fail | |

### 발견된 문제

<!-- 없으면 "없음" 한 줄 -->
- **[Required|Suggested|Nit]** `<file>:<line>` — <problem>. Fix: <concrete fix>.

### 다음 단계

<!-- 해당하는 하나만 남기고 나머지 줄은 삭제 -->
**[PASS]** 추가 작업 불필요. 아카이브 완료.
**[FIX]** Required 문제 N건. 새 PLAN.md 작성 완료. 구현 에이전트는 PLAN.md를 읽고 작업 시작.

---

Step 5 — Archive Both Files

Archive order: CODE_REVIEW.md first, then PLAN.md.

Archive CODE_REVIEW.md:

• Count existing tasks/{task_name}/code_review_*.log → that count is N.
• Rename tasks/{task_name}/CODE_REVIEW.md → tasks/{task_name}/code_review_N.log.

Archive PLAN.md:

• Count existing tasks/{task_name}/plan_*.log → that count is M.
• Rename tasks/{task_name}/PLAN.md → tasks/{task_name}/plan_M.log.

After this step neither PLAN.md nor CODE_REVIEW.md exists.

---

Step 6 — Post-Review Actions

If verdict is PASS (zero Required issues)

No further files needed. Report to the user:

• Verdict: PASS
• Archives: code_review_N.log, plan_M.log
• Task status: complete (only .log files remain in tasks/{task_name}/)

If verdict is WARN or FAIL (one or more Required issues)

Write new files for the fix round:

Write tasks/{task_name}/PLAN.md following the plan skill format exactly:

• Count tasks/{task_name}/plan_*.log files after the archive above → that count is the new plan's N.
• Header: <!-- task={task_name} plan=N tag=REVIEW_<PARENT_TAG> -->
• Include the "구현 에이전트에게" section.
• One plan item per Required issue:
  • 문제: quote the specific file:line from the review finding.
  • 해결 방법: before/after code block — read the actual source for current state.
  • 수정 파일 및 체크리스트: exhaustive checkbox list.
  • 테스트 작성: decision + justification.
  • 중간 검증: runnable command.
• Suggested/Nit issues may be grouped into one optional item.
• Include 수정 파일 요약 table.
• Include 최종 검증 section.

Write tasks/{task_name}/CODE_REVIEW.md stub:

• Header: <!-- task={task_name} plan=N tag=REVIEW_<PARENT_TAG> --> (same N as new PLAN.md)
• Completion table listing every new plan item with [ ].
• Empty sections: 계획 대비 변경 사항, 주요 설계 결정, 리뷰어 체크포인트, 검증 결과.

Report to the user:

• Verdict: WARN/FAIL, N Required issues
• Archives: code_review_N.log, plan_M.log
• New plan: tasks/{task_name}/PLAN.md ready for implementing agent

---

Review Dimensions Reference

Dimension	What to check
정확성	Logic errors, off-by-ones, wrong types, missed edge cases
완성도	All plan checkboxes done; none silently skipped
테스트 커버리지	Required tests present; assertions are meaningful
API 계약	All call sites updated; breaking changes documented
코드 품질	No debug prints, dead code, leftover TODOs
계획 대비 이탈	Deviations justified; no new unreviewed risk
검증 신뢰도	Reported output consistent with actual code

---

Quality Rules

Do write:

• Specific file:line for every issue.
• A concrete fix for every Required issue.
• The exact symbol name when Grep finds stale references.
• The exact test name when a required test is missing.

Do not write:

• "This looks fine" without having read the code.
• Style warnings with no linter rule backing them.
• Vague verdicts — every dimension gets Pass/Warn/Fail.

---

Final Verification Checklist

1. code_review_N.log exists with verdict section appended.
2. plan_M.log exists (was PLAN.md).
3. Neither CODE_REVIEW.md nor PLAN.md exists as .md in the task directory.
4. If PASS: only .log files remain in tasks/{task_name}/.
5. If FAIL: new PLAN.md exists, header plan=N matches count of plan_*.log after archiving, covers every Required issue with full sub-sections.
6. If FAIL: new CODE_REVIEW.md stub exists, header plan=N matches new PLAN.md, completion table lists every item.