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

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-review 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-codex / 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, 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

| Level | When to Load | Resources | |-------|-------------|-----------| | ALWAYS | Every skill invocation | references/protocol/quick_reference.md | | CONDITIONAL | If intent signals match | Loop protocol, convergence, state format, review contract | | ON_DEMAND | Only on explicit request | Full protocol docs, detailed specifications |

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", "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 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",
    ],
    "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",
    ],
    "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])  --strict` exits 0 on the target spec folder.

---

## 7. INTEGRATION POINTS

### Framework Integration

This skill operates within the behavioral framework defined in the active runtime's root doc (CLAUDE.md, AGENTS.md, or CODEX.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 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. Canonical packet continuity is written via `generate-context.js`
- **Command**: `/deep:review` is the primary invocation point

### Continuity Integration

Recover context via `/speckit:resume` 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`.

### Code Graph Integration

`code_graph_query + Grep` 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

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [MichelKerkmeester](https://github.com/MichelKerkmeester)
- **Source:** [MichelKerkmeester/opencode--skilled-agent-loops-with-spec-kit-memory](https://github.com/MichelKerkmeester/opencode--skilled-agent-loops-with-spec-kit-memory)
- **License:** MIT

Install and usage instructions live in the source repository linked above.