Review Report

Review Report

> Single-pass: invoke once, get either a findings-first review report or a single error. No retry, no interactive clarification, no manual fanout fallback, no override flags. The user reads .review-report.md and decides ship / no-ship / iterate.

What this is

review-report is a review execution + aggregation orchestrator. It reads .review.md (produced by code-review-plan), spawns ≤8 read-only reviewer subagents in parallel (batching in waves if there are more shards), collects each subagent's strict shard report into .review-report/.md, then aggregates findings into a findings-first .review-report.md.

Lightweight orchestration; complexity lives in subagent instructions + result schema, not in workflow state machines.

What this is NOT

• Not a code reviewer itself. Subagents review code; the main agent only spawns them and aggregates their structured returns.
• Not an editor. Does NOT edit code, source plan, TLDR, scope, debug log, or review plan.
• Not a test runner. Subagents do NOT run tests unless a shard explicitly grants that capability.
• Not auto-handoff. Does NOT auto-create BUG-* IDs (suggests them); does NOT auto-rerun siblings (recommends them); does NOT auto-ship.
• Not a workflow engine. No retry loop, no interactive clarification mid-run, no manual fallback, no override flags. Single-pass.

Relationship to sibling skills

code-review-plan produces the brief; review-report executes against it. Routing back to debug-log (new bugs found), PLAN.md (drift surfaced), or tldr-plan / scope-triage (rerun needed) is recommendation-only — the human acts on the routing fields, the skill never auto-triggers.

When not to use

• .review.md doesn't exist — run code-review-plan first.
• .review.md has Review readiness other than READY — resolve the listed issues and rerun code-review-plan first.
• You only want to brief the fleet without running the review — use code-review-plan alone.
• You want a human reviewer fleet — this skill spawns AI subagents only.

Source-of-truth rule

PLAN.md is authoritative. .review.md is the brief that defines shard scope and the report contract. .debug.md provides recurrence-risk context. Subagents must use evidence from these artifacts plus the code; fabrication is forbidden (use evidence-gap rows instead).

Invocation

• /review-report @PLAN.md
• /review-report @PLAN.md "" — optional free-text note. Recorded in §0 as run context only; it does NOT change shard selection, parallelism, or any other behavior. v1 always runs all shards listed in .review.md §6 — no subset-execution, no shard skipping. (To narrow scope, rerun code-review-plan with a smaller scope first.)
• /review-report current plan
• /review-report (uses current plan)

Refuse-list: paths ending in .tldr.md, .scope.md, .debug.md, .review.md, .review-report.md, or under .review-report/ are rejected with a directive to rerun on the source plan.

No flags: no --force, no --parallelism. The free-text note is recorded as run context only — it does NOT override readiness, shard selection, batching, or tool policy.

Output files

Two outputs:

• Sidecar dir: /.review-report/.md — one file per shard subagent report (e.g., .review-report/R01.md). Created by the skill; subagents return content, the main agent writes the file.
• Final report: /.review-report.md — aggregated findings-first report.

If the input plan is read-only / outside the workspace, write to ./ in CWD with a console note. If no plan supplied, fall back to ./current-plan.review-report.md + ./current-plan.review-report/.

Overwrite rules

• Final .review-report.md: overwrite-from-scratch on every run.
• Per-shard sidecar files: overwrite per-shard on rerun (each shard re-reviewed independently).
• Iteration happens by re-running code-review-plan (which may reshape shards) and then re-running review-report. Never evolve the report files in place.

Subagent fan-out rule (single-pass, fail-fast, deterministic batching)

