# Deep Review > Review branch diffs, working trees, or PRs in depth, including incremental, CodeRabbit-grade, cross-LLM, and spec-conformance reviews or requested publication of findings. Excludes fixes, spec-document reviews, and quick single-file feedback. - Skill: `pedronauck/deep-review` (Agent Skill, multi-file: 19 files) - Install (CLI): `npx skillmds@latest add pedronauck/deep-review` - Raw SKILL.md: https://api.skillmd.com/api/skills/pedronauck/deep-review/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: AI & ML - Author: pedronauck (https://skillmd.com/u/pedronauck) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/pedronauck/deep-review --- # 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 ``: 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. `` below means the directory containing this SKILL.md; run every bundled command from the repo root. ## Inputs (all optional) | Flag | Meaning | Default | | --- | --- | --- | | `--pr ` | Review a GitHub PR (requires authenticated `gh`; head fetched locally) | — | | `--base ` / `--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 ` | Restrict review to these paths | full diff | | `--spec ` | Spec file or directory; its contract-bearing artifacts become the conformance baseline (spec-parity sweep + verdict gate) | — | | `--subagent ` | Step 3 reviewer runtime: `native` \| `claude-opus` \| `grok` \| `codex` — non-native runs cross-LLM via `compozy exec` | `native` | | `--max-cohort-files ` | 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 ` | Artifact directory | `.deep-review//` | | `--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 ``, `.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** 1. Run the bundled manifest builder (bootstrap helper; reads the repo and `gh`, writes only under `--out`): ```bash python3 /scripts/build_manifest.py --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. 2. Read the printed summary. For `--pr`, the manifest base is the merge-base of the fetched PR base/head, so base-only changes stay outside the review. If the head is missing, run the printed fetch command and retry; if the base/history is missing, fetch it before retrying. *Done when:* `/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** 1. STOP. Read `/references/context-pack.md` and `/references/taxonomy.md` in full before extracting rules or defining reviewer lanes. Run the bootstrap helper (reads the repo, writes only under ``): ```bash python3 /scripts/build_knowledge.py --out ``` Read every source left pending in `/rules.template.json` in full, including direct references of selected project skills. Write `/rules.json` with every source marked applied or not-applicable (reason required), then extract verdict-bearing rules verbatim with scope globs. Assemble `/context-pack.md` and run/fold the detected linter lanes. 2. Read `/references/orchestration.md` (cohort rules, sweep triggers) and `/references/output-contracts.md` (walkthrough anatomy, effort scale) in full. Write `/plan.json` — cohorts of up to `` files (default 100) / ~6,000 changed lines plus any sweep whose trigger fires — and `/walkthrough.md`. 3. Run the bootstrap plan gate (reads repo artifacts, writes only under ``): ```bash python3 /scripts/build_jobs.py --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 `/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 `/jobs.json` with the mutating runner and engine contract loaded in Step 2. When `--subagent` is not `native`, read `/references/subagent-runtimes.md` in full before execution. Completion is engine-independent — re-dispatch whatever is listed as pending/invalid until exit 0: ```bash python3 /scripts/run_jobs.py --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: ```bash python3 /scripts/merge_findings.py --out python3 /scripts/render_review.py --out [--rework ""] python3 /scripts/render_html.py --out ``` merge_findings.py emits `/findings.json` plus `/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 `/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`)** 1. Read `/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** 1. state.json was already written at Step 4. When the user — or a PR reply — rebuts or dismisses a result, read `/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 `/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 `/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 `/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. `/scripts/_common.py` is a read-only library imported by the CLIs and is never invoked directly.