feat(review): consolidate output into one numbered report with best-practices checks (#210)

Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>
Co-authored-by: Oscar <martinm.oscar@gmail.com>

Author: 3 people

CLAUDE.md

@@ -43,17 +43,24 @@ Supporting skills:
 Quality-review agents:
 
 - `vgv-review-agent`
-- `code-simplicity-review-agent`
-- `test-quality-review-agent`
 - `architecture-review-agent`
+- `test-quality-review-agent`
+- `code-simplicity-review-agent`
+- `pr-readiness-review-agent`
+
+Each agent writes a detailed report to a `raw/` subdirectory and returns a structured
+findings list. The calling skill deduplicates and orders those findings, assigns stable
+`FINDING-NN` ids (plus a stable `<category>/<rule>` id per finding for acting on a whole
+class), and renders one consolidated report plus a matching chat summary (see
+`skills/shared/references/review-consolidation.md`).
 
 ## Output Directories
 
 - `docs/brainstorm/` — Brainstorm documents from `/brainstorm`
 - `docs/plan/` — Implementation plans from `/plan`
-- `docs/reviews/` — Review reports from `/build` (ephemeral, cleaned up by build)
-- `docs/hotfix-review/` — Review reports from `/hotfix` (ephemeral, cleaned up by hotfix)
-- `docs/code-review/` — Review reports from `/review` (standalone, user-managed)
+- `docs/reviews/` — Consolidated `review.md` + per-agent `raw/` from `/build` (ephemeral, cleaned up by build)
+- `docs/hotfix-review/` — Consolidated `review.md` + per-agent `raw/` from `/hotfix` (ephemeral, cleaned up by hotfix)
+- `docs/code-review/` — One `<slug>/` directory per run (`review.md` + per-agent `raw/`) from `/review` (standalone, user-managed)
 - `docs/debriefs/` — Debrief documents from `/debrief`
 
 ## Hooks

README.md

@@ -67,7 +67,7 @@ Execute the plan — write code, write tests, run quality review, and open a PR:
 
 ### 4. `/review`
 
-Automated review against best practices, test coverage, accessibility, and performance. Catches issues before they reach PR.
+Runs specialized agents in parallel — VGV standards, architecture, test quality, and simplicity. Findings land in one consolidated report with stable `FINDING-NN` ids, and the chat summary mirrors it so you can act on any finding by number. Catches issues before they reach PR.
 
 As simple as this:
 

agents/codebase-review/code-simplicity-review-agent.md

@@ -96,9 +96,7 @@ Remember: Perfect is the enemy of good. The simplest code that works is often th
 
 ## Output Instructions
 
-If a file path is specified in your task prompt, write your full review to that file path and return ONLY a brief summary to the caller covering:
-- Verdict (ready to merge / needs work / needs rethink)
-- Count of critical and important issues
-- One-line description of each critical issue
-
-If no file path is specified, return the full review in your response as usual.
+Follow the review agent instructions provided in your task prompt: write the full report to
+the given raw report path, then return only the structured findings list — not the full
+report text, and with no finding ids (the caller assigns those). If no report path is
+provided, return the full review in your response.

agents/codebase-review/vgv-review-agent.md

@@ -278,9 +278,7 @@ Remember these principles throughout every review:
 
 ## Output Instructions
 
-If a file path is specified in your task prompt, write your full review to that file path and return ONLY a brief summary to the caller covering:
-- Verdict (ready to merge / needs work / needs rethink)
-- Count of critical and important issues
-- One-line description of each critical issue
-
-If no file path is specified, return the full review in your response as usual.
+Follow the review agent instructions provided in your task prompt: write the full report to
+the given raw report path, then return only the structured findings list — not the full
+report text, and with no finding ids (the caller assigns those). If no report path is
+provided, return the full review in your response.

agents/quality-review/architecture-review-agent.md

@@ -141,9 +141,7 @@ For each new or modified package, verify:
 
 ## Output Instructions
 
-If a file path is specified in your task prompt, write your full review to that file path and return ONLY a brief summary to the caller covering:
-- Verdict (ready to merge / needs work / needs rethink)
-- Count of critical and important issues
-- One-line description of each critical issue
-
-If no file path is specified, return the full review in your response as usual.
+Follow the review agent instructions provided in your task prompt: write the full report to
+the given raw report path, then return only the structured findings list — not the full
+report text, and with no finding ids (the caller assigns those). If no report path is
+provided, return the full review in your response.

agents/quality-review/pr-readiness-review-agent.md

@@ -116,9 +116,7 @@ Items that can be resolved automatically:
 
 ## Output Instructions
 
-If a file path is specified in your task prompt, write your full review to that file path and return ONLY a brief summary to the caller covering:
-- Verdict (ready to merge / needs work / needs rethink)
-- Count of critical and important issues
-- One-line description of each critical issue
-
-If no file path is specified, return the full review in your response.
+Follow the review agent instructions provided in your task prompt: write the full report to
+the given raw report path, then return only the structured findings list — not the full
+report text, and with no finding ids (the caller assigns those). If no report path is
+provided, return the full review in your response.

agents/quality-review/test-quality-review-agent.md

@@ -140,9 +140,7 @@ Flag these immediately:
 
 ## Output Instructions
 
-If a file path is specified in your task prompt, write your full review to that file path and return ONLY a brief summary to the caller covering:
-- Verdict (ready to merge / needs work / needs rethink)
-- Count of critical and important issues
-- One-line description of each critical issue
-
-If no file path is specified, return the full review in your response as usual.
+Follow the review agent instructions provided in your task prompt: write the full report to
+the given raw report path, then return only the structured findings list — not the full
+report text, and with no finding ids (the caller assigns those). If no report path is
+provided, return the full review in your response.

config/cspell.json

@@ -5,6 +5,7 @@
     "glab",
     "codegen",
     "conventionalcommits",
+    "diffstat",
     "lockfiles",
     "frontmatter",
     "geolocation",

skills/build/SKILL.md

@@ -22,7 +22,7 @@ Build Progress:
 - [ ] Phase 0: Load plan and confirm scope
 - [ ] Phase 1: Read context files
 - [ ] Phase 2: Implement, test, and run the surgical-diff gate
-- [ ] Phase 3: Run review agents (5 in parallel)
+- [ ] Phase 3: Run review agents (5 in parallel), consolidate into one report
 - [ ] Phase 4: Final validation, cleanup, and ship
 ```
 
@@ -110,21 +110,25 @@ After all implementation tasks are complete, run 5 review agents **in parallel**
 
 ### Agent instructions
 
-Each agent prompt must include the [review agent instructions](references/review-agent-instructions.md) with `REPORT_DIR` set to `docs/reviews/`.
+Run `pwd` and let `<PWD>` be the result — subagents may change directories, making relative paths unreliable.
 
-The 5 agents and their report filenames:
+Each agent prompt must include the [review agent instructions](references/review-agent-instructions.md) with `<RAW_DIR>` set to `<PWD>/docs/reviews/raw` and `<name>` set to the agent's report name below (a bare stem — the agent writes `<RAW_DIR>/<name>.md`). Substitute `<PWD>` with the absolute path.
 
-| Agent | Report file |
+The 5 agents and their report names (`<name>`):
+
+| Agent | Report name |
 | ----- | ----------- |
-| **@vgv-review-agent** | `docs/reviews/vgv-review.md` |
-| **@code-simplicity-review-agent** | `docs/reviews/code-simplicity-review.md` |
-| **@test-quality-review-agent** | `docs/reviews/test-quality-review.md` |
-| **@architecture-review-agent** | `docs/reviews/architecture-review.md` |
-| **@pr-readiness-review-agent** | `docs/reviews/pr-readiness-review.md` |
+| **@vgv-review-agent** | `vgv-review` |
+| **@architecture-review-agent** | `architecture-review` |
+| **@test-quality-review-agent** | `test-quality-review` |
+| **@code-simplicity-review-agent** | `code-simplicity-review` |
+| **@pr-readiness-review-agent** | `pr-readiness-review` |
+
+If an agent fails, note it, continue with the rest, and record the failure in the report header.
 
 ### After all reviews complete
 
-Follow the [review consolidation procedure](references/review-consolidation.md): categorize findings, auto-fix minor issues, fix critical issues, present important issues to the user, and record suggestions.
+Follow the [review consolidation procedure](references/review-consolidation.md): deduplicate the agents' structured findings, order them deterministically, assign stable `FINDING-NN` ids, and write **one** consolidated file to `<PWD>/docs/reviews/review.md` using the [report template](references/review-report-template.md). Print the aligned chat summary (same ids, order, and titles as the file). Then act: auto-fix minor issues, fix Critical findings by id, present Important findings to the user, and note any still-deferred findings in the PR description.
 
 ## Phase 4 — Ship
 
@@ -152,7 +156,9 @@ Stage all implementation and fix changes. Use this commit format:
 Implements <plan title or summary>.
 ```
 
-Where `<type>` matches the plan's type (`feat`, `fix`, `refactor`, etc.).
+Where `<type>` matches the plan's type (`feat`, `fix`, `refactor`, etc.). Review findings are
+fixed in place during Phase 3 and the report is deleted at Cleanup, so the commit does not
+cite `FINDING-NN` ids (there would be no report left to map them to).
 
 ### Ship
 
@@ -170,7 +176,7 @@ Use **AskUserQuestion** to present options:
 - If tests fail mid-build, fix the failing test before moving to the next task. Do not accumulate broken tests across tasks.
 - Generated files (mocks, codegen output) must be regenerated after code changes — stale generated files cause confusing test failures.
 - If the plan specifies file paths that conflict with existing files, confirm with the user before overwriting. The codebase may have changed since the plan was written.
-- Review agent reports are written to `docs/reviews/` and deleted after Phase 4. If the build is interrupted, stale reports may remain — delete them manually before the next run.
+- The consolidated report (`docs/reviews/review.md`) and per-agent raw reports (`docs/reviews/raw/`) are deleted after Phase 4. If the build is interrupted, stale reports may remain — delete `docs/reviews/` manually before the next run.
 
 ## Important
 

skills/build/references/review-report-template.md

@@ -0,0 +1 @@
+../../shared/references/review-report-template.md