Deep Review

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

bashCopy code
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 for this input contract, including rule lane/lens binding.

bashCopy code
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 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:

bashCopy code
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:

bashCopy code
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.md — Engines; for non-native --subagent, read subagent-runtimes.md. External calls spend compozy exec credit; preserve the user-selected model/effort.

3. Report

After global validation exits 0:

bashCopy code
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>

The renderer builds the walkthrough from the plan, intent and reviewer summaries at report time. It derives SHIP / FIX_BEFORE_SHIP / REWORK from defects, preserves advisories/suppressions and writes state. State the verdict only after render succeeds; include counts, every Critical/Major defect, coverage and the review.html path. Use ReportFindings when available, defects first and advisories afterward. Read output-contracts.md only when changing presentation or resolving a report diagnostic.

Scope, configuration and recovery

--base, --staged, --worktree, --files, --pr, --full retain the manifest builder's scope semantics. Worktree review includes uncommitted/untracked files and is always full. Prior state scopes normal rounds incrementally; --full requests a complete round. --spec accepts a file/directory and additional canonical artifacts can be named in decisions.

Batch limits accept any positive integer and never truncate the PR. Preparation preserves selected limits across decision stages, resume and refresh in prepare-request.json; passing a limit again overrides only that setting. Direct build_jobs.py inherits plan limits and accepts the same four batch flags.

Repo .deep-review.yaml keys path_filters, path_instructions, request_changes_workflow fall back individually to .coderabbit.yaml (reviews.*). Built-in generated/vendor/lock/snapshot exclusions remain. Path instructions have highest rubric precedence, followed by deepest applicable project instructions, root instructions, routed skills and learnings.

Re-run preparation without --refresh to resume pinned inputs. A changed scope/source needs --refresh and fresh applicability evidence; never bless the old snapshot manually. Provider block is runner exit 2 with run-blocker.json; resume the same command when available. Runner/global freeze exit 3 means stale inputs. Invalid input exit 1 needs artifact repair, never bypassed coverage. prepare-status.json, per-job statuses and external attempt logs expose timing without additional model work.

With --publish, read publish-github.md and execute its GitHub recipes after local rendering. When a user rebuts a finding, read state-and-learnings.md for the correction workflow. Read taxonomy.md only when an evidence/severity decision is unclear; the normal reviewer prompt already contains its required grammar.