Panel Review

Panel review

A workflow skill. The user has just changed code (or explicitly asked for a review), and the change needs to be reviewed across four orthogonal axes — spec adherence, project standards, independent test adequacy, and specialist domain expertise — with each axis able to disagree with the others without being silenced.

Proactive trigger discipline. This skill is meant to auto-fire after implementation, not on every chat message. Fire when there's a plausible code-change checkpoint — a finished feature, a fixed bug, a landed refactor, an "I think that's done" — but not on conversation, questions, planning, or tiny one-line edits the user clearly didn't want reviewed. When in doubt, run a quick git diff --stat and ask: "Want me to run a panel review on this?" rather than firing unilaterally on an ambiguous message.

Each axis catches a different failure mode:

• Spec catches "implements the wrong thing well". Standards and Domain both pass; the diff just doesn't do what the issue asked.
• Standards catches "implements the right thing the wrong way for this repo". Spec passes; the conventions are broken.
• Test adequacy catches "the implementation and tests agree on a weaker contract". It checks observable AC coverage, negative-test mutation value, boundary cases, and whether the tests exercise the real seam.
• Domain catches "implements the right thing with a hidden landmine". Spec and Standards pass; a security, K8s, library, or duplication issue lurks.

Reporting them separately is deliberate. Synthesised together, one axis masks another. Inspired by Matt Pocock's two-axis /review skill (Standards + Spec), generalised with a Domain axis powered by the project's installed specialist reviewer agents.

Operating modes

Interactive mode (default): keep the confirmation behavior below: ask when no fixed point/spec is available, the diff is large, or the Domain panel has 5+ agents.

Orchestrator mode: /plan-orchestrate supplies the fixed point and spec. Do not pause for confirmation because the diff or panel is large; announce the scope and proceed. Keep the same bounded briefs and selected panel, record any missing source or reviewer failure, and always finish with the stable PANEL: line. All other interactive behavior is unchanged outside this mode.

Prerequisites

• Working directory is a git repository (or files were explicitly named).
• At least one of: a spec source (issue / PRD), project standards docs (CLAUDE.md, etc.), or one or more reviewer agents installed at .claude/agents/ or ~/.claude/agents/. One axis is enough to run.
• gh CLI installed if reviewing a PR by number or fetching issue bodies.

Step 1 — Pin the fixed point

The fixed point is what we're diffing against. Whatever the user said is the fixed point — a commit SHA, branch name, tag, origin/main, HEAD~5, a PR number, an explicit file list. Don't be opinionated; pass it through.

If the user didn't specify, ask before proceeding:

Review against what — a branch (main?), a commit, "since I started this branch", or a PR number?

Do not silently auto-detect. The whole review hangs on this and a wrong guess wastes the panel's effort.

Once pinned, capture once and reuse:

• Diff command: git diff <fp>...HEAD (three-dot — compares against the merge-base, which is what "what did this branch change?" means).
• Commit list: git log <fp>..HEAD --oneline (used to find issue/spec references).
• File list: git diff <fp>...HEAD --name-only.

Print to the user:

Reviewing against : N files, M insertions, L deletions, K commits. <file list, capped at 20 with "+N more">

If the diff is empty, ask for explicit file paths or a PR number.

If the diff is > 50 files or > 3000 lines, interactive mode asks whether to split into smaller reviews or proceed. Orchestrator mode proceeds without confirmation and keeps every reviewer brief bounded.

Step 2 — Read project context

In one parallel batch, read the repository's instruction and standards sources: CLAUDE.md/AGENTS.md (including parents), .claude/rules/*.md, relevant architecture/design/ADR indexes, SECURITY.md, CONTRIBUTING.md, and any CONTEXT.md/CONTEXT-MAP.md files that exist.

Step 3 — Detect the spec source

The Spec axis needs to know what was asked for. Look in this order:

1. Issue references in commit messages. Parse git log <fp>..HEAD --format=%B for #123, Closes #45, Fixes GH-67, gitlab !89, JIRA-100, LIN-1234. Fetch the issue body via gh issue view <N> (or the project's docs/agents/issue-tracker.md workflow if present).

2. A path the user passed as an argument — "review against spec at docs/specs/foo.md".

