# Code Review > Owns the local review cycle over three engines — CodeRabbit, Greptile, and Macroscope (`.coderabbit.yaml`, `.greptile/`, `.macroscope/`). Use on any request to review, and whenever those config files are read, edited, or authored — this skill owns their schemas and rule grammar. - Skill: `bsamiee/code-review` (Agent Skill, multi-file: 9 files) - Install (CLI): `npx skillmds@latest add bsamiee/code-review` - Raw SKILL.md: https://api.skillmd.com/api/skills/bsamiee/code-review/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: bsamiee (https://skillmd.com/u/bsamiee) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/bsamiee/code-review --- # [CODE_REVIEW] One rail carries the whole cycle: every engine round normalizes into one finding schema, and each round distills its refuted classes and lessons into the reviewer configs so the next round runs harder. ## [01]-[ROUTING] [REFERENCES]: - [01]-[CODERABBIT](references/coderabbit.md): `.coderabbit.yaml` config, the `--agent` stream, and the rich finding store - [02]-[GREPTILE](references/greptile.md): `.greptile/` cascade, the `--json` envelope and status oracle, and the MCP bridge - [03]-[MACROSCOPE](references/macroscope.md): `.macroscope/` concern files, the stream grammar, and worktree custody [TEMPLATES]: each template is self-contained for its own agent; a fact one of them carries is never restated here. - [01]-[FIX](templates/fix.md): universal fixer template — conduct law, corpus fills, and both dispatch shards - [02]-[CLOSE](templates/close.md): universal closer template — weight-sized arming, land-or-refute stance - [03]-[HARVEST](templates/harvest.md): per-round reviewer-harvest dispatch — round-instance slots and both transports - [04]-[REFUTED_CLASSES](templates/refuted-classes.yaml): refuted-class registry compiled into classifier, recurrence detector, and rulings roster [SCRIPTS]: - [01]-[REVIEW_RAIL](scripts/review_rail.py): verb rail printing one JSON receipt per verb [AGENT]: - `.claude/agents/reviewer-harvest.md`: owns the DISTILL leg ## [02]-[CYCLE] Every session is its own campaign: rounds number from 1, the session's first launch deletes any pre-existing `.cache/review/` state whole — never archived, never resumed, never numbered from — and the campaign close deletes it again once the final round's `round` row prints its delta. Mid-campaign round dirs survive until then: normalize provenance, `--dedup-against`, and the harvest recurrence census read prior rounds. Commits follow the user's request and the file scope it names; each round otherwise reviews the tree as it stands, every landing staying uncommitted. Step order never proves a drain, the owning receipt does: `reconcile` surfaces `routing.pending`, `round` refuses `routing-undrained` while it is non-empty, and `harvest`/`round` refuse a partial shard-report set. [STEP_1]-[LAUNCH]: `launch --reviewer --scope --follow --normalize` spawns one engine round at its canonical scope; the receipt proves the spawn, and the follow exits 0 only on `completed`, landing the findings receipt in the same verb. Bare `launch` prints `watch_cmd` instead: it self-exits at the terminal phase, its exit re-invokes the agent, and `findings --normalize --round N` lands the receipt. - KNOB: engine choice and `--focus`. [STEP_2]-[NORMALIZE]: `findings --normalize` per completed round; `gather --all-live|--reviewer |--rounds ` unions completed normalized rounds into one pre-normalized round every later step targets — `--all-live` takes every engine round with no ledger row and no prior gather, pass `--rounds` when older rounds sit open. `findings --digest --round N` prints the round read — severity counts, class fires, folder cuts, top rows per severity — where engine rotation and shard count decide; query filters answer every targeted read, never hand-jq over `findings.json`. - WATCH: provenance histogram before any count judgment — a flat total decomposes into `relitigation|refuted_remint|new_work|late_discovery`, and rising new-work beside falling relitigation is convergence. - KNOB: `--dedup-against`. [STEP_3]-[SLICE]: `slice --round N` cuts balanced per-shard manifests with stamped ids and a dispatch-ready `shard--brief.md` each; `shards --fill` then emits each shard's corpus data for template fill; files, owning packages with `.api` overlays, substrate `.api`, doctrine roots, unplaced files. - WATCH: severity and folder balance across shards. - KNOB: explicit `--shards`, one per balanced folder slice up to the ceiling — small slices direct freed capacity into capability depth, never early finish. [STEP_4]-[FIX]: one keeper per shard under `templates/fix.md`, dispatched concurrently from the briefs on either transport, codex mechanics the delegate-codex skill's, each writing `/shard--report.json`. - WATCH: `shards --spawns` proves each shard's miner passes; a lost report relaunches once, and a second failure is hand-repaired, since every downstream verb refuses a partial shard-report set. - KNOB: template wording. - Codex shards run the config-default model and effort unflagged under the full user config; miner spawns need the multi-agent depth row, so deviate only for purely mechanical slices. Each shard returns only its report path — the codex shard's `-o` capture, the claude shard's own final write. [STEP_5]-[RECONCILE]: `reconcile --round N` exits 0 only when `bijective: true` proves every stamped id carries exactly one verdict; `missing`/`phantom` name the defecting shard, `files`/`strays` name cross-territory writes, and `routing` states the closer drain `{total, drained, verdicts, pending}`. - WATCH: verdict-mix honesty — fixed-versus-upgraded inflation, citation-backed push-back share; `report_valid: false` beside a `fault` is a decode failure to repair first. [STEP_6]-[CLOSERS]: shard-report `routing[]` rows alone arm this stage, so a finding `reconcile` reports dropped or phantom lands as a hand-added routing row before the cut. `slice --closers --round N` cuts the rows into file-disjoint territories (`close-.json` and brief); closers dispatch concurrently under `templates/close.md`, sized by row weight, each writing `/close--report.json` answering by the brief's stamped keys, and `reconcile` re-runs to prove the drain empty. - WATCH: honest land-versus-refute — a mined candidate that cannot ground is refuted with its citation, never forced. - KNOB: closer sizing. [STEP_7]-[DISTILL]: `harvest --round N` assembles the feed and memory proposals (`round --harvest` in one verb); dispatch under `templates/harvest.md`. - WATCH: diff-sample touched blocks — density rose, integrations weave, additions earned; the `trimmed` self-report verifies against the diff. - KNOB: agent-file wording, the single versioned tuning surface. [STEP_8]-[VERIFY]: `registry --apply --rows ` lands only a clean set, append-only, refusing whole and naming each fault; `registry --check --rows ` diagnoses the refusal, bare `registry --check` lints the standing yaml and proves each row's `landed_surfaces` claim. `verify --round N` proves each surface-ledger guard in its surface's own oracle. - WATCH: an ineffective row marks failed wording — harden the owner and re-verify before `round`, since the close is one-shot. - KNOB: guard wording at its owning surface. [STEP_9]-[CLOSE]: `round [--harvest] [--defer-routing] --round N` appends the `rounds.jsonl` row and prints the delta; it refuses `routing-undrained` while routing rows lack closer verdicts unless `--defer-routing` records the deferral. - WATCH: findings trending down while capability rows rise is the goal line. - Campaign close dispatches `/custodian` bare over the round's working diff for one-way touchpoint and ownership custody across the reviewer-config and doctrine surfaces; its receipt returns to the orchestrator and never feeds the harvest. [STEP_10]-[NEXT]: grade the round on the [GRADING] axes, then pick the next engine — recurrence judges per engine, counts flattening under one engine rotate the next round to another, and `--focus` aims a round within one; greptile rides early rounds, before the accumulated diff meets its size caps. - WATCH: plateau under a hardened config. - KNOB: rotation and focus. [FRAMING]: both framings ride every surface — negative framing kills false-positive classes through do-not-flag guards citing the refuting ruling, positive framing steers toward house demands through hunt axes and hit-shape rosters. Hit-shape rosters land on every surface regardless of what an engine emits, fixer miners execute them. [GRADING]: REVIEW-THE-REVIEWER grades every round on the round row's typed fields, each naming its oracle, so a between-rounds template edit reads as prompt-change to behavior-change mechanically. CodeRabbit emits no missing-capability findings under any `path_instructions` wording; capability-direction rides Macroscope check-run agents and Greptile structured rules. - Round axes and oracles: `fp_share`/`relitigation_share` (pre-prune provenance histogram), `novel_quality` (accepted-verdict share over novel-provenance rows), `hunt_axis_fire` (fixer-stamped improvement axes), `shape_fire` (fixer-stamped ledger `shape`; `ShardStat.shapes` counts each shard's unstamped gap), `wall_spread` (shard wall times; an outlier exceeds twice the median), `prompts` (content hashes of the dispatch templates and the `reviewer-harvest` agent). - Finding strength stays a judgment sample, never a computed grade: `anchored` and `actionable` are rail-stamped bits, while discriminating (the claim states why the shape is wrong) and novelty read by operator judgment — a computed stand-in fabricates the grade. - Fixer shards grade on five per-model axes in `grades` beside the raw `by_model` verdict rollup — `depth_of_fix` (`upgraded` over `fixed` + `upgraded`), `scope_clean` (phantom-free shards), `refute_cited` (evidence-carrying `refuted` rows), `gate_clean`, `bijective` — so the claude-versus-codex comparison is one jq group; upgraded claims surviving diff re-read stay the orchestrator's judgment axis. - Prose FP classes live as `corpus: prose` registry rows citing the docgen defect catalog, graded by the same recurrence machinery. ## [03]-[VERBS] Every round-scoped verb accepts `--round N` and `--dir`, printing one JSON receipt; a refusal exits nonzero carrying `{code, detail}`. `REVIEW_RAIL_BUNDLE` points a relocated copy of the script back at the bundle's `templates/` and registry. ```bash template rail() { uv run "${CLAUDE_SKILL_DIR}/scripts/review_rail.py" "$@"; } # shell state dies per tool call — re-define per shell, or use the literal path rail launch --reviewer --scope [--focus ] [--follow [--json] [--normalize]] rail status --follow --round [--json] [--normalize] rail findings --normalize --round [--dedup-against ] rail findings --digest --round rail findings --file '' --severity --claim '' [--in claim|fix|both] --round [--json] rail slice [--shards 3] [--recut] --round rail shards --fill --round # fixer shards dispatch here (orchestrator): each prompt cites its shard--brief.md; each shard writes /shard--report.json rail reconcile --round rail shards --spawns [--shard ] --round rail slice --closers [--shards 2] [--recut] --round # closers dispatch here: each cites its close--brief.md and writes /close--report.json rail reconcile --round # re-run: proves the closer drain empty rail harvest --round # dispatch the reviewer-harvest agent on the feed; persist its ledger as /surface-ledger.json rail registry --apply --rows rail verify --round rail round [--harvest] [--defer-routing] --round ``` ```bash template rail launch --reviewer coderabbit --scope uncommitted rail launch --reviewer greptile --scope base: rail launch --reviewer macroscope --scope base: rail status --follow --all-live # exits when every live round is terminal rail findings --normalize --round # once per engine round rail gather --all-live # union round: fingerprint collapse, corroborators, max severity # slice / reconcile / closers / harvest / verify / round then target the gather round ``` `launch` refuses an unsupported engine-scope pair and a live same-engine round; the scope family is `all|committed|uncommitted|base:|base-commit:`, every `--reviewer` takes the `cr|gt|ms` aliases, and conflicting selectors refuse `bad-flag` on `status`/`kill`. `--focus` takes inline text or a file path — greptile rides `--instructions`, coderabbit a round-scoped `-c` instruction file, and macroscope refuses `--focus` before any preflight side effect. [CODERABBIT]: sweeps working-tree quality and style at full breadth every run — a retry re-spends quota; canonical round `--scope uncommitted`, full scope family accepted. `launch` resolves and injects a base for every working-tree scope. One hard changed-file cap (300, counted pre-filter) refuses oversized scopes, so a tree past the cap reviews under another engine or after the user's own commit narrows it. [GREPTILE]: hunts cross-file logic over the commits already on the branch against a base; canonical round `--scope base:`, `committed` reviews against the repo default, and `base:`/`base-commit:` refs take any committish. - Scope is a base..HEAD range, so a cumulative campaign pins one base — `base-commit:` held across rounds — and the whole accumulated delta reviews as one change regardless of commit count, with cross-round dedup and provenance keeping adjudicated rows out of shards. - Client-side size caps refuse a range past them, and a tree carrying no commits past the base returns a clean empty round. [MACROSCOPE]: streams AST-level correctness in place — fixes land in the files the review read; canonical round `--scope base:` spanning committed branch work and uncommitted edits, `uncommitted` for tree-only — an in-place run without a base on a branch reviews almost nothing. Terminal phases are `completed|failed|refused|stalled|timed-out|killed`; a receipt short of `completed` names its fault `signature`, `remedy`, and engine `exit_code`, and `status --follow --all-live` exits 0 only when every followed round completed. `--json` on any follow streams one `StatusReceipt` JSON line per phase change or minute pulse for a piping orchestrator; the terminal receipt prints either way. Bare `status` resolves the single live round, else the highest-numbered on disk; several live rounds refuse `ambiguous` naming them — pass `--round`, `--reviewer`, or `--all-live`. `kill` (same selectors, same `no-round`/`ambiguous` selection refusals) escalates SIGTERM to SIGKILL over the process group, sweeps detached engine survivors and macroscope worktrees, and reaps a stalled or timed-out round whose engine still breathes; per round it refuses a gather round (`no-process`) and a round whose process group is gone (`already-closed`). `findings --normalize` gates on `completed` and refuses an already-sliced round. Minting strips each engine's constant fix-preamble (one `ENGINE_PREAMBLES` row per preamble) and carries content fields only; the receipt `source` names the store a raw payload re-reads from. `scope_misfire` on the receipt flags zero rows over a dirty scope; an exit-0 zero-comment envelope over a clean scope is ordinary success. Normalize refuses `dedup-collapse` when over half of eight or more admitted rows drop as intra-round fingerprint duplicates — engine format drift, never real duplication. Bare `findings` reprints the admission summary. `--top N` bounds the digest's per-severity rows, and the query filters compose with `--digest` — both print human-scan text, `--json` the typed form. `--in` scopes the `--claim` regex, defaults to `both`, and refuses without `--claim`. `gather` takes exactly one selector, and every source must be `completed` and normalized. `slice [--shards N] --balance count|loc` partitions by folder affinity — grouping deepens past common prefixes and splits oversized folders at sub-folder seams until shards balance, so N shards over at least N findings always cut N non-degenerate shards. It clears stale shard artifacts only after the cut proves out, and each manifest carries the corpus-matched settled-rulings roster; a registry row tagged `corpus` slices only into shards whose file set resolves to that corpus. `slice --closers` instead keys one row per routed demand as `:`, groups by target file, and greedy-packs whole files into territories; an omitted `--shards` derives the count, clamped to the distinct-file ceiling, and the cut never rewrites `findings.json`. `reconcile` covers all shards bare. `shards` takes exactly one of `--fill` or `--spawns` with an optional `--shard ` filter (a bare letter reads as `shard-`); its spawn oracle is the codex rollout store — the per-shard events stream records zero spawns by design and is never consulted — and a `fault` of `no-events|no-session|no-rollout` is a per-shard fact, not a refusal. `round` refuses a duplicate close and fails loud on findings without shard reports. `verify` takes exactly one of `--rule [--path ]` (greptile cascade check) or `--round N` (all-surface ledger check). `selftest` proves the rail's pure contracts beside the harvest law's two spellings, exiting nonzero naming each failed proof and the law line a one-sided edit diverged. ## [04]-[SHARD_CONTRACT] Per shard the rail writes `shard-.json` and `shard--brief.md`; dispatch writes `task-.md`, `shard--report.json`, `shard--events.jsonl`, and `shard--stderr.log`. Each report is the machine intake `reconcile`, `harvest`, and the reviewer-harvest agent parse, written as the shard's final act: ```json signature { "ledger": [{"id": "", "file": "", "severity": "", "verdict": "fixed|upgraded|pushed-back|already_resolved", "note": "", "shape": "substitution|collapse|completion"}], "improvements": [{"page": "", "pattern": "", "what": "", "axis": ""}], "refuted": [{"claim": "", "evidence": ""}], "capability": [], "routing": [{"target_file": "", "needed_change": ""}], "uncertain": [], "files": [], "gate_clean": true, "model": "", "wall_s": 0.0 } ``` `axis` and `shape` are fixer-stamped, never inferred; a blank `shape` counts under `unstamped` in `ShardStat.shapes`. `files` is the shard's touched roster, not its assigned set. Each `capability` row carrying a `members`, `roster`, or `symbols` list feeds the `reference_*` memory proposals; `uncertain` alone carries no mined structure, its rows reprinted verbatim by the feed. `model` keys the grade cohorts casefolded at reconcile. Per territory the rail writes `close-.json` and `close--brief.md`; each closer writes `close--report.json`: ```json signature {"rows": [{"id": ":", "verdict": "landed|refuted|already-landed|blocked", "note": ""}], "files": []} ``` `id` echoes the brief's stamped key, and a bare target path in `id` or `file` joins as fallback; the drain counts a row answered under any verdict. ## [05]-[DISTILL] Round dirs sit outside reviewer-harvest's write territory, so project its returned surface ledger into `/surface-ledger.json` yourself as `[{surface, text, path}]` rows — `surface` an engine name or alias, `text` the shortest guard substring unique on the surface, `path` blank falling to the engine's own oracle. Project one row per landed addition and consolidation — `corpus` rows never project, a ruling, index repair, or card proving itself on disk with no engine oracle; a receipt whose `source` is `surface-ledger` marks a malformed row (blank text or an unmapped surface name), never failed wording. - [REGISTRY]: `harvest` proposes new rows in the feed, `registry --check --rows` proves them (matcher compile, schema, dedup, each named surface resolving to its engine oracle on disk), and a judgment-bearing merge into an existing row is a hand edit re-proved by bare `registry --check`, which refuses `unmirrored` until every engine carries the class — a proposal's roster fills as its guards land. - [RAIL_GAPS]: rail gaps a round exposes harden the script. - [VERIFY]: `verify --round` re-proves each landed guard — a `.coderabbit.yaml` `path_instructions` clause by text, a greptile rule by substring over the resolved `greptile config` output (never by id — org rules re-key to server UUIDs) falling back to full-text over `.greptile/config.json` and `.greptile/rules.md` when the cascade truncates or a scoped rule never resolves at the probe path, the receipt `source` naming the oracle that matched, a macroscope topic file by presence and content, a blank path scanning `.macroscope/**/*.md` whole. - [FEED_OUTPUTS]: provenance and corroboration histograms feed review-the-reviewer — a class one engine raises and rounds keep refuting marks that engine's false-positive tendency, and multi-engine corroboration marks high-confidence work. - [PROPOSALS]: `memory-proposals/` under the round dir carries candidate memory files the orchestrator curates, never the live memory dir — the campaign memory (`project_cr_review_cycle_machine`) is the destination owner, taking verdicts and class calibrations as merged rulings, never narration, and a proposal duplicating a repo-owned fact dies at curation.