Autonomous Deep Review Loop
Iterative code review and quality auditing protocol with fresh context per iteration, externalized state, convergence detection, and severity-weighted findings (P0/P1/P2).
Runtime path resolution:
- OpenCode/Copilot runtime:
.opencode/agents/*.md - Claude runtime:
.claude/agents/*.md
Convergence threshold semantics and sibling-parity notes (deep-review 0.10 vs deep-research 0.05) live in references/convergence/convergence.md §1 under "Threshold Semantics and Sibling Parity".
1. WHEN TO USE
When to Use This Skill
Use this skill when:
- Code quality audit requiring multiple rounds across different review dimensions
- Spec folder validation requiring cross-reference checks between docs and implementation
- Release readiness check before shipping a feature or component
- Finding misalignments between spec documents and actual code
- Verifying cross-references across documentation, agents, commands, and code
- Iterative review where each dimension's findings inform subsequent dimensions
- Unattended or overnight audit sessions
When NOT to Use
- Simple single-pass code review (use
sk-code's code-review mode instead) - Known issues that just need fixing (go directly to implementation)
- Implementation tasks (use
sk-codeor/speckit:implement) - Quick one-file checks (use direct Grep/Read)
- Fewer than 2 review dimensions needed (single-pass suffices)
FORBIDDEN INVOCATION PATTERNS
This skill is invoked EXCLUSIVELY through the /deep:review command. The command's YAML workflow owns state, dispatch, and convergence.
NEVER:
- Write a custom bash/shell dispatcher to parallelize iterations (ad-hoc shell fan-out)
- Invoke any CLI executor (cli-codex, cli-claude-code, cli-opencode, cli-cursor, cli-devin, cli-pi, cli-deepseek-harness) directly in a loop to simulate iterations
- Manually write iteration prompts to
/tmpand dispatch them viacopilot -p - Dispatch the
@deep-reviewLEAF agent via the Task tool for iteration loops (the agent is LEAF, a single iteration, and MUST be driven by the command's workflow) - Skip the state machine:
deep-review-state.jsonl,deep-review-config.json,deltas/,prompts/,logs/ - Manage iteration state outside the resolved local review packet under
{spec_folder}/review/
COMMAND-DRIVEN FAN-OUT IS SUPPORTED: use --executor/--executors/--concurrency flags on /deep:review. The command's YAML step_fanout_spawn owns multi-lineage dispatch; fanout-merge.cjs applies strongest-restriction (any lineage with an active P0, or a required quality gate still failing at its stop → merged FAIL). This is not ad-hoc shell dispatch — it is the canonical fan-out path. Intra-lineage wave orchestration remains deferred.
ALWAYS:
- Invoke via
/deep:review :autoor/deep:review :confirm - Let the command's YAML workflow own dispatch (auto:
.skilled/commands/deep/assets/deep-review.yaml) - Record each leaf iteration through the append gateway (
runtime/scripts/append-mode-event.cjs --mode review --run-directory <spec folder> --event-json <file>) — the gateway is the SINGLE state-log writer: it authorizes, fences, and receipts the write, then refreshes{state_paths.state_log}from the ledger - Treat
runtime/scripts/reduce-state.cjsas the reducer for DERIVED artifacts only (finding registry, dashboard metrics, strategy updates); it never writes the state log - Require every iteration to produce BOTH the markdown narrative AND the JSONL delta (dispatch scripts must fail if either is missing)
- Use
resolveArtifactRoot(specFolder, 'review')from.skilled/skills/system-spec-kit/shared/review-research-paths.cjsto locate the canonical review root
Trigger Phrases
- "review code quality" / "audit this code"
- "audit spec folder" / "validate spec completeness"
- "release readiness check" / "pre-release review"
- "find misalignments" (between spec and implementation)
- "verify cross-references" (across docs and code)
- "deep review" / "iterative review" / "review loop"
- "quality audit" / "convergence detection"
Keyword Triggers
deep review, convergence review, iterative review, review loop, release readiness, spec folder review, convergence detection, quality audit, find misalignments, verify cross-references, pre-release review, audit spec folder
2. SMART ROUTING
The system-deep-loop hub routes an iterative review loop here, and its review mode signal selects this packet.
The signal fires when a request names a deep review, a convergence review, a review loop, a release readiness check or a spec-folder audit.
The loop runs only through /deep:review, whose workflow owns state, dispatch and convergence.
references/protocol/quick-reference.md loads first on every invocation.
The review phase named by the dispatch context then selects the loop protocol, the convergence documents or the state documents.
The routing pseudocode in ROUTER.md is the one route from a request to a resource set.
A request whose intent scores stay under the threshold returns UNKNOWN_FALLBACK with a disambiguation checklist, never a silent default.
Read ROUTER.md before selecting skill-local resources; open only the matched files.
3. HOW IT WORKS
Architecture
/deep:review owns the loop. The YAML workflow initializes state, dispatches one LEAF review iteration at a time, evaluates convergence, synthesizes review-report.md, and saves continuity. The LEAF agent reads state, reviews one dimension, writes iteration-NNN.md, updates strategy, and appends JSONL. Full 4-phase lifecycle: references/protocol/loop-protocol.md.
Resource Map Coverage Gate
When {spec_folder}/resource-map.md exists at init, deep review treats it as a mandatory audit input and does four things:
- Persists
resource_map_presentin config. - Seeds
Known Contextwith a snapshot of the map. - Has at least one iteration audit
target_filescoverage against the map: touched, not-touched withexpected-by-scope-versus-gap, and absent-from-map, with findings taggedresource-map-coverage. - Has synthesis add the
## Resource Map Coverage Gatereport section and a convergedresource-map.md. Disable this with--no-resource-map.
Absent at init, the gate and section are skipped without failing the loop.
Full sequencing: references/protocol/loop-protocol.md (init 9a, iteration 3b, synthesis 4). Schema: references/state/state-format.md.
Bounded Context Snapshot Replacement
During initialization, capture a bounded, pointer-based context snapshot in deep-review-strategy.md Known Context before the first dimension runs.
The snapshot holds:
- Target pointers: files, specs, symbols and resource-map entries.
- The claimed behavior and acceptance criteria to verify.
- Reuse and convention pointers.
- Risk areas, missing context, stale-graph caveats and out-of-scope areas.
Do not create a context-loop report or widen scope beyond the declared target.
Use @context for quick retrieval, and /speckit:plan only when findings require implementation planning.
State Packet Location
The review state packet always lives under the target spec's local review/ folder.
Root-spec targets use {spec_folder}/review/ directly.
Child-phase and sub-phase targets use flat-first placement: the first run writes flat, and a pt-NN sibling packet is allocated only when prior content already exists for a different target.
Full resolution rule and worked examples: references/state/state-format.md §1.
Core artifacts: deep-review-config.json, deep-review-state.jsonl, deep-review-strategy.md, deep-review-dashboard.md, .deep-review-pause, resource-map.md, review-report.md, and iterations/iteration-NNN.md.
The loop writes review/review-report.md itself at synthesis rather than scaffolding it through create.sh --level review.
The report is assembled from the findings registry and the JSONL state, so its content exists only once the loop has run, and a scaffolded skeleton would be overwritten whole.
create.sh --level review exists for a review packet authored by hand, and its template carries the same nine sections the loop emits.
Core Innovation: Fresh Context Per Iteration
Each agent dispatch gets a fresh context window; state continuity comes from files, not memory, preventing accumulated findings from biasing later dimensions. Init writes config/strategy/JSONL; each loop reads state, checks convergence, dispatches one dimension, records findings, and reduces state; synthesis compiles the report and saves continuity.
Review Dimensions
The four primary review dimensions (configured in assets/review-mode-contract.yaml):
| Dimension | Focus | Key Questions |
|---|---|---|
| Correctness | Logic, behavior, error handling | Behavior matches claims? Edge cases handled? |
| Security | Vulnerabilities, exposure, trust boundaries | Inputs validated? Credentials exposed? |
| Spec-Alignment / Traceability | Spec vs. implementation fidelity | Code matches spec.md? Planned items present? |
| Completeness / Maintainability | Coverage, dead code, documentation | TODOs resolved? Code self-documenting? |
Lifecycle + Reducer Contract
Review mode is lineage-aware.
- Lifecycle modes:
new,resume, andrestart. - Required lineage fields:
sessionId,parentSessionId,lineageMode,generation,continuedFromRun, andreleaseReadinessState. - Reducer contract: consumes the latest JSONL delta, the new iteration file, and prior reduced state, then emits finding registry, dashboard metrics, and strategy updates.
Severity Classification
| Severity | Criteria | Blocking |
|---|---|---|
| P0 | Correctness failure, security vulnerability, spec contradiction | Yes, blocks PASS verdict |
| P1 | Degraded behavior, incomplete implementation, missing validation | Conditional, triggers CONDITIONAL verdict |
| P2 | Style, naming, minor improvements, documentation gaps | No, PASS with advisories |
P0 and P1 also follow the reach calibration in sk-code-review's references/review-core.md §2.
A blocking finding names an input or call path the code's stated contract allows, or a real caller that sends the failing input.
"Missing validation" is P1 only when the unvalidated input is in reach. Validation the code never claimed, for input outside its stated contract, is P2 hardening.
At a trust boundary every value the outside can send is in reach.
The scale has exactly three tiers, and no fourth is reserved.
A severity outside P0/P1/P2 is not a fourth tier. That covers a P3 inherited from an older four-level convention, and any unlisted word.
Collapse it to the tier its impact actually matches (a P3 becomes P2) and keep the original rating visible in the finding, so the rating is converted rather than lost.
An unconverted out-of-scale severity reaches the cross-lineage merge unranked, where it sorts below every P2 and cannot raise the merged verdict.
Verdicts
| Verdict | Condition |
|---|---|
| PASS | No P0/P1 findings, P2 findings recorded as advisories (hasAdvisories: true) |
| CONDITIONAL | P1 findings present, remediation plan included in report |
| FAIL | Any P0 finding confirmed after adversarial self-check, or a required quality gate (evidence, scope, coverage) still failing at the terminal stop |
Acceptance-Coverage Signal
When the review target is a spec folder, deep review reflects the AC_COVERAGE validation signal in synthesis for Level 2+ folders.
The signal applies only once checklist.md exists and implementation-summary.md is in-progress or later. Level 1 folders and fresh scaffolds are exempt.
It is advisory while the validation rule stays INFO/default-on (non-blocking, and RULE_STATUS stays pass).
It can add traceability context and planning-seed work, but must not alter the iteration final-line contract below unless a later enforcement rollout explicitly changes severity.
Iteration Final-Line Contract (MANDATORY)
Every iteration-NNN.md MUST end with exactly one of the following plain-text lines as the absolute final line (no trailing whitespace, no variation), and every review MUST emit exactly one parseable verdict:
Review verdict: PASS
Review verdict: CONDITIONAL
Review verdict: FAIL
Mapping rule: PASS if no P0 or P1 findings in this iteration. CONDITIONAL if any P1 (but no P0) findings. FAIL if any P0 findings. P2-only findings → PASS.
VERDICT_LOCK: Any confirmed active P0 forces the exact final line Review verdict: FAIL -- never relabel that state as conditional, partial, mixed, or advisory, and truncated/partial output is not a valid substitute for the final line. An optional advisory riskScore may appear in narratives/JSONL for relative risk calibration but never changes the PASS|CONDITIONAL|FAIL mapping.
Downstream automation (including the synthesis phase and CI gate parser) parses this final line via exact string match, do not vary the format.
What the check proves: the post-dispatch verifier validates the shape of this line, and nothing more: exactly one well-formed verdict line, and it is final.
It does not read findings, so a PASS written above active P1 findings satisfies it, and no parser here makes the line true.
The verdict a release decision reads is recomputed from the findings registry.
In a fan-out run the cross-lineage merge is the authoritative rollup, where any active P0, or any lineage's required quality gate still failing at its stop, becomes a merged FAIL.
Treat the final line as the leaf's self-report and the registry as the record.
Executor Selection Contract
Executor settings are owned by the YAML workflow and rendered prompt pack -- never hand-dispatch review iterations; each iteration stays LEAF-only and produces the required markdown plus JSONL delta. Full contract (per-iteration invariants, failure modes, JSONL audit field, config surface/precedence, TrustState surface): references/protocol/loop-protocol.md.
Stop Decision, Counters and Limits
runtime/scripts/convergence.cjs computes the whole stop decision once per pass from the config, the state log, the findings registry and the coverage graph. deep-review.yaml renders no stop arithmetic of its own. The frozen stop reasons are converged, maxIterationsReached, blockedStop, manualStop, error, stuckRecovery, userPaused and maxDurationReached. A missing graph decision blocks every non-terminal STOP.
The stuck count and the consecutive failure count are rebuilt from the state log on every pass, so a resumed run counts the same as one that never paused. Failed iterations stay out of the ratio signals. Three trailing failed iterations stop the loop with stop reason error. In confirm mode only, the workflow first asks the operator Retry, Skip or Cancel. Auto mode has no such question.
Each pass also compares maxDurationMinutes with the config createdAt. When the limit is reached the loop skips the dispatch and goes to synthesis with stop reason maxDurationReached.
4. RULES
✅ ALWAYS
- Read JSONL and strategy before review action.
- Review one dimension per iteration and write findings to
iteration-NNN.md. - Append JSONL with severity counts, finding detail, and
newInfoRatio. - Cite every finding with
[SOURCE: file:line]. Reject inference-only findings. - Re-read cited code before recording any P0.
- Keep target files read-only.
- Use
generate-context.jsfor continuity saves. Owner: the workflow (deep-review.yaml) calls it at the save phase, not the reducer (runtime/scripts/reduce-state.cjs) directly — don't expect continuity-save side effects from the reducer alone. - Emit setup
BINDING:lines before workflow output. - Refuse nested dispatch with:
REFUSE: nested Task tool dispatch is forbidden for LEAF agents. Returning partial findings instead.
⛔ NEVER
- Dispatch sub-agents,
@deep-reviewis LEAF-only. It cannot dispatch additional agents. When dispatch is requested, use the canonical REFUSE wording (ALWAYS rule 9). - Hold findings in context, Write everything to iteration files. Context is discarded after each dispatch.
- Exceed TCB, Stay within
config.maxToolCallsPerIterationtool calls per iteration. Breadth over depth per cycle. - Ask the user, The leaf agent never asks. It makes best-judgment decisions without pausing. The workflow asks only in
:confirmmode, at its approval gates. - Skip convergence checks, Every iteration must be evaluated against convergence criteria before the next dispatch.
- Modify config after init, review parameters in
deep-review-config.jsonare read-only after initialization; the terminalstep_update_config_statusflip tostatus: completeis the one permitted write. - Modify files under review, The review loop is observation-only. No code changes during audit.
- Use WebFetch, Review is code-only. No external resource fetching is permitted.
- Implement fixes during review, Report findings only. Implementation is a separate follow-up step.
Iteration Status Enum
complete | timeout | error | stuck | insight
insight: Low newInfoRatio but important finding that changes the verdict trajectory.
⚠️ ESCALATE IF
- 3+ consecutive failed iterations, The loop stops with stop reason
errorand enters synthesis with partial findings. In confirm mode the workflow asks Retry, Skip or Cancel first. - State file corruption, Cannot reconstruct iteration history from JSONL or iteration files.
- All dimensions covered with P0 findings remaining, Human sign-off required before shipping.
- Security vulnerabilities discovered in production code, Escalate immediately. Do not defer to report synthesis.
- All recovery tiers exhausted, No automatic recovery path remaining in convergence protocol.
5. REFERENCES
The router discovers reference, asset and script docs dynamically. Start with these, in order:
references/protocol/quick-reference.mdreferences/protocol/loop-protocol.mdreferences/convergence/convergence.mdreferences/convergence/convergence-signals.mdreferences/state/state-format.mdreferences/state/state-outputs.mdreferences/state/state-reducer-registry.mdassets/deep-review-dashboard.mdassets/deep-review-strategy.md
Then load task-specific resources from references/, templates from assets/, and automation from scripts/ when present.
Scripts: runtime/scripts/reduce-state.cjs, scripts/runtime-capabilities.cjs.
Detailed contracts:
references/protocol/loop-protocol.md: executor invariants, failure modes and config surface.references/protocol/loop-state-and-gates.md: state transitions, error handling and STOP-decision gates.references/protocol/completion-criteria.md: the full loop-completion, quality-gate and validation-success checklist.references/state/state-reducer-registry.md: two-tier content-hash dedup.
6. SUCCESS CRITERIA
A review loop is complete only when convergence and every quality gate agree. All of these must hold:
- The composite stop score clears
compositeStopScore, ormaxIterationsis hit without a false-positive STOP. - Every configured dimension plus the required traceability protocols (
spec_code,checklist_evidence) has at least one full iteration of coverage. - All canonical state files exist and parse cleanly:
deep-review-config.json,deep-review-state.jsonl,deep-review-findings-registry.json,deep-review-strategy.mdanddeep-review-dashboard.md(a fan-out run keeps one per lineage instead), plus oneiterations/iteration-NNN.mdper dispatched iteration. review-report.mdcarries all 9 core sections plus the conditional## Resource Map Coverage Gate.- Continuity is saved via
generate-context.js.
Nine binary quality gates must all pass before STOP is legal:
- Config validity and lineage match.
- Strategy initialization completeness.
- State and registry consistency.
- Iteration completeness (markdown plus JSONL delta).
- Severity-field coverage on every finding (
severity/category/file:line/content_hash). - The advisory-only
riskScorenever gating verdict logic. - Adversarial P0 replay.
- Dimension and protocol coverage stability.
- Acceptance coverage: the advisory
AC_COVERAGEsignal when the spec-folder lifecycle predicate is active.
The security-sensitive override also applies when the target touches security, path handling, env precedence, schema boundaries, persistence or shared policy (minStabilizationPasses=2 plus fix-completeness replay).
Full gate-by-gate criteria and rationale: references/protocol/completion-criteria.md.
Validate a completed run with skill_advisor.py "run a deep review loop" --threshold 0.8 (skill still surfaces) and bash .skilled/skills/system-spec-kit/runtime/cli/spec/validate.sh <spec-folder> --strict (exits 0).
7. INTEGRATION POINTS
Framework Integration
This skill operates within the behavioral framework defined in the active runtime's root doc (CLAUDE.md or AGENTS.md).
Key integrations:
- Gate 2: Skill routing via
skill_advisor.py(keywords: deep review, convergence review, iterative review) - Gate 3: File modifications require spec folder question per the root doc Gate 3. The spec folder determines the
{spec_folder}/review/state packet location - Continuity:
/speckit:resumeis the operator-facing recovery surface, resolving context in the orderhandover.md -> _memory.continuity -> spec docs. During review, the agent writes iteration, strategy, and JSONL state; after synthesis, rungenerate-context.jsto write canonical packet continuity - Command:
/deep:reviewis the primary invocation point
Code Graph Integration
The review loop consumes the shared runtime graph and its strict mode-gate validator; packet-specific convergence and state rules remain in this skill.
Related Skills
Related skills: deep-research for investigation loops, sk-code's code-review mode for single-pass review doctrine, and system-spec-kit for command-owned state and continuity saves.