update agent-ops/skills/common/plan/SKILL.md

agent-ops/skills/common/plan/SKILL.md

@@ -62,17 +62,31 @@ Use short snake_case task names, e.g. `api_refactor`.
 
 ## Step 2 - Analyze Before Writing
 
-Complete these before creating files:
+Complete all items below before creating any files. Work through them in order; do not proceed to the next step until every checkbox is done.
 
-- Read every source file the change will touch, whole file.
-- Read every test file that exercises changed behavior.
-- For each behavior change, note whether existing tests cover it.
-- Grep renamed/removed symbols for all call sites and import chains.
-- Check package manifests/dependency files before adding dependencies.
-- Anticipate compile issues: missing overrides, type mismatches, broken imports.
-- Confirm final verification commands work in this repository layout.
+- [ ] **Read all source files in full** — read every source file the change will touch, whole file. No partial reads.
+- [ ] **Read all test files in full** — read every test file that exercises the changed behavior.
+- [ ] **Assess test coverage** — for each behavior change, explicitly record whether existing tests cover it.
+- [ ] **Grep all symbol references** — for any renamed or removed symbol, find every call site and import chain.
+- [ ] **Check dependency manifests** — before adding any new package, verify its presence in go.mod / package manifest.
+- [ ] **Pre-check compile issues** — identify missing interface implementations, type mismatches, and broken imports.
+- [ ] **Verify verification commands** — confirm that the final verification commands actually run in this repository layout.
 
-## Step 3 - Archive Existing Active Files
+## Step 3 - Determine GXX Grade
+
+GXX is an output of analysis, not an input. Determine lane and grade only after Step 2 is fully complete.
+
+- [ ] **Assess change scope** — count affected files, interface impact, and call-site count.
+- [ ] **Check risk factors** — mark any that apply: concurrency, storage/migration, protocol/schema, auth, irreversible behavior.
+- [ ] **Evaluate test confidence** — judge whether existing tests sufficiently verify the changed behavior.
+- [ ] **Decide lane** — use `local` if the plan is explicit and tests are sufficient; use `cloud` if any of the following apply:
+  - Tests are weak or do not cover the changed behavior
+  - Broad API/call-site impact
+  - Concurrency, storage, protocol, or auth risk
+  - Prior local build failure on this task
+- [ ] **Decide GNN** — assign a higher grade as scope, ambiguity, irreversibility, and blast radius increase. Grade is complexity-based, not model-name-based.
+
+## Step 4 - Archive Existing Active Files
 
 Before writing new active files for the chosen task:
 
@@ -81,7 +95,7 @@ Before writing new active files for the chosen task:
 
 The new plan number is the count of `plan_*.log` after archiving.
 
-## Step 4 - Write Plan File
+## Step 5 - Write Plan File
 
 Header line must be exactly:
 
@@ -92,11 +106,17 @@ Header line must be exactly:
 Required sections:
 
 - Title.
-- `이 파일을 읽는 구현 에이전트에게`: tell the implementer to complete checklists, run intermediate/final verification, and fill every `CODE_REVIEW-*-G??.md` section with actual implementation notes and command output. Explicitly state that the implementing agent must NOT execute the archiving instructions in the review file's "이 파일을 읽는 리뷰 에이전트에게" section — those instructions (renaming to `*.log`, writing `complete.log`) are for the code-review skill only.
+- `이 파일을 읽는 구현 에이전트에게`: open with a bold warning that filling in `CODE_REVIEW-*-G??.md` is a mandatory final step — the task is NOT complete until every section of that file is filled. Tell the implementer to complete checklists, run intermediate/final verification, and fill every `CODE_REVIEW-*-G??.md` section with actual implementation notes and command output. Explicitly state that the implementing agent must NOT execute the archiving instructions in the review file's `이 파일을 읽는 리뷰 에이전트에게` section — those instructions (renaming to `*.log`, writing `complete.log`) are for the code-review skill only.
 - `배경`: 2-4 sentences explaining why the work is needed.
