review

name	review
description	Runs an independent multi-dimension review of completed work and adversarially verifies every finding before reporting it.

Review

Freedom: LOW — dispatch all four reviewers for the initial audit, then freeze scope and the finding ledger.

Overview

Dispatch four specialized reviewer agents to independently audit completed work once, then dispatch a dedicated verifier sub-agent to kill-or-keep each finding and freeze the survivors into a review ledger. Remediation closes that ledger; it does not restart an open-ended audit.

The verification work is delegated to a dedicated verifier sub-agent, not done in the main context. Main context's job is dispatch + assembly; the verifier's job is ruthless kill-or-keep classification. This split follows Anthropic's CitationAgent pattern and avoids the synthesizer becoming context-starved from juggling four simultaneous roles (dispatch, verify, dedup, implement).

Works in epic or standalone workflow context; either context has an initial-audit phase and a bounded closure phase:

• Epic review: When an epic Task exists, conformance checks against epic requirements and success criteria
• Task review: When reviewing standalone work (debugging, refactoring), conformance checks against the workflow Task's goal and success criteria

• Epic review: When this root transcript contains an approved epic contract, conformance checks against its requirements and success criteria
• Workflow review: For standalone work, conformance checks against the complete workflow brief and checkpoint in this root transcript

Core principle: Review is adversarial and broad once; closure is adversarial and narrow until the frozen findings are resolved.

Announce at start: "I'm using gambit:review to validate this implementation before finishing."

Quick Reference

Step	Action	STOP If

| 1. Detect Context | Epic Task/workflow Task + any open review ledger | Can't find either context | | 2. Load Context | Task + changed files list | Can't load task |

| 1. Detect Context | Approved contract/brief + any open review ledger in this root transcript | Same-session context is absent | | 2. Load Context | Complete contract/brief + changed files list | Context is incomplete |

| 3. Freeze Boundary | Requirements + base revision + review snapshot + changed hunks | Boundary incomplete | | 4. Dispatch Reviewers | Initial audit only: 4 agents in parallel, each reading instructions by path | Any agent fails to run | | 5. Scope + Dedupe | Reject out-of-boundary candidates; byte-identical dedupe only | — | | 6. Dispatch Verifier | 1 verifier sub-agent with the deduped candidate list | Verifier fails to run | | 7. Freeze Ledger | Confirmed findings become the complete, immutable blocker set | — | | 8. Remediate / Close | Fix ledger items; re-verify only open IDs + original gates | Evidence fails |

| 9. Gate | APPROVED or OPEN LEDGER with verification counts | Ledger remains open → fix tasks, STOP |

| 9. Gate | APPROVED or OPEN LEDGER with verification counts | Ledger remains open → fix briefs and a later wave, STOP |

When to Use

• All epic subtasks show "completed" (called automatically by gambit:executing-plans Step 5)

• Every native wave step is completed (called automatically by gambit:executing-plans Step 5)

• After gambit:refactoring completes changes (mandatory)
• Before gambit:finishing-branch
• Any time you want independent review of completed work

Don't use when:

• Tasks still in progress → use gambit:executing-plans

• A native wave is pending or in progress → use gambit:executing-plans