3. PRD / spec files under conventional locations matching the branch name or feature: docs/specs/<name>.md, docs/prd/<name>.md, specs/<name>.md, .scratch/<name>.md, docs/acceptance/<name>.md.

4. If nothing is found, ask the user:

   I don't see a spec or issue reference for this branch. Path to a spec, or skip the Spec axis?

If the Spec axis is skipped, note it in the final output as "Spec axis: no source available — skipped" with the reason. Do not fabricate a spec.

Step 4 — Inventory standards sources

The Standards axis needs to know what conventions this repo documents. Collect filenames (the Standards subagent will read them):

• CLAUDE.md, AGENTS.md, CONTRIBUTING.md
• CONTEXT.md, CONTEXT-MAP.md, per-directory CONTEXT.md files
• docs/adr/*.md (architectural decisions ARE standards)
• STYLE.md, STANDARDS.md, STYLEGUIDE.md at repo root or under docs/
• .claude/rules/*.md
• docs/design/principles.md if present

Explicit skip rule (inherited from Matt's design): tell the Standards subagent not to re-check anything enforced by detected formatter, linter, type-checker, compiler, or project tooling configs (for example .editorconfig, ESLint/Biome/Prettier/TypeScript, .golangci.yml, pyproject Ruff/Black/mypy, rustfmt/clippy). Re-flagging tool-enforced rules wastes tokens.

If no standards docs are found, note "Standards axis: no project standards docs found — axis returned an empty report" in output; don't skip the axis silently.

Step 5 — Inventory the available domain panel

List .claude/agents/*.md and ~/.claude/agents/*.md. Parse each file's description field (frontmatter).

Build a table:

This is the domain panel of available specialist reviewers. Don't fabricate agents that aren't installed — if a dimension has no matching agent, note the gap rather than skip the dimension silently.

Step 6 — Classify the diff (Domain axis)

For each file in the diff, identify the domain dimensions that apply. The mapping below is a default; project-specific agents take precedence over generic ones when their scope matches.

If no Domain agent is available (including a pure-docs diff), mark Domain axis: unavailable — no applicable installed specialist and still fan out Spec, Standards, and Test adequacy. Domain unavailability is not a reviewer failure.

Classification rules:

• Always include secure-code-reviewer for diffs touching application code with external trust boundaries.
• software-architect is the default architecture reviewer for any non-trivial code diff — cross-language design plus the language-architecture role when no language-specific architect is installed.
• Project-specific architects in the repo's .claude/agents/ compose with software-architect rather than replacing it. Both can run on the same diff: the project-specific one carries domain-loaded invariants and ADR knowledge, software-architect carries the cross-cutting design lens.
• code-duplication-reviewer and library-reuse-reviewer are DEFAULT-ON for any non-trivial code diff (any diff touching application logic — not pure-docs / pure-config). Do NOT gate them on "a new dependency was added" or "actual duplication shape is already visible". Their entire job is to FIND the duplication and the reinvented stdlib that ISN'T obvious from the diff surface; gating them on the signal already being visible skips them on exactly the diffs where they add the most value. When in doubt, include both — they default to silence when they find nothing. The reuse pair is cheap insurance against the most common over-build failure mode an agent introduces (reinvented stdlib, speculative abstraction, unrequested layer). See the reuse-ladder brief in Step 8.
• Pure-docs diffs skip the Domain axis (Spec axis may still run).
• Pure-test diffs: a single Domain reviewer (project's test-review agent if present, else language architect).

Step 7 — Announce the four-axis plan

Reviewing against <fp>: N files, M insertions, L deletions, K commits.

Spec axis:       checking against #123 ("Add /preview endpoint")
Standards axis:  reading CLAUDE.md, .claude/rules/, docs/adr/
                 skipping tooling: golangci-lint, biome, prettier
Test adequacy:   independently tracing requirements to assertions and seams
Domain axis (running in parallel):
  - secure-code-reviewer        — auth/HTTP/SSRF surface in api/handlers/
  - kubernetes-deployment-expert — deploy/staging/ manifests
  - devops-expert               — .github/workflows/release.yml changes
  - library-reuse-reviewer      — default-on: reinvented stdlib / over-build
  - code-duplication-reviewer   — default-on: duplication across the diff

Skipping (no diff in scope):
  - kubernetes-operator-expert

Gaps (dimension detected, no matching agent installed):
  - (none)

Wait for user pushback only in interactive mode when the panel is large (5+ agents across the Domain axis) or they asked for a dry-run. Orchestrator mode proceeds immediately.

Step 8 — Fan out (PARALLEL)

In a single assistant turn, issue all of:

• 1 × Agent call for the Spec axis (general-purpose subagent with brief).
• 1 × Agent call for the Standards axis (general-purpose subagent with brief).
• 1 × Agent call for the Test adequacy axis (general-purpose subagent with brief).
• N × Agent calls for the Domain panel (named specialist agents).

They run concurrently, separate contexts, no order dependencies.

Spec subagent

• subagent_type: general-purpose

• description: "Spec adherence check for "

• prompt:

  Diff to review: git diff <fp>...HEAD Commit list: Spec source: <path or inline contents of the issue/PRD>

  Read the spec carefully, then read the diff. Report:

  1. Missing — requirements the spec asked for that the diff doesn't implement, or only partially implements.
  2. Scope creep — behaviour added by the diff that the spec didn't ask for.
  3. Wrong — requirements that look implemented but where the implementation appears incorrect against the spec.

  Quote the specific spec line / requirement for each finding. Classify every finding explicitly as blocker, important, or advisory: blocker = must fix before merge; important = concrete non-blocking fix; advisory = judgement/polish. Under 400 words. Default to silence when uncertain — only flag concrete mismatches.

  Root-cause discipline: when a finding names a symptom, note whether the diff fixes the root cause or only the path the ticket names — a sibling caller may still be broken.

If no spec source was found in Step 3, skip this call and note in final output.

Standards subagent

• subagent_type: general-purpose

• description: "Standards conformance check for "

• prompt:

  Diff to review: git diff <fp>...HEAD Standards source files (read these): <list from Step 4> Tooling-enforced configs to SKIP (tooling already runs on every commit; do not re-flag what they cover):

  Read the standards docs, then the diff. Report — per file / hunk where relevant — every place the diff violates a documented standard. Cite the standard (file + the rule). Classify every finding explicitly as blocker, important, or advisory: blocker = must fix before merge; important = concrete non-blocking fix; advisory = judgement/polish. Under 400 words. Default to silence when uncertain.

Test-adequacy subagent

• subagent_type: general-purpose

• description: "Independent test-adequacy check for "

• prompt:

  Diff to review: git diff <fp>...HEAD Spec source: <path or inline contents; state unavailable if skipped> Acceptance plan / verify contract:

  Review tests independently of the implementation. Trace each requirement or AC to an assertion at the lowest adequate layer. Flag missing or weaker coverage, tests that cannot fail on regression, negative assertions without a planted violation, fake-only tests that bypass the real seam, and missing boundary/failure cases. Do not re-report style or implementation findings. Classify findings as blocker, important, or advisory and cite test paths and requirement/AC ids. Under 400 words; default to silence when adequate.

For a pure-docs or pure-config diff with no executable behavior contract, mark this axis not applicable; that is a deliberate skip, not a reviewer failure.

Domain agents

For each specialist in the panel:

• subagent_type: the agent's name field.
• description: " review of ".
• prompt:
  • The exact diff scope (git diff <fp>...HEAD -- <paths>).
  • A one-line statement of what the agent should focus on, derived from its own description.
  • The project-context items the agent's body needs.
  • Reminder: "Respect your calibration discipline — flag only findings that affect correctness, security, or stated requirements. Classify every finding as blocker, important, or advisory. Map your native severity deterministically: Critical/High = blocker, Medium = important, Low/Info = advisory. Default action when uncertain is silence."

Reuse pair — extra brief (library-reuse-reviewer + code-duplication-reviewer). When fanning out the default-on reuse pair, append the reuse-ladder brief from references/reuse-ladder.md to each of their prompts so they review systematically rather than ad-hoc. The brief gives them the 7-rung reuse ladder (Does this need to exist? → Already in codebase? → Stdlib? → Native platform? → Installed dep? → One line? → Minimum), the delete:/stdlib:/native:/ yagni:/shrink: tag vocabulary, the net: -<N> lines possible. score, and root-cause discipline (grep every caller, fix the shared function once). Read the reference file and paste the brief block into each reuse agent's prompt.

Set run_in_background: false (default) so synthesis blocks on completion.

If the environment or the user has expressed a model preference, honour it on each Agent call.

Step 9 — Four-axis output + machine result

Do NOT merge findings across axes. They are deliberately orthogonal — one passing while another fails is exactly the information you want to preserve. Cross-axis merging is the failure mode Matt's design exists to prevent.

For the Spec, Standards, and Test adequacy axes, present each subagent's explicitly classified findings verbatim or lightly cleaned. Don't rerank or infer a classification from prose. An unclassified finding is a reviewer failure to retry, not a countable finding.

For the Domain axis only, synthesise across the panel:

Synthesis (Domain axis only)

1. Combined table — every finding from every domain agent, preserving its source severity and its required panel classification. Domain mapping is exhaustive: Critical/High → blocker, Medium → important, Low/Info → advisory; missing or unknown severity/classification is a reviewer failure.
2. Dedup — two findings are duplicates when they share location AND underlying issue. Merge with Sources: [A, B] and tag as cross-confirmed (highest-confidence — multiple specialists independently reached the same conclusion).
3. Prioritise — Critical → High → Medium → Low → Info; within severity, cross-confirmed before single-source; within that, by file path.
4. Tag for action class without changing the explicit panel class:
   • Ship-blockers — Domain blocker findings; must address before merge.
   • Mechanical fixes — clear path, no judgement.
   • Judgement calls — architectural trade-offs.
   • Polish — optional.

Final output structure

Render the report following the template in references/output-template.md. The prose rules above (don't merge across axes; synthesis within Domain only) govern; the template is the shape.

End every report with exactly one machine-readable line, with no prose after it:

PANEL: ship_blockers=<n> important=<n> advisory=<n> reviewer_failures=<n>

Count only explicit classifications. Each Spec, Standards, and Test-adequacy finding counts once in its declared class. Domain duplicates are deduplicated as above and each resulting Domain finding counts once by the exhaustive native severity mapping; cross-axis findings remain distinct because the axes are orthogonal. Never infer severity from category names or prose. reviewer_failures counts agents that errored, timed out, or returned findings without the required classification; a documented unavailable/not-applicable/ skipped axis is not a failure. Values are non-negative base-10 integers. This line is the stable automation contract; prose is not.

Step 10 — Offer follow-up

Offer one short follow-up immediately before emitting the final PANEL: line (the machine line remains the last line):

• "Apply mechanical fixes now?" → suggest /simplify
• "Drill into a specific finding?" → user names one
• "Post these as inline PR comments?" → suggest /pr-review-post if installed
• "Address the Spec misalignment first?" → user redirects work
• "Ship as-is" → user accepts the report

Don't loop on synthesis. The panel ran once; the report stands.

What this skill does NOT do

• Doesn't modify code. Synthesis is a report.
• Doesn't merge findings across axes — Spec, Standards, Test adequacy, and Domain are orthogonal by design; one masking another is the failure mode this skill exists to prevent.
• Doesn't fan out to every available Domain agent regardless of diff — irrelevant reviewers waste tokens and add noise. (The reuse pair is the exception: default-on for non-trivial code diffs, because over-engineering is the most common agent failure mode and the signal is rarely visible on the diff surface.)
• Doesn't duplicate the built-in /code-review skill's single-pass logic.
• Doesn't override the user's choice of agents.
• Doesn't auto-detect the fixed point — always pin it explicitly (asking if needed).
• Doesn't fabricate a spec if none exists. Skips the Spec axis with a noted reason instead.
• Doesn't re-check rules that project tooling (linters, formatters, type-checkers) already enforces.
• Doesn't fire on every chat message just because trigger keywords appear. Plausible code-change checkpoint required: a finished feature, a fixed bug, a landed refactor. Pure-question messages, planning conversations, and trivial one-line edits don't trigger. When ambiguous, ask the user before fanning out the panel.

Error handling

See also

• Reuse-ladder brief
• Output template
• Matt Pocock's /review
• Claude Code best practices
• Sub-agents reference
• Bundled /code-review (single pass) and /code-review ultra (cloud panel)