From 2e647324f90f36b4c8ef8cbca0bbda89b2a82434 Mon Sep 17 00:00:00 2001 From: Matt Pocock Date: Wed, 17 Jun 2026 14:29:34 +0100 Subject: [PATCH] =?UTF-8?q?refine:=20Tighten=20review=20skill=20=E2=80=94?= =?UTF-8?q?=20fail-fast=20ref=20check,=20single-sourced=20rules,=20no-op?= =?UTF-8?q?=20cuts?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - Validate the fixed point resolves and diff is non-empty before spawning sub-agents - Single-source the tooling-enforced and two-axis rationale (point to Why two axes) - Fix rerank contradiction: summarize worst issue per axis, not across axes - Drop dead "Read X, then read the diff" preambles from both briefs Co-Authored-By: Claude Opus 4.8 (1M context) --- skills/in-progress/review/SKILL.md | 21 +++++++-------------- 1 file changed, 7 insertions(+), 14 deletions(-) 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