• Mid-implementation, per-task quality check → that's the executing-plans checkpoint quality gate's job (it reuses this skill's quality reviewer, scoped to one diff, when it escalates). This skill is the multi-dimension end-of-epic backstop, not the per-task gate.

The Process

Step 1: Detect Context

First detect an open Review Closure Ledger in the current workflow state. A ledger is open when a prior review recorded confirmed finding IDs and has not recorded terminal closure for all of them.

• Open ledger found → closure mode. Skip Steps 3–5 and all four finders. Load the frozen boundary and only the still-open ledger entries, then continue at Step 6 with mode: closure.
• No open ledger → initial mode. Determine what you're reviewing against below and run the full audit.

An old APPROVED report is not an open ledger. A ledger is invalidated only when the user explicitly changes requirements or authorizes implementation outside the recorded remediation boundary; then record why and begin a new initial review. Incidental scope creep is not a reason to restart review — remove it or return it to the worker.

Epic context (default when epic exists):

TaskList → find epic Task (subject starts with "Epic:")
TaskGet → epic (requirements, success criteria, anti-patterns)
TaskList → all subtasks (verify all completed)

Task context (refactoring or standalone work):

TaskList → find the workflow Task (most recent in-progress or just-completed Task)
TaskGet → task (goal, implementation steps, success criteria)

The review brief adapts based on which context is detected. If both exist (e.g., a refactor during an epic), prefer the epic context. Detect an open ledger from the prior review checkpoint and its fix Tasks before creating a new audit.

Use SessionContextRead in this root session to detect context:

Epic context (default when a complete approved epic contract exists):

SessionContextRead → approved epic contract (requirements, success criteria, anti-patterns)
SessionPlanRead → concise wave steps; verify every wave is completed
SessionContextRead → latest checkpoint and native subagent results for individual worker completion

Workflow context (refactoring or standalone work with no epic contract):

SessionContextRead → complete workflow brief and checkpoint result (goal, implementation steps, success criteria)

The review brief adapts based on which same-session context exists. If both exist, prefer the epic context. Detect an open ledger from the prior review checkpoint in this root transcript; plan steps never carry it. Never search plan steps for an epic selector or individual worker record.

Step 2: Load Context

For epic context:

TaskGet → epic (requirements, success criteria, anti-patterns)
TaskList → all subtasks (verify all completed)

For task context:

TaskGet → workflow task (goal, success criteria)

For epic context: use SessionContextRead for the full approved contract and latest checkpoint, and SessionPlanRead only to verify every concise wave step is completed.

For workflow context: use SessionContextRead for the complete workflow brief and checkpoint result.

Initial mode, both contexts: freeze exact revisions before dispatch:

git merge-base main HEAD            # review_base
git rev-parse HEAD                  # review_snapshot
git diff <review_base>..<review_snapshot> --name-only
git diff --unified=0 <review_base>..<review_snapshot>  # frozen changed hunks

If tracked or untracked implementation changes are absent from review_snapshot, STOP. The audited snapshot must contain everything intended for merge.

Step 3: Freeze Boundary and Prepare Brief

Build a brief that each reviewer agent will receive. Include:

For epic context:

1. Epic requirements — full text from TaskGet (requirements, success criteria, anti-patterns)

1. Epic requirements — full text from the approved contract returned by SessionContextRead (requirements, success criteria, anti-patterns)

2. Changed files — the --name-only output
3. Base branch — what the diff is against

For task context:

1. Task goal and success criteria — full text from TaskGet

1. Workflow goal and success criteria — full text from the workflow brief returned by SessionContextRead

2. Changed files — the --name-only output
3. Base branch — what the diff is against
4. Context type indicator — "This is a task-level review (debugging/refactoring), not an epic review. Evaluate against the task's stated goal and success criteria."

Both contexts also include a frozen Review Boundary:

• review_base and review_snapshot
• exact changed files and zero-context changed hunks between those revisions
• explicit requirements/success criteria from the approved contract or workflow brief
• this rule: every finding must anchor to a line changed in that frozen diff, including missing-test/docs/config findings via the changed line that creates the obligation

Commit history, checkpoint formatting, transcript/process compliance, unchanged code, and "while I was reading" observations are outside the gate unless an explicit approved requirement names them. Report such observations separately; they cannot become candidates, ledger entries, fix work, or reasons to restart review.

Do NOT include your opinions, implementation notes, or rationale. The reviewers should form their own conclusions from the code.

Before any finder dispatch, validate that the frozen Review Brief contains the actual frozen diff hunks from review_base..review_snapshot. An empty or missing hunk set is a composition failure: stop the review before any finder dispatch, and never dispatch a finder with nothing to review.

Step 4: Dispatch Four Reviewers

Resolve the absolute path to this skill's reviewers/ directory once (Glob **/skills/review/reviewers/conformance.md if you don't already know it). You pass this path to the agents — do NOT read the reviewer files into this context. The four reviewer files are ~8k tokens; reading them here and re-emitting them as prompts wastes ~18k tokens every review. Each agent reads its own instruction file in its own fresh context.

Rung resolution (Claude only)

Resolve the finder role through contracts/models.md exactly once, before emitting any of the four calls. All four dimensions run on that one resolved rung — never resolve per dimension and never mix rungs inside one audit. Finders are advisory and read-only, so an agent rung uses the rung's readonly_agent.

Finder dispatch

Native Codex finder dispatch

In ONE message, emit exactly four finder calls on that one resolved rung. A model rung emits four general-purpose Agent calls with model: set to the rung's alias — set it explicitly, never inherit; an agent rung emits four calls on the rung's readonly_agent with no model: at all. Each prompt is just: (1) a directive to read and follow that agent's instruction file by path, then (2) the review brief.