+- `분석 결과`: record the findings from Step 2 and Step 3. This section is the written output of the analysis — not a summary, but the actual findings that justify the plan's scope and decisions. Must include all of the following subsections:
+  - `읽은 파일`: list every source and test file read during analysis, with path.
+  - `테스트 커버리지 공백`: list each behavior change and whether existing tests cover it; explicitly note gaps.
+  - `심볼 참조`: list renamed/removed symbols and every call site found, or state "none" if no symbols were changed.
+  - `범위 결정 근거`: state which files or areas were explicitly excluded from this change and why. This is the boundary justification — the implementing agent must not silently expand scope beyond what is recorded here.
+  - `빌드 등급`: state the decided lane and GNN grade with a one-line rationale.
 - One item per change: `### [TAG-1] Title`, `TAG-2`, etc.
 - `수정 파일 요약`: table mapping files to item ids.
-- `최종 검증`: runnable commands and expected outcome.
+- `최종 검증`: runnable commands and expected outcome. The final line of this section must read exactly — **"모든 코드 변경 완료 후 반드시 `CODE_REVIEW-*-G??.md`의 전체 섹션을 채운다. 이 파일 작성이 구현의 마지막 단계다."**
 
 Each plan item must include:
 
@@ -116,6 +136,7 @@ Quality rules:
 - List all call sites for renamed/removed symbols.
 - Never write "add tests as needed"; decide up front.
 - Do not cite files you did not read.
+- Be concise. Write the minimum words needed to convey the decision or fact. No preamble, no restatement of context already in the plan, no closing summaries.
 
 Test policy:
 
@@ -127,7 +148,7 @@ Test policy:
 | Internal refactor | Existing tests may be enough |
 | Concurrency logic | Race/ordering test recommended |
 
-## Step 5 - Write Review Stub
+## Step 6 - Write Review Stub
 
 Use the template below exactly. Fill `{…}` placeholders from the plan; everything else is fixed and must not be changed by the implementing agent.
 
@@ -136,6 +157,10 @@ Use the template below exactly. Fill `{…}` placeholders from the plan; everyth
 
 # Code Review Reference - {TAG}
 
+> **[IMPLEMENTING AGENT — READ FIRST] Filling in this file is the mandatory final step of implementation.**
+> The task is NOT complete until every section below is filled in.
+> Follow the ownership table at the bottom of this file for which sections you own.
+
 ## 개요
 
 date={YYYY-MM-DD}
@@ -186,18 +211,23 @@ $ {verification command from plan}
 $ {final verification command from plan}
 (output)
 ```
+
+---
+
+> **[IMPLEMENTING AGENT — BEFORE SAVING] Have you filled in every section: completion table, changes from plan, design decisions, and verification output?**
+> If anything is blank, go back and fill it in before saving this file.
 ```
 
 Sections and their ownership:
 
-| 섹션 | 소유자 | 설명 |
-|------|--------|------|
-| 헤더 주석, 개요(date/task/plan/tag), 리뷰 에이전트 지시 | 스텁 생성 시 고정 | 구현 에이전트가 수정하지도, 수행하지도 않음 (아카이브·complete.log 생성은 리뷰 에이전트 전용) |
-| 구현 항목별 완료 여부 (항목명) | 스텁 생성 시 고정 | `[ ]` → `[x]` 체크만 구현 에이전트가 수행 |
-| 계획 대비 변경 사항, 주요 설계 결정 | 구현 에이전트가 채움 | placeholder 텍스트를 실제 내용으로 교체 |
-| 리뷰어를 위한 체크포인트 | 스텁 생성 시 고정 | 계획에서 추출한 리뷰 포인트 |
-| 검증 결과 (섹션 제목 + 명령) | 스텁 생성 시 고정 | 실행 출력만 구현 에이전트가 채움 |
-| 코드리뷰 결과 | 리뷰 에이전트가 append | 스텁에 포함하지 않음 |
+| Section | Owner | Note |
+|---------|-------|------|
+| Header comment, 개요, 리뷰 에이전트 지시 | Fixed at stub creation | Implementing agent must not modify or execute these (archive + complete.log are review-agent only) |
+| 구현 항목별 완료 여부 (item names) | Fixed at stub creation | Implementing agent checks `[ ]` → `[x]` only |
+| 계획 대비 변경 사항, 주요 설계 결정 | Implementing agent | Replace placeholder text with actual content |
+| 리뷰어를 위한 체크포인트 | Fixed at stub creation | Pre-filled from plan |
+| 검증 결과 (section headings + commands) | Fixed at stub creation | Implementing agent fills in command output only |
+| 코드리뷰 결과 | Review agent appends | Not included in stub |
 
 ## Naming