agentleFS
dougcunhadougcunha/TokenHound/.agents/skills/deep-review/SKILL.md

deep-review

Skill3 starsChanged 36 days agoMITView on GitHub

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.

46 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use react, testing-strategy and 7 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • VercelSkill

    react

    React renderer for json-render that turns JSON specs into React components. Use when working with @json-render/react, building React UIs from JSON, creating component catalogs, or rendering AI-generated specs.

    Also in 3 projects that use this

  • BlockSkill

    testing-strategy

    Guidelines for writing effective tests in this project

    Also in 3 projects that use this

  • SentrySkill

    deslop

    Strip AI-generated noise from the diff before pushing — extra comments a human wouldn't write, defensive try/catch in trusted code paths, casts to any, inline imports in Python, and other style inconsistencies with the surrounding file. Use this immediately before commit so the diff stays clean.

    Also in 3 projects that use this

  • SentrySkill

    review

    Fixture review skill.

    Also in 5 projects that use this

  • AnthropicSkill

    debug

    Structured debugging session — reproduce, isolate, diagnose, and fix. Trigger with an error message or stack trace, "this works in staging but not prod", "something broke after the deploy", or when behavior diverges from expected and the cause isn't obvious.

    Also in 3 projects that use this

  • NVIDIASkill

    testing

    Run Python and Rust tests for physicsnemo-curator using uv + pytest with coverage reporting via pytest-cov, and cargo-nextest for Rust tests. Includes benchmark workflows with pytest-benchmark and criterion.

    Also in 3 projects that use this

The file

Show its rules and text

We split this skill into the rules it gives an agent

14 rules. 0 are common, 3 are distinctive, and 11 are very specific to this project.

  • 0

    Common

    Most of the 40 edited versions we read keep these.

  • 3

    Distinctive

    This author's own choices. Worth a look.

  • 11

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    No file-count cap: a large selection means more cohorts, never a skipped or silently truncated review.

    line 47
  2. Very specific:

    Every defect starts with Premise → Path → Verdict.

    line 48
  3. Very specific:

    Every selected hunk line receives both defect and polish coverage.

    line 49
  4. Very specific:

    Run the repo's linters first and record every overlapping candidate as linter-overlap rather than reporting it again.

    line 50
  5. Very specific:

    Every review ends with a SHIP / FIX_BEFORE_SHIP / REWORK verdict derived by render_review.py and stated only after that script exits 0.

    line 53
  6. Very specific:

    Run the bundled manifest builder (bootstrap helper.

    line 60
  7. Very specific:

    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.

    line 68
  8. Very specific:

    STOP. Read <skill-dir>/references/context-pack.md and <skill-dir>/references/taxonomy.md in full before extracting rules or defining …

    line 74
  9. Very specific:

    Read every source left pending in <out>/rules.template.json in full, including direct references of selected project skills.

    line 80
  10. Very specific:

    Read <skill-dir>/references/orchestration.md (cohort rules, sweep triggers) and <skill-dir>/references/output-contracts.md (walkthrough …

    line 81
  11. Very specific:

    Run the bootstrap plan gate (reads repo artifacts, writes only under <out>):

    line 82
  12. Distinctive:

    Run the bootstrap merger, mutating state/report renderer, and bootstrap HTML hydrator:

    line 105
  13. Distinctive:

    When ReportFindings is available, report defects first and every advisory afterward.

    line 115
  14. Very specific:

    Read <skill-dir>/references/publish-github.md in full and execute its recipes: upsert the walkthrough, publish every anchorable in-diff …

    line 121

“Common” is measured: kept by at least 6 in 10 of the 40 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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)

FlagMeaningDefault
--pr <n>Review a GitHub PR (requires authenticated gh; head fetched locally)—
--base <ref> / --stagedLocal diff scopemerge-base with the origin default branch
--worktreeReview uncommitted + untracked work against the base ref (always a full round)—
--files <p1,p2>Restrict review to these pathsfull 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 execnative
--max-cohort-files <n>Maximum files assigned to one cohort; the ~6,000 changed-line cap still applies100
--publishPost walkthrough + review to the PRoff — local report only
--fullIgnore prior state; review the whole diff againincremental when state exists
--out <dir>Artifact directory.deep-review/<target>/
--no-workflowSkip the Workflow tool; use Agent fan-outWorkflow 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:

KeyMeaning
path_filtersGlobs 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_instructionspath glob + verbatim instructions entries — the highest-precedence rubric source (Step 2)
request_changes_workflowpublish-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

  1. 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.

  2. 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

  1. 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.

  2. 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.
  3. 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)

  1. 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

  1. 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.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.