• Run 5 reviewer subagents per batch by default. If the total shard count is ≤8, the skill may run all shards in one batch. Never exceed 8 parallel subagents. No flag to override.
• Take shard rows from .review.md §6 in order. No priority-sort logic, no reordering.
• The default of 5 is conservative: AI review is context-hungry, and a smaller batch produces more focused reviewers.
• All batches complete before final aggregation.
• Fail-fast if subagent spawning is unavailable. The skill assumes the runtime supports direct subagent spawning (e.g., Claude Code's Agent tool). If spawning is unavailable, stop before writing any output with a clear single-line reason. Do NOT emit prompt files for the user to run by hand. Do NOT degrade to a manual workflow.
• No --parallelism flag, no manual override, no fallback mode. The skill is single-pass.

Subagent rules

Full template + tool allowlist in references/subagent-instructions.md. Summary:

• Each subagent receives a bounded shard-specific prompt — only the data needed for that shard. Context isolation is the whole point of using subagents.
• Subagents are read-only by default. Tool allowlist: Read, Grep, Glob, read-only Bash subset (git diff, git log, git show, find, grep, wc, head, tail, cat). Forbidden by default: Edit, Write, NotebookEdit, write-mode Bash, test runners. Per-shard escalation requires explicit annotation in the shard's Required tests / evidence field.
• Subagents must return exactly the strict shard report schema (see references/shard-report-schema.md). Malformed output is marked by the schema check (Workflow Step 3); the main agent still writes the sidecar with Status: MALFORMED, surfaces it as an evidence gap, and continues aggregation.
• Subagents must NOT review outside their assigned shard, NOT edit files, NOT fix bugs, NOT auto-trigger anything.

Workflow

4 steps, single-pass; no retry, no interactive clarification, no manual handoff in the middle.

1. Read review brief. Resolve PLAN.md and .review.md. Stop if .review.md is missing or its Review readiness is not READY. (NEEDS_INPUT / BLOCKED → tell the human to rerun code-review-plan after resolving the listed issues; do NOT introduce an override flag.)
2. Run shard reviewers. For each review shard in .review.md §6, spawn one read-only reviewer subagent. Run 5 reviewer subagents per batch by default. If the total shard count is ≤8, the skill may run all shards in one batch. Never exceed 8 parallel subagents. Take shard rows in §6 order (no priority-sort). All batches complete before final aggregation. Each subagent receives only its shard-specific inputs (per references/subagent-instructions.md) and must return the strict shard report schema (per references/shard-report-schema.md). If the runtime cannot spawn subagents, fail fast with one clear reason — do NOT degrade to a manual workflow.
3. Persist shard reports. Two failure modes, recorded distinctly:

• MALFORMED (subagent returned but schema check failed): write .review-report/.md with Status: MALFORMED + a one-line reason prepended; surface the shard as an evidence gap in §3 of the final report and route it to BLOCKED_BY_MISSING_EVIDENCE in aggregation.
• MISSING (subagent never returned — timed out, refused, runtime error mid-spawn): do NOT create a sidecar file at all; record the shard as MISSING in §0 / §3 / §10 of the final report and route it to BLOCKED_BY_MISSING_EVIDENCE in aggregation.

Schema check is behavioral, not a parser script. Do not retry. Do not spawn a fix-up subagent.

1. Aggregate findings. Apply the rules in references/aggregation-rules.md: deduplicate conservatively (≥2-signal rule), preserve evidence verbatim, group by severity then finding type, extract debug-log updates and PLAN revision suggestions as recommendation lists (no auto-actions), compute final recommendation per the severity-tally rule. Write .review-report.md per references/output-layout.md — findings-first, with Review Coverage near the bottom.

Style rules

• Final report is findings-first. §0 Decision Summary, §1 Blocking Findings, §2 High Findings come BEFORE §8 Review Coverage.
• Background-rich findings: every BLOCKER and HIGH finding MUST include background (why the invariant matters), expected behavior, the finding itself, evidence, impact, recommended action, and routing. A finding that only says "X is broken" is invalid. Full rules in references/finding-rules.md.
• Anchor canonicality: same as code-review-plan — canonical anchors are plan-level (AC* / C* / D* / E* / M* / A*); F* may appear as optional navigation refs only, never in Plan anchors: fields.
• Tables for findings index, evidence gaps, debug-log updates, PLAN revisions.
• unknown markers when a subagent reported missing evidence; never invent.
• Dashboard short-rule: if §0 + §8 bookkeeping outweighs §1–§3 findings, compress bookkeeping.

Quality checklist

Before finalizing the artifact, verify:

• File path is /.review-report.md + sidecar dir .review-report/.
• Final report has Report readiness: ∈ {COMPLETE, INCOMPLETE (some shards malformed/missing)}. Input-blocked cases (review-plan missing or Review readiness != READY, runtime can't spawn subagents) fail before writing the report — they do NOT produce a BLOCKED_AT_INPUT artifact; the user gets a single chat error reason instead.
• Subagent count ≤8 per batch.
• Every shard in .review.md §6 has a corresponding sidecar file (or is explicitly recorded as MISSING in §0 / §10).
• Every BLOCKER and HIGH finding in §1 / §2 has all 7 required fields (Background, Expected behavior / invariant, Finding, Evidence, Impact, Recommended action, Routing).
• Findings-first order: §0 / §1 / §2 / §3 BEFORE §8.
• Final recommendation ∈ {APPROVE, APPROVE_WITH_FOLLOWUPS, NEEDS_FIX, BLOCKED} (matches code-review-plan's aggregation contract).
• Missing or malformed required shard → Final recommendation: BLOCKED (per references/aggregation-rules.md).
• No source-plan / TLDR / scope / debug / review-plan edits.
• No auto-creation of BUG-* IDs (only suggestions in §4 Debug-log Updates Required).
• No auto-rerun of any sibling skill (only recommendations).

What NOT to do

• Don't spawn >8 parallel subagents.
• Don't grant subagents write tools.
• Don't aggregate without the schema check.
• Don't edit any source artifact.
• Don't auto-fix bugs.
• Don't auto-create BUG-* IDs in debug-log.
• Don't auto-rerun tldr-plan / scope-triage.
• Don't write a coverage-first report (findings-first is mandatory).
• Don't accept findings that lack background (invalid per finding-rules.md).
• Don't add per-cause Review readiness: enums (use the 2-value Report readiness: plus dashboard bullets).
• Don't introduce a manual-fanout fallback, a prompt-export mode, or any sidecar subdirectories (prompts/, pending/, manual/, raw/). Sidecar dir contains exactly .md files — nothing else.
• Don't retry a malformed subagent. Don't spawn a fix-up agent. The malformed sidecar + §3 Evidence Gap row is the entire failure path.
• Don't add --force, --parallelism, or any other flag. The free-text invocation note is the only override channel (and it's audit-only — does not change behavior).
• Don't ask the user mid-run. Single-pass means: invoke once, get a result.

References

This skill is part of the shared plan-artifact pipeline. See .claude/skills/README.md (or claude-skills/skills/README.md) for the overview.

Read these only when needed (per progressive disclosure):

• references/subagent-instructions.md — bounded reviewer-subagent prompt template + tool allowlist + spawn rules + failure handling
• references/shard-report-schema.md — strict per-shard report schema + behavioral schema-check rules
• references/finding-rules.md — what makes a finding valid (background rule), severity rules, finding-type guidance, routing rules, evidence-gap rules
• references/aggregation-rules.md — collection, dedup, grouping, extraction, final-recommendation tally
• references/output-layout.md — final report layout (findings-first §0–§10) + per-section field specs

Examples:

• examples/input-review-plan.md — minimal .review.md with 3 shards (router zero-active suspend example chain)
• examples/input-shard-report-r01.md — R01 reviewer return: NEEDS_FIX with one HIGH remove_worker recurrence finding
• examples/input-shard-report-r02.md — R02 reviewer return: PASS_WITH_NOTES with one MEDIUM finding
• examples/output-review-report.md — aggregated .review-report.md showing R01 + R02 + R03-MISSING (BLOCKED final recommendation)

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: taoluo
• Source: taoluo/claude-skills
• License: MIT

Install and usage instructions live in the source repository linked above.