From 067af0aa6d6ae666913ebf15dd5fbd2d0dfbdb25 Mon Sep 17 00:00:00 2001 From: toki Date: Tue, 5 May 2026 10:30:39 +0900 Subject: [PATCH] update agent-ops/skills/common/plan/SKILL.md --- agent-ops/skills/common/plan/SKILL.md | 72 +++++++++++++++++++-------- 1 file changed, 51 insertions(+), 21 deletions(-) diff --git a/agent-ops/skills/common/plan/SKILL.md b/agent-ops/skills/common/plan/SKILL.md index cbdca81..b5e026e 100644 --- a/agent-ops/skills/common/plan/SKILL.md +++ b/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