/deep-review

name: deep-review
description: "Review branch diffs, working trees, or PRs in depth with defect, polish and cross-contract coverage. Includes incremental and spec-conformance reviews; excludes fixes, spec-document reviews and quick single-file feedback."
disable-model-invocation: true
argument-hint: "[--pr N | --base REF | --staged | --worktree] [--files p1,p2] [--spec PATH] [--subagent native|claude-opus|grok|codex] [--max-cohort-files N] [--max-cohort-lines N] [--max-polish-files N] [--max-polish-lines N] [--publish] [--full] [--out DIR]"

Deep Review

Find actionable defects and improvements with complete selected-hunk and project-rule accounting. Scripts handle discovery, partitions, artifact assembly and validation; the model supplies applicability decisions and evidence-based review. Keep source read-only; write review artifacts under `<out>` (default `.deep-review/<target>/`). Resolve `<skill-dir>` from this file and run bundled commands from the reviewed repository root.

Contract

• No total file or line cap on the PR. Every selected hunk has exactly one defect owner and one polish owner. Both default to broad cohorts of **200 files / 15,000 changed lines per job**, adjustable with `--max-cohort-files`, `--max-cohort-lines`, `--max-polish-files` and `--max-polish-lines`. Oversized files are sliced without losing hunks. An optional `--max-context-lines N` preparation budget accounts for whole-file reading while preserving selection.
• Every defect has causal evidence; every advisory has an observed premise, concrete improvement and bounded fix. Investigated rejections stay in the suppression ledger. No quota; advisories never block SHIP.
• Every applied rule comes from material actually read, with verbatim text, source, scope and explicit assessment. Root/nested instructions retain scope and precedence. Metadata is a triage queue, not an instruction to load every skill.
• Relevant linters run first or reuse evidence for the same frozen inputs. Record unavailable lanes; suppress overlapping findings. Never install tools to fill a lane.
• The checkout, rule evidence and job contracts are pinned. Valid outputs are reused only for their unchanged contracts. Missing coverage, stale evidence and malformed results prevent completion.
• Publish only with `--publish` or explicit session authorization. Product fixes are outside this skill.

1. Prepare

python3 <skill-dir>/scripts/prepare_review.py --out <out> \
  [--pr N | --base REF | --staged | --worktree] [--files p1,p2] \
  [--spec PATH] [--full] [--max-cohort-files N] [--max-cohort-lines N] \
  [--max-polish-files N] [--max-polish-lines N]

The helper creates the manifest, `knowledge.md` and `decisions.template.json`. Inspect the manifest summary for correct base/head and file selection, especially after a rebase. Empty selection ends as “nothing reviewable.” For PRs, fetch the missing head/base/history using the manifest's diagnostic and retry.

Read `knowledge.md`, not the raw registry. Use its metadata to classify routers; read applicable instructions and selected skill sections. Copy the template with `cp <out>/decisions.template.json <out>/decisions.json`, then edit only the semantic decisions, preserving fingerprints. Use compact source IDs or grouped exclusions; supply actual reasons, exact rule spans, change intent and linter evidence. Read [context-pack.md — Decision file](references/context-pack.md#decision-file) for this input contract, including rule lane/lens binding.

python3 <skill-dir>/scripts/prepare_review.py --out <out> --decisions <out>/decisions.json

Exit 2 means decisions remain: applied skill parents reveal their reference routes on the next compile. The refreshed `decisions.template.json` already preserves prior decisions and additional fields; copy it over `decisions.json` and edit the pending entries. Assess references from their routing conditions. Excluding a parent accounts for its dependent references; shared references remain pending while an applicable parent needs them. Missing required references block preparation.

Complete decisions compile `rules.json`, `context-pack.md`, a package-oriented `plan.json`, per-job contracts and `jobs.json`. Do not write preparation scripts, manually enumerate partitions, or author a walkthrough before dispatch. Adjust generated groups only for real semantic boundaries. Sweeps default to none; use [orchestration.md — Sweeps](references/orchestration.md#sweeps) only for a concrete cross-cohort hypothesis. `--spec` adds the conformance sweep automatically.

2. Review

Use native agents by default, at most six concurrent. A worker receives only its rendered prompt: “Read `<prompt>` and complete its assigned review; submit its draft with the local command in that prompt.” Start without inherited conversation where supported (`fork_turns=none`). The worker does not load this skill, global jobs/manifest files or orchestrator references. Its contract includes the necessary context, rules, hunk IDs, evidence grammar and output shape.

Workers fill the provided draft template with explicit assessments, then run:

python3 <skill-dir>/scripts/run_jobs.py --out <out> --job <label> --submit

This validates only that job and expands IDs into canonical output. Missing or invalid fields produce complete local diagnostics; repair the existing draft. No blanket `clear`/`compliant`, global validation in workers, or new investigation merely to reconstruct JSON.

The orchestrator alone runs the global gate after a batch, or to resume an interrupted round:

python3 <skill-dir>/scripts/run_jobs.py --out <out> --validate-only

Dispatch only pending/invalid status rows using their `prompt` field: invalid rows already point to a targeted repair prompt. Reuse valid outputs. Repeated failure without progress requires inspecting the actual diagnostic, not looping the same review request. For Workflow execution, read [orchestration