deep-review

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 vs deep-ai-council 0.20) 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-code or /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 cli-opencode / cli-claude-code directly in a loop to simulate iterations
• Manually write iteration prompts to /tmp and dispatch them via copilot -p
• Dispatch the @deep-review LEAF 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 active P0 → 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 :auto or /deep:review :confirm
• Let the command's YAML workflow own dispatch (auto: .opencode/commands/deep/assets/deep-review-auto.yaml)
• Let scripts/reduce-state.cjs be the SINGLE state writer
• 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 .opencode/skills/system-spec-kit/shared/review-research-paths.cjs to 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

Resource Loading Levels

Smart Router Pseudocode

• Pattern 1: Runtime Discovery - discover_markdown_resources() recursively inventories references/ and assets/.
• Pattern 2: Existence-Check Before Load - load_if_available() guards markdown paths, checks inventory, and uses seen.
• Pattern 3: Extensible Routing Key - get_routing_key() derives the review phase from dispatch context.
• Pattern 4: Multi-Tier Graceful Fallback - UNKNOWN_FALLBACK returns review disambiguation and missing phases return a "no review resources" notice.

from pathlib import Path

SKILL_ROOT = Path(__file__).resolve().parent
RESOURCE_BASES = (SKILL_ROOT / "references", SKILL_ROOT / "assets")
DEFAULT_RESOURCE = "references/protocol/quick-reference.md"

INTENT_SIGNALS = {
    "REVIEW_SETUP":       {"weight": 4, "keywords": ["deep review", "review mode", "convergence review", "iterative review", ":review", "audit spec"]},
    "REVIEW_ITERATION":   {"weight": 4, "keywords": ["review iteration", "dimension review", "review findings", "P0", "P1", "P2"]},
    "REVIEW_CONVERGENCE": {"weight": 3, "keywords": ["review convergence", "coverage gate", "verdict", "binary gate", "all dimensions"]},
    "REVIEW_REPORT":      {"weight": 3, "keywords": ["review report", "remediation", "verdict", "release readiness", "planning packet"]},
}

NOISY_SYNONYMS = {
    "REVIEW_SETUP":       {"audit code": 2.0, "review spec folder": 1.8, "release readiness": 1.5, "pre-release": 1.5},
    "REVIEW_ITERATION":   {"review dimension": 1.5, "check correctness": 1.4, "check security": 1.4, "check alignment": 1.4},
    "REVIEW_CONVERGENCE": {"all dimensions covered": 1.6, "coverage complete": 1.5, "stop review": 1.4},
    "REVIEW_REPORT":      {"review results": 1.5, "what to fix": 1.4, "ship decision": 1.6, "final report": 1.5},
}

# RESOURCE_MAP: local markdown assets + local review-specific protocol docs
RESOURCE_MAP = {
    "REVIEW_SETUP":       [
        "references/protocol/loop-protocol.md",
        "references/state/state-format.md",
        "references/state/state-outputs.md",
        "references/state/state-reducer-registry.md",
        "assets/deep-review-strategy.md",
        "references/state/state-jsonl.md",
    ],
    "REVIEW_ITERATION":   [
        "references/protocol/loop-protocol.md",
        "references/convergence/convergence.md",
        "references/convergence/convergence-signals.md",
    ],
    "REVIEW_CONVERGENCE": [
        "references/convergence/convergence.md",
        "references/convergence/convergence-signals.md",
        "references/state/state-outputs.md",
        "references/protocol/completion-criteria.md",
        "references/protocol/loop-state-and-gates.md",
        "references/convergence/convergence-recovery.md",
    ],
    "REVIEW_REPORT":      [
        "references/state/state-format.md",
        "references/state/state-outputs.md",
        "references/state/state-reducer-registry.md",
        "assets/deep-review-dashboard.md",
    ],
}

LOADING_LEVELS = {
    "ALWAYS":            [DEFAULT_RESOURCE],
    "ON_DEMAND_KEYWORDS": ["full protocol", "all templates", "complete reference", "resume deep review", "deep-review wave", "review artifact", "release-readiness audit", "convergence-tracked", "same session lineage", "P0"],
    "ON_DEMAND":         [
        "references/protocol/loop-protocol.md",
        "references/state/state-format.md",
        "references/convergence/convergence.md",
        "references/convergence/convergence-signals.md",
        "references/state/state-outputs.md",
        "references/state/state-reducer-registry.md",
    ],
}

PHASE_RESOURCE_MAP = {
    "init": ["references/protocol/loop-protocol.md", "references/state/state-format.md", "references/state/state-outputs.md"],
    "iteration": ["references/protocol/loop-protocol.md", "references/convergence/convergence.md", "references/convergence/convergence-signals.md"],
    "stuck": ["references/convergence/convergence.md", "references/convergence/convergence-signals.md", "references/protocol/loop-protocol.md", "references/state/state-reducer-registry.md"],
    "synthesis": ["references/state/state-format.md", "references/state/state-outputs.md", "references/state/state-reducer-registry.md", "assets/deep-review-dashboard.md"],
}

