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.

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 <fp>: 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, ask whether to split into smaller reviews or proceed.

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 when the panel is large (5+ agents across the Domain axis) or they asked for a dry-run.

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 <scope>"

• prompt:

  Diff to review: git diff <fp>...HEAD Commit list: <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 <scope>"

• 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): <list>

  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.