| name | deep-review |
| description | Deep review of branch diffs, working trees, or GitHub PRs at any size. Use when the user asks for CodeRabbit-grade review, an incremental re-review after new pushes, publication of findings to a PR, a cross-LLM peer-review verdict round, or conformance review against spec artifacts. Don't use for applying fixes, reviewing specs or PRDs as documents, or quick single-file feedback. |
| trigger | explicit |
| argument-hint | [--pr N | --base <ref> | --staged | --worktree] [--files p1,p2] [--spec <path>] [--subagent native|claude-opus|grok|codex] [--max-cohort-files N] [--publish] [--full] [--out <dir>] [--no-workflow] |
Deep Review
Review at CodeRabbit grade with no file cap and one assertive posture: funnel the diff, discover root/nested project instructions and relevant local skills, shard defects and polish into independent cohorts, fan out reviewers, then merge with complete hunk/rule accounting. Defects require causal evidence and control the verdict; advisories require a concrete improvement and always remain visible.
Steps 1–4 drive an idempotent artifact pipeline under <out>: every stage gate is a bundled-script exit 0, valid agent outputs are never re-run, and an interrupted round resumes by re-running the same commands.
<skill-dir> below means the directory containing this SKILL.md; run every bundled command from the repo root.
Inputs (all optional)
| Flag | Meaning | Default |
|---|
--pr <n> | Review a GitHub PR (requires authenticated gh; head fetched locally) | — |
--base <ref> / --staged | Local diff scope | merge-base with the origin default branch |
--worktree | Review uncommitted + untracked work against the base ref (always a full round) | — |
--files <p1,p2> | Restrict review to these paths | full diff |
--spec <path> | Spec file or directory; its contract-bearing artifacts become the conformance baseline (spec-parity sweep + verdict gate) | — |
--subagent <runtime> | Step 3 reviewer runtime: native | claude-opus | grok | codex — non-native runs cross-LLM via compozy exec | native |
--max-cohort-files <n> | Maximum files assigned to one cohort; the ~6,000 changed-line cap still applies | 100 |
--publish | Post walkthrough + review to the PR | off — local report only |
--full | Ignore prior state; review the whole diff again | incremental when state exists |
--out <dir> | Artifact directory | .deep-review/<target>/ |
--no-workflow | Skip the Workflow tool; use Agent fan-out | Workflow when available |
Repo config — .deep-review.yaml
Optional repo-root file, the skill-native config standard. Any key absent there falls back to its .coderabbit.yaml counterpart (reviews.*), so repos migrating from CodeRabbit work unconfigured. Top-level keys, all optional:
| Key | Meaning |
|---|
path_filters | Globs over repo-relative paths: !pat excludes; bare patterns, when present, restrict review to their matches and beat any exclude; built-in excludes (locks, vendor, generated, testdata, snapshots) always append |
path_instructions | path glob + verbatim instructions entries — the highest-precedence rubric source (Step 2) |
request_changes_workflow | publish-mode review-event gate |
The manifest builder resolves path_filters into manifest.json; the knowledge stage ingests path_instructions together with project instructions and skills.
Hard rules
- Source is read-only and frozen: the manifest pins
worktree_snapshot, and run_jobs.py / render_review.py refuse a drifted checkout. Writes go only to <out>, .deep-review/ state, and — with --publish — the target PR.
- No file-count cap: a large selection means more cohorts, never a skipped or silently truncated review. Every selected file lands in exactly one cohort.
- Every defect starts with
Premise → Path → Verdict; every advisory starts with Premise → Improvement → Fix. Investigated rejections remain visible in the suppression ledger.
- Every selected hunk line receives both defect and polish coverage. Every bound rule receives an explicit compliant/violated/not-applicable assessment.
- Run the repo's linters first and record every overlapping candidate as
linter-overlap rather than reporting it again.
- Cite rubric rules verbatim with their source path; severity comes from the taxonomy, never inflated.
- Publishing needs
--publish or the user's explicit go-ahead in this session; otherwise the review stays local.
- Every review ends with a SHIP / FIX_BEFORE_SHIP / REWORK verdict derived by render_review.py and stated only after that script exits 0.
- External
--subagent runtimes spend compozy exec credit.
Procedure
Step 1: Funnel — build the manifest
-
Run the bundled manifest builder (bootstrap helper; reads the repo and gh, writes only under --out):
python3 <skill-dir>/scripts/build_manifest.py --out <out> \
[--pr N | --base REF | --staged | --worktree] [--files p1,p2] [--full]
It resolves repo path filters, detects generated / trivial / renamed files, scopes to the incremental delta when prior state exists, and pins the source-freeze snapshot.
-
Read the printed summary. On --pr, the script errors with the exact git fetch command when the head SHA is absent — run it and retry.
Done when: <out>/manifest.json exists, every changed file is accounted for as selected, ignored(reason), or skipped(reason), and every selected file carries its hunk list (the units of judgment and the publish anchors).
Step 2: Knowledge + plan — project rules, cohorts, walkthrough
-
STOP. Read <skill-dir>/references/context-pack.md and <skill-dir>/references/taxonomy.md in full before extracting rules or defining reviewer lanes. Run the bootstrap helper (reads the repo, writes only under <out>):
python3 <skill-dir>/scripts/build_knowledge.py --out <out>
Read every source left pending in <out>/rules.template.json in full, including direct references of selected project skills. Write <out>/rules.json with every source marked applied or not-applicable (reason required), then extract verdict-bearing rules verbatim with scope globs. Assemble <out>/context-pack.md and run/fold the detected linter lanes.
-
Read <skill-dir>/references/orchestration.md (cohort rules, sweep triggers) and <skill-dir>/references/output-contracts.md (walkthrough anatomy, effort scale) in full. Write <out>/plan.json — cohorts of up to <max-cohort-files> files (default 100) / ~6,000 changed lines plus any sweep whose trigger fires — and <out>/walkthrough.md.
-
Run the bootstrap plan gate (reads repo artifacts, writes only under <out>):
python3 <skill-dir>/scripts/build_jobs.py --out <out> \
[--max-cohort-files N]
It rejects incomplete source accounting, proves defect ownership, derives smaller polish cohorts (≤20 files / 1,200 changed lines), injects bound rules into every lane and sweep, and materializes <out>/jobs.json.
Done when: build_jobs.py exits 0, every discovered source has an audited decision in rules.json, context-pack.md lists applied source/rule and linter outcomes without copying the full registry, and walkthrough.md satisfies its contract.
Step 3: Fan-out — parallel review
Execute <out>/jobs.json with the mutating runner and engine contract loaded in Step 2. When --subagent is not native, read <skill-dir>/references/subagent-runtimes.md in full before execution. Completion is engine-independent — re-dispatch whatever is listed as pending/invalid until exit 0:
python3 <skill-dir>/scripts/run_jobs.py --out <out> --validate-only
Done when: run_jobs.py --validate-only exits 0 — every defect, polish, and sweep output matches the schema and completely accounts for assigned hunks and rules.
Step 4: Merge + report
Run the bootstrap merger, mutating state/report renderer, and bootstrap HTML hydrator:
python3 <skill-dir>/scripts/merge_findings.py --out <out>
python3 <skill-dir>/scripts/render_review.py --out <out> [--rework "<structural rationale>"]
python3 <skill-dir>/scripts/render_html.py --out <out>
merge_findings.py emits <out>/findings.json plus <out>/review-stats.json, deduplicates both result classes, reconciles rounds, and fails unless every selected hunk line has defect and polish coverage. render_review.py derives the verdict from defects only. render_html.py shows defects, advisories, suppressions, and coverage separately in <out>/review.html.
When ReportFindings is available, report defects first and every advisory afterward. The user-facing summary states the verdict, defect/advisory counts, every Critical/Major defect, coverage status, and artifact paths.
Done when: render_review.py and render_html.py exit 0 and the final message states the verdict, every Critical and Major defect, and the review.html path.
Step 5: Publish (only with --publish)
- Read
<skill-dir>/references/publish-github.md in full and execute its recipes: upsert the walkthrough, publish every anchorable in-diff defect and advisory inline, keep only unanchorable/outside-diff results in the body, and edit resolved prior-round comments.
Done when: the PR shows the updated walkthrough and the new review, and both URLs are cited in the final message.
Step 6: Learnings
- state.json was already written at Step 4. When the user — or a PR reply — rebuts or dismisses a result, read
<skill-dir>/references/state-and-learnings.md in full, distill the correction into .deep-review/learnings.md, and mark that fingerprint dismissed in the state ledger.
Done when: every user correction from the session is captured as a learning or explicitly declined.
Incremental rounds
With prior state (or fingerprints recovered from the PR thread), Step 1 scopes to commits since the last reviewed head and archives the prior round's artifacts under <out>/rounds/. Unresolved prior results re-surface once under Duplicates; dismissed fingerprints stay suppressed; resolved ones receive the ✅ edit in publish mode. --full reviews the whole diff again. Each round's Step 4 regenerates <out>/review.html, so a browser tab left open on it tracks the rounds by itself.
Error handling
--pr or --publish without a passing gh auth status → stop and name the gap; publishing by any other transport is out of scope.- Workflow tool unavailable → automatic Agent fallback; record the mode in walkthrough.md's Review details.
- External
--subagent failure (model not available, missing/invalid output file, non-zero exit) → apply the failure handling loaded in Step 3.
- Empty selection after the funnel → report "nothing reviewable" with the manifest counts; write no findings.
- A linter lane unavailable → proceed and state in review.md that overlap suppression did not run for that lane.
- A bootstrap gate failing (build_manifest.py, build_knowledge.py, build_jobs.py, merge_findings.py) → stop and surface stderr. Missing knowledge accounting or incomplete defect/polish coverage is a review failure, not a warning.
- run_jobs.py exit 2 (blocked) → a provider limit interrupted the fan-out; valid outputs are preserved and
<out>/run-blocker.json lists the pending jobs — resume by re-running the same command once the limit clears. Providers that signal limits differently need extra --block-on patterns.
- run_jobs.py exit 3 or a render_review freeze failure → the checkout drifted mid-round; findings would anchor to stale lines. Restart from Step 1 — the round increments and prior artifacts are archived.
- More than 75 publishable results → use the Step 5 batching contract.
Bundled implementation
assets/PROMPT.md, assets/findings.schema.json, and assets/REVIEW_UI.html are author-tooling sources consumed by the bundled scripts; agents use their rendered prompt/schema/report artifacts rather than loading these assets directly. <skill-dir>/scripts/_common.py is a read-only library imported by the CLIs and is never invoked directly.