NON_MARKDOWN_REFERENCES = {
    "review_contract": "assets/review-mode-contract.yaml",
}

UNKNOWN_FALLBACK_CHECKLIST = [
    "Confirm the review target or spec folder",
    "Confirm the review phase",
    "Provide one concrete file, diff range, or expected finding class",
    "Confirm the verification command set before final review",
]

def _guard_in_skill(relative_path: str) -> str:
    resolved = (SKILL_ROOT / relative_path).resolve()
    resolved.relative_to(SKILL_ROOT)
    if resolved.suffix.lower() != ".md":
        raise ValueError(f"Only markdown resources are routable: {relative_path}")
    return resolved.relative_to(SKILL_ROOT).as_posix()

def discover_markdown_resources() -> set[str]:
    docs = []
    for base in RESOURCE_BASES:
        if base.exists():
            docs.extend(path for path in base.rglob("*.md") if path.is_file())
    return {doc.relative_to(SKILL_ROOT).as_posix() for doc in docs}

def get_routing_key(dispatch_context) -> str:
    phase = str(getattr(dispatch_context, "phase", "")).strip().lower()
    if phase:
        return phase
    text = str(getattr(dispatch_context, "text", "")).lower()
    if "recovery" in text:
        return "stuck"
    if "convergence" in text or "synthesis" in text:
        return "synthesis"
    if "iteration" in text or "dimension" in text:
        return "iteration"
    return "init"

def route_review_resources(task, dispatch_context):
    inventory = discover_markdown_resources()
    routing_key = get_routing_key(dispatch_context)
    scores = score_intents(task, INTENT_SIGNALS, NOISY_SYNONYMS)
    intents = select_intents(scores, ambiguity_delta=1.0)

    loaded = []
    seen = set()

    def load_if_available(relative_path: str) -> None:
        guarded = _guard_in_skill(relative_path)
        if guarded in inventory and guarded not in seen:
            load(guarded)
            loaded.append(guarded)
            seen.add(guarded)

    for relative_path in LOADING_LEVELS["ALWAYS"]:
        load_if_available(relative_path)

    if max(scores.values() or [0]) < 0.5:
        return {
            "routing_key": routing_key,
            "load_level": "UNKNOWN_FALLBACK",
            "needs_disambiguation": True,
            "disambiguation_checklist": UNKNOWN_FALLBACK_CHECKLIST,
            "resources": loaded,
        }

    phase_resources = PHASE_RESOURCE_MAP.get(routing_key, [])
    if routing_key == "unknown" or not phase_resources:
        return {
            "routing_key": routing_key,
            "notice": f"No review resources found for routing key '{routing_key}'",
            "resources": loaded,
        }

    for intent in intents:
        for relative_path in RESOURCE_MAP.get(intent, []):
            load_if_available(relative_path)

    for relative_path in phase_resources:
        load_if_available(relative_path)

    task_text = str(getattr(task, "text", "")).lower()
    if any(keyword in task_text for keyword in LOADING_LEVELS["ON_DEMAND_KEYWORDS"]):
        for relative_path in LOADING_LEVELS["ON_DEMAND"]:
            load_if_available(relative_path)

    return {
        "routing_key": routing_key,
        "intents": intents,
        "resources": loaded,
        "non_markdown_references": NON_MARKDOWN_REFERENCES,
    }

Phase Detection

Detect the current review phase from dispatch context to load appropriate resources:

3. HOW IT WORKS

Resource Map Coverage Gate

