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/agent/*.md
• Claude runtime: .claude/agents/*.md
• Codex runtime: .codex/agents/*.toml

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--review instead)
• Known issues that just need fixing (go directly to implementation)
• Implementation tasks (use sk-code--opencode or /spec_kit:implement)
• Quick one-file checks (use direct Grep/Read)
• Fewer than 2 review dimensions needed (single-pass suffices)

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, code audit, 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

from pathlib import Path

SKILL_ROOT = Path(__file__).resolve().parent
LOCAL_REFS   = SKILL_ROOT / "references"
LOCAL_ASSETS = SKILL_ROOT / "assets"
DEFAULT_RESOURCE = "references/quick_reference.md"

INTENT_SIGNALS = {
    "REVIEW_SETUP":       {"weight": 4, "keywords": ["deep review", "review mode", "code audit", "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 assets + local review-specific protocol docs
RESOURCE_MAP = {
    "REVIEW_SETUP":       [
        "references/loop_protocol.md",
        "references/state_format.md",
        "assets/review_mode_contract.yaml",
        "assets/deep_review_strategy.md",
    ],
    "REVIEW_ITERATION":   [
        "references/loop_protocol.md",
        "references/convergence.md",
        "assets/review_mode_contract.yaml",
    ],
    "REVIEW_CONVERGENCE": [
        "references/convergence.md",
        "assets/review_mode_contract.yaml",
    ],
    "REVIEW_REPORT":      [
        "references/state_format.md",
        "assets/review_mode_contract.yaml",
    ],
}

LOADING_LEVELS = {
    "ALWAYS":            [DEFAULT_RESOURCE],
    "ON_DEMAND_KEYWORDS": ["full protocol", "all templates", "complete reference"],
    "ON_DEMAND":         [
        "references/loop_protocol.md",
        "references/state_format.md",
        "references/convergence.md",
    ],
}

Scoped Guard

def _guard_in_skill():
    """Verify this skill is active before loading resources."""
    if not hasattr(_guard_in_skill, '_active'):
        _guard_in_skill._active = True
    return _guard_in_skill._active

Phase Detection

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

3. HOW IT WORKS

Architecture: 3-Layer Integration

User invokes: /spec_kit:deep-review "target"
                    |
                    v
    ┌─────────────────────────────────┐
    │  /spec_kit:deep-review command  │  Layer 1: Command
    │  (YAML workflow + loop config)    │  Manages loop lifecycle
    └──────────────┬──────────────────┘
                   |
                   v
    ┌─────────────────────────────────┐
    │     YAML Loop Engine            │  Layer 2: Workflow
    │  - Init (config, strategy)       │  Dispatch, evaluate, decide
    │  - Loop (dispatch + converge)   │
    │  - Synthesize (review-report)   │
    │  - Save (memory context)        │
    └──────────────┬──────────────────┘
                   |  dispatches per iteration
                   v
    ┌─────────────────────────────────┐
    │    @deep-review (LEAF agent)    │  Layer 3: Agent
    │  - Reads: state + strategy      │  Fresh context each time
    │  - Executes ONE review cycle    │
    │  - Writes: findings + state      │
    │  - Tools: Grep, Read, Glob, etc │
    │  - No WebFetch (code-only)      │
    └──────────────┬──────────────────┘
                   |
                   v
    ┌─────────────────────────────────┐
    │        State Files (disk)       │  Externalized State
    │  deep-review-config.json         │  Persists across iterations
    │  deep-review-state.jsonl        │
    │  deep-review-strategy.md        │
    │  deep-review-dashboard.md       │
    │  review/iterations/             │
    │    iteration-NNN.md             │
    │  review/review-report.md        │
    └─────────────────────────────────┘

State Packet Location

The review state packet lives under {spec_folder}/review/:

review/
  deep-review-config.json            # Immutable after init: review parameters
  deep-review-state.jsonl            # Append-only review iteration log
  deep-review-strategy.md            # Review dimensions, findings, next focus
  deep-review-dashboard.md           # Auto-generated review dashboard
  .deep-review-pause                 # Pause sentinel checked between iterations
  review-report.md                   # Final review report (synthesis output)
  iterations/
    iteration-NNN.md                 # Write-once review findings per iteration

Core Innovation: Fresh Context Per Iteration

Each agent dispatch gets a fresh context window. State continuity comes from files, not memory. This solves context degradation in long review sessions where accumulated findings would otherwise bias subsequent dimensions.

Data Flow

Init --> Create config.json, strategy.md, state.jsonl
  |
Loop --> Read state --> Check convergence --> Dispatch @deep-review
  |                                              |
  |                                              v
  |                                         Agent executes:
  |                                         1. Read state files
  |                                         2. Select ONE dimension (from strategy "Next Focus")
  |                                         3. Review target code (read-only, 3-5 actions)
  |                                         4. Write iteration-NNN.md (P0/P1/P2 findings)
  |                                         5. Update deep-review-strategy.md
  |                                         6. Append deep-review-state.jsonl
  |                                              |
  +<--- Evaluate results <-----------------------+
  |
  +--- Continue? --> Yes: next iteration
  |                  No: exit loop
  v
Synthesize --> Compile review/review-report.md (9 sections, verdict)
  |
Save --> generate-context.js --> verify memory artifact

Review Dimensions

The four primary review dimensions (configured in assets/review_mode_contract.yaml):

Severity Classification

Verdicts

4. RULES

ALWAYS

1. Read state first — Agent must read JSONL and strategy.md before any review action.
2. One dimension focus per iteration — Pick ONE review dimension from strategy.md "Next Focus"; never mix dimensions in a single iteration.
3. Externalize findings — Write to iteration-NNN.md with P0/P1/P2 classifications; never hold findings only in agent context.
4. Update strategy — Append dimension coverage to strategy.md "Covered" list, update "Next Focus" for the subsequent iteration.
5. Report newInfoRatio — Every iteration JSONL record must include newInfoRatio.
6. Respect exhausted approaches — Never re-review already-covered file+dimension combinations listed in strategy.md "Exhausted".
7. Cite sources — Every finding must cite [SOURCE: file:line] with actual code evidence; inference-only findings are not accepted.
8. Use generate-context.js for memory saves — Never manually create memory files; always use the script.
9. Review target files are read-only — Never modify any file under review; observation and reporting only.
10. Run adversarial self-check on P0 findings — Re-read the cited code before recording a P0 finding to confirm severity is genuine.
11. Report severity counts in every JSONL record — findingsSummary (cumulative) and findingsNew (this iteration) are required fields.
12. Quality guards must pass before convergence — Evidence completeness, scope alignment, no inference-only findings, severity coverage, and cross-reference checks must all pass (see references/convergence.md Section 10.4) before STOP can trigger.

NEVER

1. Dispatch sub-agents — @deep-review is LEAF-only; it cannot dispatch additional agents.
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.

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

Core Documentation

Local review-specific protocol documents:

Local Templates

Agent Runtime Paths

Review YAML Workflows

6. SUCCESS CRITERIA

Loop Completion

• Review loop ran to convergence or max iterations
• All configured review dimensions have at least one iteration of coverage
• All state files present and consistent (config.json, state.jsonl, strategy.md)
• review/review-report.md produced with all 9 sections
• Memory context saved via generate-context.js

Quality Gates

Review Mode Success Criteria

Convergence Report

Every completed loop produces a convergence report (embedded in review-report.md and JSONL):

• Stop reason (converged, max_iterations, all_dimensions_covered, stuck_unrecoverable)
• Total iterations completed
• Dimension coverage ratio
• P0/P1/P2 finding counts at convergence

7. INTEGRATION POINTS

Framework Integration

This skill operates within the behavioral framework defined in CLAUDE.md.

Key integrations:

• Gate 2: Skill routing via skill_advisor.py (keywords: deep review, code audit, iterative review)
• Gate 3: File modifications require spec folder question per CLAUDE.md Gate 3; the spec folder determines the {spec_folder}/review/ state packet location
• Memory: Context preserved via Spec Kit Memory MCP (generate-context.js)
• Command: /spec_kit:deep-review is the primary invocation point

Memory Integration

Before review:
  memory_context({ input: target, mode: "deep", intent: "review" })
  --> Loads prior audit context into strategy.md "Known Context"

During review (each iteration):
  Agent writes {spec_folder}/review/iterations/iteration-NNN.md
  Agent updates {spec_folder}/review/deep-review-strategy.md
  Agent appends {spec_folder}/review/deep-review-state.jsonl

After review:
  node .opencode/skill/system-spec-kit/scripts/dist/memory/generate-context.js [spec-folder]

Command Integration

CocoIndex Integration

mcp__cocoindex_code__search is available to @deep-review for semantic code search when Grep/Glob exact matching is insufficient. Use for:

• Finding all usages of a pattern by concept/intent
• Locating implementations when exact symbol names are unknown
• Cross-referencing behavior across unfamiliar code paths

8. RELATED RESOURCES

Worked Example: Spec Folder Audit

1. /spec_kit:deep-review:auto "specs/042-mcp-server"
2. Init creates specs/042-mcp-server/review/ with config, strategy (4 dimensions), state log
3. Iteration 1 (Correctness): Finds 2 P1 findings in handler logic; iteration-001.md written
4. Iteration 2 (Security): Finds 1 P0 (unsanitized input path); adversarial self-check confirms; iteration-002.md written
5. Iteration 3 (Spec-Alignment): Checks spec.md vs. implementation; finds 3 P1 misalignments
6. Iteration 4 (Completeness): All TODOs resolved; 2 P2 naming advisories
7. Convergence: all dimensions covered, quality guards pass
8. Synthesis produces review-report.md with verdict FAIL (P0 from iteration 2)
9. Memory saved via generate-context.js

Design Origins

Agents

Commands

Related Skills

For one-page cheat sheet: See quick_reference.md