Agent subagent_type="general-purpose" model="<finder rung alias — contracts/models.md>" description="Conformance review" prompt="Read <abs>/reviewers/conformance.md — that file is your complete instructions; your FIRST action must be to Read it, then follow it exactly.\n\n## Review Brief\n\n[brief]"
Agent subagent_type="general-purpose" model="<finder rung alias — contracts/models.md>" description="Security review"    prompt="Read <abs>/reviewers/security.md — that file is your complete instructions; your FIRST action must be to Read it, then follow it exactly.\n\n## Review Brief\n\n[brief]"
Agent subagent_type="general-purpose" model="<finder rung alias — contracts/models.md>" description="Quality review"     prompt="Read <abs>/reviewers/quality.md — that file is your complete instructions; your FIRST action must be to Read it, then follow it exactly.\n\n## Review Brief\n\n[brief]"
Agent subagent_type="general-purpose" model="<finder rung alias — contracts/models.md>" description="Performance review" prompt="Read <abs>/reviewers/performance.md — that file is your complete instructions; your FIRST action must be to Read it, then follow it exactly.\n\n## Review Brief\n\n[brief]"

In ONE message, emit exactly four general-purpose Agent calls, each at the finder tier (model: resolved per contracts/models.md — default most-capable, because a missed finding is unrecoverable; set model: explicitly, never inherit). Each prompt is just: (1) a directive to read and follow that agent's instruction file by path, then (2) the review brief.

Agent subagent_type="general-purpose" model="<finder tier — see contracts/models.md>" description="Conformance review" prompt="Read <abs>/reviewers/conformance.md — that file is your complete instructions; your FIRST action must be to Read it, then follow it exactly.\n\n## Review Brief\n\n[brief]"
Agent subagent_type="general-purpose" model="<finder tier — see contracts/models.md>" description="Security review"    prompt="Read <abs>/reviewers/security.md — that file is your complete instructions; your FIRST action must be to Read it, then follow it exactly.\n\n## Review Brief\n\n[brief]"
Agent subagent_type="general-purpose" model="<finder tier — see contracts/models.md>" description="Quality review"     prompt="Read <abs>/reviewers/quality.md — that file is your complete instructions; your FIRST action must be to Read it, then follow it exactly.\n\n## Review Brief\n\n[brief]"
Agent subagent_type="general-purpose" model="<finder tier — see contracts/models.md>" description="Performance review" prompt="Read <abs>/reviewers/performance.md — that file is your complete instructions; your FIRST action must be to Read it, then follow it exactly.\n\n## Review Brief\n\n[brief]"

Parallelism is structural, not a reminder. That single message contains four calls on the once-resolved finder rung and nothing else: no Read calls, no prose between them. Reading one reviewer file before each dispatch is exactly what forces the agents sequential; passing paths removes the read step, so there's nothing left to interleave. If you catch yourself using Read on a reviewer file, you've reverted to the old serializing pattern — stop and dispatch by path.

Parallelism is structural, not a reminder. That single message contains four native SpawnAgent calls and nothing else: no file reads, no prose between them. Reading one reviewer file before each dispatch is exactly what forces the agents sequential; passing paths removes the read step, so there's nothing left to interleave. If you catch yourself reading a reviewer file here, you've reverted to the old serializing pattern — stop and dispatch by path.

Each reviewer will:

• Read the changed files independently
• Evaluate their dimensions with evidence
• Fetch documentation or references from the web when local knowledge is insufficient or the code is sensitive/complex
• Attach a **Verify by:** line to every Gap and Improvement (required — see each reviewer file's "Verification Requirement" section)
• Return findings as APPROVED or GAPS FOUND

Critical: Reviewers are strictly advisory. They must NOT run tests, execute commands, or edit files. All tests are already passing by the time review runs — their job is code analysis only. They DO have access to WebFetch and WebSearch and should use them to validate edge cases, check API documentation, verify security patterns, or confirm language-specific behavior when they aren't confident from code reading alone.

Critical: Reviewers are strictly advisory. They must NOT run tests or edit files. Local inspection is limited to the bounded commands and locations in each reviewer contract. Use live web search to validate edge cases, check API documentation, verify security patterns, or confirm language-specific behavior when local knowledge is insufficient.

Step 5: Scope-Filter and Dedupe Candidate Findings

Collect the four reviewer reports into one candidate list. Each finding carries a **Verify by:** line; assign each finding an opaque id (any stable string — reviewer name + sequence works).

Apply the frozen boundary mechanically before verification. A candidate is eligible only when its cited anchor intersects a changed hunk in review_base..review_snapshot, or an explicit requirement directly names the non-code artifact it cites. Put rejected items in a non-blocking Out of scope audit trail with the failed boundary check. Do not send them to the verifier and do not create work from them.