When {spec_folder}/resource-map.md exists at init, deep review treats it as a mandatory audit input: resource_map_present is persisted in config, a map snapshot seeds Known Context, at least one iteration audits target_files coverage against the map (touched / not-touched expected-by-scope-vs-gap / absent-from-map, findings tagged resource-map-coverage), and synthesis adds the ## Resource Map Coverage Gate report section plus a converged resource-map.md (disable via --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: target pointers (files, specs, symbols, resource-map entries), claimed behavior/acceptance criteria to verify, reuse/convention pointers, and risk areas, missing context, stale-graph caveats, and out-of-scope areas. It must 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.

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.

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 (first run writes flat, 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.

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

Lifecycle + Reducer Contract

Review mode is lineage-aware. Supported lifecycle modes are new, resume, and restart. Required lineage fields include sessionId, parentSessionId, lineageMode, generation, continuedFromRun, and releaseReadinessState. The reducer consumes the latest JSONL delta, the new iteration file, and prior reduced state, then emits finding registry, dashboard metrics, and strategy updates.

Severity Classification

Verdicts

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, and only once checklist.md exists and implementation-summary.md is in-progress or later (Level 1 folders and fresh scaffolds are exempt). The signal is advisory while the validation rule stays INFO/default-on (non-blocking; 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.

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.

4. RULES

✅ ALWAYS

1. Read JSONL and strategy before review action.
2. Review one dimension per iteration and write findings to iteration-NNN.md.
3. Append JSONL with severity counts, finding detail, and newInfoRatio.
4. Cite every finding with [SOURCE: file:line]. Reject inference-only findings.
5. Re-read cited code before recording any P0.
6. Keep target files read-only.
7. Use generate-context.js for continuity saves. Owner: the YAML workflow (deep_review_{auto,confirm}.yaml) calls it at the save phase, not the reducer (scripts/reduce-state.cjs) directly — don't expect continuity-save side effects from the reducer alone.
8. Emit setup BINDING: lines before workflow output.
9. Refuse nested dispatch with: REFUSE: nested Task tool dispatch is forbidden for LEAF agents. Returning partial findings instead.

⛔ NEVER

1. Dispatch sub-agents, @deep-review is LEAF-only. It cannot dispatch additional agents. When dispatch is requested, use the canonical REFUSE wording (ALWAYS rule 14).
2. Hold findings in context, Write everything to iteration files. Context is discarded after each dispatch.
3. Exceed TCB, Target 8-11 tool calls per iteration (max 12). Breadth over depth per cycle.
4. Ask the user, Autonomous execution. The agent makes best-judgment decisions without pausing.
5. Skip convergence checks, Every iteration must be evaluated against convergence criteria before the next dispatch.
6. Modify config after init, deep-review-config.json is read-only after initialization.
7. Modify files under review, The review loop is observation-only. No code changes during audit.
8. Use WebFetch, Review is code-only. No external resource fetching is permitted.
9. 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

1. 3+ consecutive timeouts, Infrastructure issue. Pause loop and report to user.
2. State file corruption, Cannot reconstruct iteration history from JSONL or iteration files.
3. All dimensions covered with P0 findings remaining, Human sign-off required before shipping.
4. Security vulnerabilities discovered in production code, Escalate immediately. Do not defer to report synthesis.
5. All recovery tiers exhausted, No automatic recovery path remaining in convergence protocol.

5. REFERENCES AND RELATED RESOURCES

The router discovers reference, asset, and script docs dynamically. Start with references/protocol/quick-reference.md, references/protocol/loop-protocol.md, references/convergence/convergence.md, references/convergence/convergence-signals.md, references/state/state-format.md, references/state/state-outputs.md, references/state/state-reducer-registry.md, assets/deep-review-dashboard.md, assets/deep-review-strategy.md, then load task-specific resources from references/, templates from assets/, and automation from scripts/ when present.

Scripts: scripts/reduce-state.cjs, scripts/runtime-capabilities.cjs.

Detailed contracts: references/protocol/loop-protocol.md (executor invariants, failure modes, config surface), references/protocol/loop-state-and-gates.md (state transitions, error handling, STOP-decision gates), references/protocol/completion-criteria.md (full loop-completion/quality-gate/validation-success checklist), and references/state/state-reducer-registry.md (two-tier content-hash dedup).

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.

6. SUCCESS CRITERIA

A review loop is complete only when convergence and every quality gate agree: the composite stop score clears compositeStopScore (or maxIterations is hit without a false-positive STOP), every configured dimension plus required traceability protocols (spec_code, checklist_evidence) have 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.md, deep-review-dashboard.md, one iterations/iteration-NNN.md per dispatched iteration), review-report.md carries all 9 core sections plus the conditional ## Resource Map Coverage Gate, and continuity is saved via generate-context.js.

Nine binary quality gates must all pass before STOP is legal: config validity + lineage match, strategy initialization completeness, state/registry consistency, iteration completeness (markdown + JSONL delta), severity-field coverage on every finding (severity/category/file:line/content_hash), the advisory-only riskScore never gating verdict logic, adversarial P0 replay, dimension/protocol coverage stability, acceptance-coverage (advisory AC_COVERAGE signal when the spec-folder lifecycle predicate is active), and the security-sensitive override (minStabilizationPasses=2 + fix-completeness replay) when the target touches security, path handling, env precedence, schema boundaries, persistence, or shared policy. 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 .opencode/skills/system-spec-kit/scripts/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:resume is the operator-facing recovery surface, resolving context in the order handover.md -> _memory.continuity -> spec docs. During review, the agent writes iteration, strategy, and JSONL state; after synthesis, run generate-context.js to write canonical packet continuity
• Command: /deep:review is 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.