diff --git a/skills/in-progress/review/SKILL.md b/skills/in-progress/review/SKILL.md index 7507a36..e6c4001 100644 --- a/skills/in-progress/review/SKILL.md +++ b/skills/in-progress/review/SKILL.md @@ -22,6 +22,8 @@ Whatever the user said is the fixed point — a commit SHA, branch name, tag, `m Capture the diff command once: `git diff ...HEAD` (three-dot, so the comparison is against the merge-base). Also note the list of commits via `git log ..HEAD --oneline`. +Before going further, confirm the fixed point resolves (`git rev-parse `) and the diff is non-empty. A bad ref or empty diff should fail here — not inside two parallel sub-agents. + ### 2. Identify the spec source Look for the originating spec, in this order: @@ -33,16 +35,7 @@ Look for the originating spec, in this order: ### 3. Identify the standards sources -Anything in the repo that documents how code should be written. Common locations: - -- `CLAUDE.md`, `AGENTS.md` -- `CONTRIBUTING.md` -- `CONTEXT.md`, `CONTEXT-MAP.md`, per-context `CONTEXT.md` files -- `docs/adr/` (architectural decisions are standards) -- `.editorconfig`, `eslint.config.*`, `biome.json`, `prettier.config.*`, `tsconfig.json` (machine-enforced standards — note them but don't re-check what tooling already checks) -- Any `STYLE.md`, `STANDARDS.md`, `STYLEGUIDE.md`, or similar at the repo root or under `docs/` - -Collect the list of files. The **Standards** sub-agent will read them. +Anything in the repo that documents how code should be written, such as `CODING_STANDARDS.md` or `CONTRIBUTING.md`. ### 4. Spawn both sub-agents in parallel @@ -52,21 +45,21 @@ Send a single message with two `Agent` tool calls. Use the `general-purpose` sub - The full diff command and commit list. - The list of standards-source files you found in step 3. -- The brief: "Read the standards docs. Then read the diff. Report — per file/hunk where relevant — every place the diff violates a documented standard. Cite the standard (file + the rule). Distinguish hard violations from judgement calls. Skip anything tooling enforces. Under 400 words." +- The brief: "Report — per file/hunk where relevant — every place the diff violates a documented standard. Cite the standard (file + the rule). Distinguish hard violations from judgement calls. Skip anything tooling enforces. Under 400 words." **Spec sub-agent prompt** — include: - The diff command and commit list. - The path or fetched contents of the spec. -- The brief: "Read the spec. Then read the diff. Report: (a) requirements the spec asked for that are missing or partial; (b) behaviour in the diff that wasn't asked for (scope creep); (c) requirements that look implemented but where the implementation looks wrong. Quote the spec line for each finding. Under 400 words." +- The brief: "Report: (a) requirements the spec asked for that are missing or partial; (b) behaviour in the diff that wasn't asked for (scope creep); (c) requirements that look implemented but where the implementation looks wrong. Quote the spec line for each finding. Under 400 words." If the spec is missing, skip the Spec sub-agent and note this in the final report. ### 5. Aggregate -Present the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings — the two axes are deliberately separate so the user can see them independently. +Present the two reports under `## Standards` and `## Spec` headings, verbatim or lightly cleaned. Do **not** merge or rerank findings — the two axes are deliberately separate (see *Why two axes*). -End with a one-line summary: total findings per axis, and the worst single issue (if any) flagged. +End with a one-line summary: total findings per axis, and the worst issue _within each axis_ (if any). Don't pick a single winner across axes — that's the reranking the separation exists to prevent. ## Why two axes