agentleFS
kurofunekurofune/claudit/.agents/skills/review/SKILL.md

review

Skill4 starsChanged 3 days agoMITView on GitHub

Single-lens code review: ONE reviewer agent sweeps the whole diff — implementation AND tests together — in one pass and emits the fenced JSON triage sidecar the review-loop gate parses (SHIP | SHIP-WITH-FIXES | REWORK plus severity_counts, invented_rate_pct, promoted_findings). One agent, one pass, one sidecar. It MUST NOT fan out. Run as the review-loop's body child (autonomous formula) or as the /wish orchestrator's single-lens review subagent.

  • Installs packages

192 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use close-spec, design-with-images and 10 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.
  • dzhngSkill

    close-spec

    When a spec under specs/<feature>/ is done shipping (a write-spec build, or any planned task that produced a spec), archive it to specs/done/ and rewrite it from a build-plan into a durable rationale — the why, the principles, the invariants — pointing back to the real code for the how. Use when implementation has landed and the plan no longer matches what shipped, or the user says a feature/spec is finished. Pairs with [write-spec](../write-spec/SKILL.md) (the plan this closes) and [review](../review/SKILL.md) (run before closing).

    Also in 5 projects that use this

  • dzhngSkill

    design-with-images

    Explore UI and visual design with image generation, then iterate the real implementation against the user-selected concept. Use when brainstorming visual directions, offering mockup variants, or implementing an approved generated design; do not stop at the mockups or the first code approximation.

    Also in 5 projects that use this

  • LambenthanSkill

    daily-arxiv

    每日从 arXiv 拉取新论文,过滤相关性,auto-ingest 高优先级论文,检测 SOTA 更新

    Also in 5 projects that use this

  • LambenthanSkill

    exp-eval

    实验判决门:Review LLM 独立评判实验结果 → 4 种判决路径 → 自动更新 claims confidence、ideas status、graph edges

    Also in 5 projects that use this

  • +3 more from dzhng
  • +5 more from Lambenthan

The file

Show its rules and text

We split this skill into the rules it gives an agent

17 rules. 0 are common, 4 are distinctive, and 13 are very specific to this project.

  • 0

    Common

    Most of the 157 edited versions we read keep these.

  • 4

    Distinctive

    This author's own choices. Worth a look.

  • 13

    Very specific

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

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    Before anything else: run djinn skills check --here in the repo you are working in.

    line 9
  2. Distinctive:

    Do NOT invoke any other review skill or command to do the review for you.

    line 34
  3. Very specific:

    Do NOT delegate any part of the review to a Task / Agent subagent — not for evidence-gathering, not for a "second opinion", not to …

    line 35
  4. Distinctive:

    Do not modify code: No edits, no fixes, no "while I was in there".

    line 44
  5. Very specific:

    Every promoted fix finding must cite a file:line that lands inside this diff — the harness ground-truths citations against exactly this …

    line 61
  6. Very specific:

    If the prompt carries no <bead> block, stop and say so — a review with no acceptance criteria in hand cannot be scored.

    line 108
  7. Very specific:

    Check the code, not the fix diff's intent.

    line 126
  8. Very specific:

    Read the bead first so the acceptance criteria are in hand before the code frames your judgment.

    line 205
  9. Distinctive:

    Read the diff in scope — implementation and tests in one sitting, not as two passes.

    line 220
  10. Very specific:

    The design rule: When the prompt carries ## The approved design note, also sweep the diff against it: its data shapes, the parts it said it …

    line 253
  11. Very specific:

    When the prompt also carries ## Points the design review left to you, read each point on that list: a real point the design review graded …

    line 262
  12. Very specific:

    Within NIT, grade a filing priority (priority): Every promoted NIT fix finding ALSO carries a priority grade that decides whether it …

    line 341
  13. Very specific:

    P2 ONLY: when that deferred behavior defect is severe enough that recording it in this sidecar is not enough — it has to be carried on the …

    line 358
  14. Very specific:

    Every promoted fix finding MUST cite a real file and line from the diff.

    line 372
  15. Very specific:

    Do not invent findings to look thorough, and do not suppress a real one to look agreeable.

    line 424
  16. Very specific:

    A check you cannot run is unverified, never graded: When a criterion's check cannot run on your machine for an environment reason — a …

    line 550
  17. Distinctive:

    After the JSON is in your visible text, stop.

    line 615

“Common” is measured: kept by at least 6 in 10 of the 157 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
<!-- djinn-compat-check: begin -->

Before anything else: run djinn skills check --here in the repo you are working in. If it exits non-zero, stop: relay its output to the user verbatim — it names the fix — and run no other step of this skill. On exit 0, continue.

<!-- djinn-compat-check: end -->

Review — single-lens

Overview

This skill is the single-lens code review. One reviewer agent reads the whole diff a bead produced — implementation and tests together — and emits one triage verdict.

The cost model is "one strong reviewer instead of a panel": the formula pins this step to the strongest model precisely because there is no panel behind it to catch what the single lens misses.

The output is a fenced json triage sidecar, so the loop gate (djinn.check.review_approved via ParseTriageSidecar) routes it with no special-casing — including the BLOCKER-count gate, the citation ground-truth gate, and the invented-rate gate.

The single-lens rule — no fan-out

You are the reviewer. You do the review yourself. Fanning out would reinstate the exact multi-agent cost this skill exists to cut, which is the whole point of the step. So, absolutely:

  • Do NOT invoke any other review skill or command to do the review for you.
  • Do NOT delegate any part of the review to a Task / Agent subagent — not for evidence-gathering, not for a "second opinion", not to parallelize the rubric below.

One agent, one pass, one sidecar. If the diff is large, read more of it — do not split it across helpers.

Two more hard rules, symmetric with every other review path:

  • Do not modify code. No edits, no fixes, no "while I was in there". The loop's paired fix step applies findings on the next iteration.
  • Do not write files. The sidecar goes in your visible response text.

Inputs

The invoker provides:

  1. The bead, in a <bead> block — its id, title, description, acceptance_criteria, design and notes, copied verbatim from the tracker by the invoker. Judge the bead from that block alone. Run no bd command: a reviewer may run in a sandbox with no beads database, and the block is the bead as the invoker read it. The acceptance_criteria lines are what the completeness concern below is scored against — one criteria row each.
  2. The diff to review — either an explicit base ref, or the pre-implementation baseline. Absent an explicit base, reconstruct it: git diff <base>..HEAD (plus git status / git diff for uncommitted work). Every promoted fix finding must cite a file:line that lands inside this diff — the harness ground-truths citations against exactly this range.
  3. The round's scope, under ## Scope of this round — full, spot-check or fix. It decides which diff you sweep; see Step 1. Absent, treat the round as full.

    On iteration 2 and later, extra blocks — "What iteration N-1 found" (the previous pass's promoted findings), "What the last fix changed" (git diff <that review's SHA>..HEAD), on a fix round ## Criteria rows from round N-1, and ## Findings the fix step declined when the fix step declined any finding. They are the incremental half of this review; see "Answering the previous iteration" below. On iteration 1 none of them is present and there is nothing to answer.

  4. The bead's comments, under ## Evidence on the bead — every comment on the bead, oldest first, each a ### <author> <time> heading over its body, read by the invoker when it built this prompt. Proof a worker posted as a bead comment (timings, capture paths, measurement runs) lives here, and so do the harness's djinn-evidence records of earlier passes. A djinn design review verdict comment arrives without its P3/P4 polish section: polish is never a code-review concern. The block is absent when the bead has no comments.
  5. The full test suite, under ## Test suite — the module's full test command (go test -short ./..., or the repo's configured command), run by the harness outside your sandbox on this iteration's tree before you: the revision it ran against, the exact command, its exit code, each failing test's --- FAIL: name and package, and the output tail. Read the full-suite result from this block. Inside a sandbox part of the suite cannot run (a test that execs ps, a test that writes a git index under the temp dir), so a module-wide go test ./... of your own verifies only part of it: never run one. When you need to run tests yourself, run only the packages the diff touches. The block is absent only when the harness ran no suite (a dry run); then cite none.
  6. The approved design note, under ## The approved design note — the plan a design reviewer of the other model family approved before any code was written. The implementer builds to it and may depart from it only with a stated reason: a Design departure: <what changed> — <why> line in the message body of the commit that departs, which you read in git log <base>..HEAD. The block is absent when the formula ran no design step; then the design rule below does not apply. The note never replaces the acceptance criteria: they stay what concern 2 scores. After it may come ## Points the design review left to you: the points the design review graded P2, each with its id, which the implementer had to settle.

If the prompt carries no <bead> block, stop and say so — a review with no acceptance criteria in hand cannot be scored.

Answering the previous iteration

The review loop is a conversation, not a series of independent samples. When the two blocks above are present, your sidecar MUST answer them — the harness computes the loop's progress from your answers, and a pass that ignores them reads as a loop that is making none.

For each finding the previous iteration promoted, emit one prior_findings entry — {"file", "line", "status"} — echoing the file and line exactly as the block wrote them, so the harness can match your entry to the finding:

  • "status": "resolved" — the fix landed; this is no longer true of the code.
  • "status": "unresolved" — still true, whether the fix missed it, only half-applied it, or made it worse.

Check the code, not the fix diff's intent. A fix that edited the cited line without addressing the finding is unresolved.

For each finding under ## Findings the fix step declined, rule on the decline. The fix step changed no code for it and gave evidence (a file:line, a test name, or command output) that the finding is wrong. Open that evidence yourself, then emit one prior_findings entry at the finding's file and line, with a one-sentence reason:

  • "status": "upheld" — the evidence does not refute the finding: it is still true of the code. Upheld counts as unresolved: re-promote the finding as a promoted_findings row at the same file and line, with an action that answers the fix step's evidence. The fix step may not decline it again.
  • "status": "withdrawn" — the evidence shows the finding was wrong (the cited test already covers the case, the path cannot be reached, the code does not do what the finding said). It closes; do not re-promote it.

Rule on whether the finding is true, never on what fixing it costs. A decline whose reason is cost, effort or a disagreement with the grade is no evidence: uphold it, and grade the re-promoted row under Step 3 like any other finding. A declined finding gets upheld or withdrawn, never resolved or unresolved; omitting its entry reads as upheld.

On a fix round, carry the criteria rows forward. For each row under ## Criteria rows from round N-1, copy it into your criteria array unchanged unless the fix diff changes the code the row cites, or the row was partial or fail; re-judge those rows against the code now. Every acceptance line still gets exactly one row.

Every unresolved entry MUST also be re-promoted as a promoted_findings row at the same file and line, with the severity it still deserves and an action describing what is left to do. The prior_findings entry is your verdict on the last fix; the promoted row is the work order. The harness carries an unresolved prior finding forward on your behalf if you omit the row, for as many passes as it survives — but it can only carry the wording of the reviewer who first raised it, which is a description of the code before any of these fixes touched it. Re-promoting is how the fixer learns what the half-applied fix actually left behind. Do not use the prior_findings entry alone as a way to say "still broken" and move on.

A re-promotion is not a NEW finding. origin describes findings this pass raised for the first time; the harness knows every citation the loop has been carrying — not just the last pass's — and ignores any origin you put on one of those, so you cannot accidentally get a re-promoted row filed away as a follow-up instead of fixed. Tag it or don't — the row goes back to the fix step either way.

For each NEW finding you promote, add an origin:

  • "origin": "regression" — the fix diff introduced it. Something in "What the last fix changed" is the reason this finding is true.
  • "origin": "latent" — it pre-existed that fix. This pass is simply the first to look there.

Judge origin from the fix diff, not from how serious the finding feels. The two are not the same claim and the harness treats them differently:

  • A regression is the loop's own damage. It keeps the loop iterating.
  • A latent IMPORTANT is filed as a P2 follow-up bead and is NOT handed to the fix step. The bead is tracked; the loop moves on.
  • A BLOCKER blocks either way. latent buys it nothing.

So mislabeling a latent finding as a regression keeps the loop open on work it was never meant to carry — the failure that deferred a bead after three passes each found one new IMPORTANT somewhere else. Mislabeling a real regression as latent ships it. Neither is a safe default; read the diff.

Both bullets above are about findings that are new at this citation. A latent IMPORTANT the loop is already carrying is not filed a second time, however many passes ago it was raised.

Omitting origin means regression (the conservative reading), and omitting prior_findings entirely means "every prior finding is still unresolved as far as the harness can tell" — both are honest fallbacks, neither is a shortcut.

Process

Step 1. Read the bead, then read the diff the scope names

Read the bead first so the acceptance criteria are in hand before the code frames your judgment. Then read ## Scope of this round; it names the diff you sweep:

  • full or spot-check — the block names git diff <claim SHA>..HEAD, the bead's whole diff. Read all of it. A spot-check is a forced second look at a clean SHIP: sweep it exactly as a full round, without trusting the earlier pass.
  • fix — the block names git diff <review anchor>..HEAD, the fix diff since the last review, and lists the open findings. Do NOT sweep the bead's whole diff. Review three things only: the fix diff, each open finding (is it resolved now?), and each declined finding (rule on it). Read the code around a hunk or a finding as far as you need to judge it, but raise a new finding only when the fix diff introduced it or it sits in code the fix diff changed.

Read the diff in scope — implementation and tests in one sitting, not as two passes. Reviewing them together is the point: the tests are evidence about the implementation, and the implementation is evidence about whether the tests are vacuous.

Step 2. Sweep the rubric

Sweep every concern below over the diff in scope: the whole diff on a full or spot-check round, the fix diff on a fix round. Each one is a named concern you are accountable for, not a suggestion.

Implementation concerns

#ConcernThe question you answer
1Correctness bugsBugs, nil dereferences, missing error paths, off-by-ones, unhandled failure branches. Does the code do what it says on any input, not just the happy one?
2Acceptance-criteria completenessWhich of the bead's acceptance_criteria are not yet represented in code? Walk them one at a time, recording each as a criteria row (Step 5); a criterion with no corresponding code or test is an IMPORTANT at minimum.
3Simplicity / deletable codeWhat could be deleted without breaking anything — dead branches, unused fields, a duplicated utility that already exists elsewhere in the repo, a layer of indirection carrying one caller?
4Behavior at scaleWhat breaks at 10× the input volume the bead assumes (the bead's Scalability Assumption if it states one)? Where is the hot path, and what did this diff put on it?
5Adversarial-caller boundary assumptionsWhich assumptions about callers are wrong if the caller is adversarial or merely careless — unvalidated inputs, trusted-but-external data, invariants asserted in a comment instead of in code?

Test concerns

#ConcernThe question you answer
6Vacuously-true test assertionsWould any assertion pass against an empty implementation? An assertion on a constant, on a value the test itself just set, or on "no error" alone is vacuous. Also: delete the most important line of implementation — which test catches it? If none, say so.
7Cheapest implementation that passes the testsWhat is the cheapest, dumbest implementation that passes every test in this diff? If shipping that would embarrass the author, the tests are underspecified — report it against the tests, not the implementation. When your prompt carries a ## Mutation check report, every survived test in it passes with the bead's code change reverted: give each one exactly one disposition — a guard (it pins behaviour the diff deliberately keeps) listed under mutation_survivors (Step 5), or an IMPORTANT kind: "fix" test finding citing the test's file:line that says what it must assert to fail without the change. A survivor with neither is a refused review.
8Uncovered scenariosWhat scenario is not covered at all — error paths, empty/boundary inputs, the concurrent case?
9Tests coupled to implementation detailsDo any tests assert on internals (call order, private shape, log text) rather than behavior, such that a legitimate refactor breaks them?

Concerns 1–7 are the ones this step is contractually accountable for; 8 and 9 round out the test lens.

The design rule. When the prompt carries ## The approved design note, also sweep the diff against it: its data shapes, the parts it said it would touch and how they connect, the approach it picked, the proof it promised, and what it said it would not do. Every place the code does something else is a departure. Find each departure's Design departure: line in the commit messages of git log <base>..HEAD. A departure with no such line is a finding, graded in Step 3 below; a departure with one is judged on its merits like any other change.

When the prompt also carries ## Points the design review left to you, read each point on that list: a real point the design review graded P2 and left for the implementer to settle while building. Find where the diff settles each one. A point the build did not settle is a finding, graded in Step 3 below like any other.

Step 3. Grade each finding

First decide whether the finding sits inside the bead's intent. The bead's intent is the paths its description, acceptance criteria and design name, plus every line of code those paths run — wherever it lives. A shared helper outside the bead's named feature is inside the intent when the bead's path calls it on an ordinary run; what decides is whether the bead's path reaches the defect, not which file or package holds it. A path that worked before this diff and that the diff breaks is inside the intent too. Outside it: code the diff touches that only another feature, an operator-only or debug entry point, or a path no criterion names runs; and a defect that predates the diff on such a path.

Assign every finding a severity:

  • BLOCKER — the change is wrong or unsafe as written: the bead's path gives the wrong result on the very input its acceptance criteria describe, a missing acceptance criterion that makes the bead false, data loss, a security hole, a broken invariant. A BLOCKER means the diff must not ship as-is. Data loss, a security hole or a broken invariant is a BLOCKER on any path. A defect on a failure branch of the bead's path — an error swallowed or misreported when a dependency times out or a lookup fails — is IMPORTANT, not BLOCKER, even when it yields wrong output on that branch.

    Visual work needs its capture. A bead whose diff changes a visual surface (web/, a terminal-UI package, a visual asset) is a BLOCKER when its evidence comment lacks the capture contract §4 requires, or when that capture misses an element the reference shows and the acceptance criteria name. Review runs before commit-push writes that comment, and the rule above holds here too: run no bd command for it. Look for the capture only where the invoker points you — the capture files the diff commits, capture artifacts in the worktree (.playwright-cli/, a saved tmux capture-pane text) that the diff or the invoker's prompt names, any implementer report or prior evidence the invoker pasted into your prompt, and the prompt's ## Evidence on the bead block with every capture path a comment there names. Open each one yourself; a golden file alone is not the capture, and a capture no supplied source reaches counts as missing. Record each capture and its per-element comparison in that criterion's criteria row, so commit-push carries it into the evidence comment. A design departure needs its reason. Code that departs from the approved design note with no Design departure: line naming it is an IMPORTANT fix finding at minimum — cite the departing file:line and name what the note said; the fix is to build to the note, or to state the reason in a commit. It is a BLOCKER when the unexplained departure also breaks an acceptance criterion, contradicts a repo ruling, or ships what the note's ## Out of scope said this bead would not do.

  • IMPORTANT — a real defect a caller will hit on a path inside the bead's intent: wrong output, a missing or swallowed error, a panic, a scale or boundary hazard at the volume the bead assumes, on an input an ordinary caller of that path produces. Also IMPORTANT: an acceptance criterion with no code or test (concern 2), a meaningfully underspecified test of the bead's own behavior, a mutation survivor that is not a guard (concern 7), and an unexplained design departure (below). Name the caller and the input in the action. A defect you cannot place on the bead's path is not IMPORTANT.
  • NIT — worth doing, not worth blocking on: naming, comment drift, a tidier arrangement, and every real defect that is not IMPORTANT under the rule above —

    • a defect on a path outside the bead's intent;
    • a rare case: it needs an input, timing or environment no ordinary caller of the bead's path produces, or a volume past the one the bead assumes;
    • a small cost: the harm is minor (an extra allocation, a redundant call, a misleading log line) and nothing returns a wrong result.

    These are never fixed inline; whether one becomes a follow-up bead is decided by the priority grade below. Grade a real behavior defect on another path or in a rare case P2 when it is worth tracking until someone fixes it, so it files as a follow-up instead of being lost.

  • INVENTED — reserved for the self-audit: a finding you could not anchor to a real file:line in the diff. Count it honestly rather than deleting it; the invented-rate is a diagnostic on the reviewer, and a silently-dropped invention teaches the harness nothing.

Within NIT, grade a filing priority (priority). Every promoted NIT fix finding ALSO carries a priority grade that decides whether it becomes a tracked backlog bead or stays report-only. The default is P4 — anything whose fix is more verification or polish rather than a behavior change. P4 explicitly includes pure polish, cosmetic, style, speculative-future and test-micro-tightening findings (the canonical noise: "extract a constant", "use bytes.Cut", "strengthen this assertion", "rename for clarity") and the absent-verification shapes — untested error path, named-coverage gap, drift trap between two sources. Those stay valuable as report content, but their fix is "add a test / comment / sync", not a behavior change; graded at the filing floor they buried the backlog under ~100 add-a-test beads (closed as a class in the 2026-08-03 triage). Grade P3 when the NIT names a deferred behavior defect — code in the diff that produces observably wrong runtime behavior (wrong output, panic, false verdict, resource leak, silent data loss) which the fix step is deferring rather than fixing this iteration. P3 is report-only: the floor moved to P2 (operator ruling D1, 2026-09-03), so a P3-graded NIT is dropped exactly like a P4 and stays in this sidecar for human reading. Grade P2 ONLY when that deferred behavior defect is severe enough that recording it in this sidecar is not enough — it has to be carried on the backlog until someone fixes it. A review-follow-up bead has to earn P2; P2 is the only grade that files. Litmus test: if the entire fix is "add a test", "add a comment", or "sync two sources", it is P4 no matter how real the underlying risk reads. When in doubt, P4 — this sidecar preserves the finding for human reading either way.

The file_nits filer reads this grade per-finding and files only at or above the floor, so an ungraded NIT falls back to the filer's batch default and is report-only. Grade explicitly when you want a finding tracked. BLOCKER/IMPORTANT findings route to the fix step, NOT the follow-up filer, so their priority is unused — omit it or leave it empty there, as for counters.

Every promoted fix finding MUST cite a real file and line from the diff. A finding you cannot anchor is not a finding — either anchor it or count it as INVENTED.

The one honest exception is a finding about a caller of the changed code — "this changed signature breaks its three call sites", "the invariant this diff altered is assumed here" — whose truthful citation is a file the diff never touched. Cite the caller's real file and line and set "caller_of_changed_code": true. The harness's citation gate then keeps the finding instead of rejecting it for pointing outside the diff. Do NOT set the flag to smuggle a citation you could not anchor: an unanchorable finding is still INVENTED.

A finding that is an anti-recommendation ("do NOT do X", "resist the urge to extract this") is promoted with "kind": "counter" rather than "kind": "fix". The fix step skips counters by contract; a counter carries no obligation to act.

A finding whose only fix is an action no worker may take is promoted with "kind": "lead" and a "lead_action" from this closed list:

  • reinstall-binary — the proof needs the installed djinn binary rebuilt and reinstalled (go install ./cmd/djinn), e.g. a criterion comparing djinn init --print-lead or --print-contract output against canon.
  • file-bead — the fix is filing a bead, and /create-bead refuses to file because the repo's skill copies are stale (its compatibility guard asks for djinn init --resync or a djinn upgrade).
  • edit-seat-file — the fix is an edit under .djinn/seats/, which workers never edit (contract §7).

The harness routes a lead finding to the lead and does not fail the bead on it. It keeps its severity, file and line. If a worker could do any part of the fix — code, a test, a doc, a commit, a proof run with the repo-built binary (go run ./cmd/djinn) — it is kind: "fix", not lead. Never use lead for a finding you would rather not send to the fix step. The criterion row such a finding blocks is "status": "unverified" with a note that opens lead action: and names the action.

Step 4. Pick the verdict

Pick it without kind: "lead" findings: a sidecar whose only BLOCKER or IMPORTANT findings are lead findings is SHIP, or SHIP-WITH-FIXES when other actionable findings remain.

  • SHIP — no actionable findings at severity ≥ IMPORTANT. Note that a zero-findings SHIP on a non-trivial diff earns exactly one adversarial re-review before it is trusted, so do not reach for it to end the loop cheaply — reach for it when the code has actually earned it.
  • SHIP-WITH-FIXES — ships once the listed BLOCKER/IMPORTANT findings are applied. This is the common verdict.
  • REWORK — the approach itself is wrong; applying the listed fixes would not get there.

Do not invent findings to look thorough, and do not suppress a real one to look agreeable. A truthful clean SHIP is a legitimate outcome.

Step 5. Emit the sidecar

Emit a fenced json block as the LAST thing in your visible response text — not inside a tool-result, not in a file. The harness extracts it from your assistant text stream; a sidecar that never reaches visible text reads as a parse failure and burns the loop's budget.

```json
{
  "verdict": "SHIP-WITH-FIXES",
  "severity_counts": { "BLOCKER": 0, "IMPORTANT": 3, "NIT": 3, "INVENTED": 0 },
  "invented_rate_pct": 0,
  "suite": { "revision": "8fe8b9ae1c0d4e2f9a7b6c5d4e3f2a1b0c9d8e7f", "exit": 0 },
  "criteria": [
    { "index": 1, "status": "pass", "file": "internal/djinn/session/run_formula.go", "line": "1318", "note": "buildLoopFixPrompt reads the prior iteration's review output" },
    { "index": 2, "status": "partial", "file": "internal/djinn/session/implementer_test.go", "line": "88", "note": "the skip path is implemented but only the happy path is tested; the suite-run at 8fe8b9ae exited 0" },
    { "index": 3, "status": "pass", "file": "docs/verdict-state.md", "line": "35", "note": "the doc names the new writer" },
    { "index": 4, "status": "unverified", "file": "internal/djinn/session/run_formula.go", "line": "1318", "note": "could not run: `go run honnef.co/go/tools/cmd/staticcheck@latest ./...` failed with `dial tcp: lookup proxy.golang.org: no such host`; nearest check run: `go vet ./internal/djinn/session/` exits 0" }
  ],
  "mutation_survivors": [
    { "test": "internal/djinn/session/run_formula_test.go:TestRunOneFormula_NoMutationGateInPipelineIsNoOp", "disposition": "guard", "note": "pins the no-gate pass-through the diff deliberately keeps" }
  ],
  "prior_findings": [
    { "file": "internal/djinn/session/formula_prompts.go", "line": "204", "status": "resolved" },
    { "file": "internal/djinn/session/run_formula.go", "line": "1332", "status": "unresolved" },
    { "file": "internal/djinn/session/fix_prompt.go", "line": "77", "status": "upheld", "reason": "the cited test feeds one finding; with two findings at one file the second is still dropped" },
    { "file": "internal/djinn/session/formula_prompts.go", "line": "290", "status": "withdrawn", "reason": "TestBuildFixPrompt_EmptyFindings at formula_prompts_test.go:140 already pins the empty set the finding called untested" }
  ],
  "promoted_findings": [
    {
      "severity": "IMPORTANT",
      "kind": "fix",
      "origin": "regression",
      "file": "internal/djinn/session/run_formula.go",
      "line": "1332",
      "action": "Handle the nil-step case before dereferencing step.Prompt — a renamed step id panics here instead of erroring.",
      "effort": "S"
    },
    {
      "severity": "IMPORTANT",
      "kind": "fix",
      "file": "internal/djinn/session/fix_prompt.go",
      "line": "77",
      "action": "Upheld after a decline: the dedup keys on file alone, so a review with two findings in one file hands the fixer only the first — key on file and line, and test it with two findings in one file.",
      "effort": "S"
    },
    {
      "severity": "IMPORTANT",
      "kind": "fix",
      "origin": "latent",
      "file": "internal/djinn/session/implementer.go",
      "line": "221",
      "action": "The empty-prompt skip path is untested and predates this diff — a pre-existing gap this pass is the first to reach.",
      "effort": "M"
    },
    {
      "severity": "NIT",
      "kind": "fix",
      "priority": "P2",
      "file": "internal/djinn/session/file_nits.go",
      "line": "204",
      "action": "An empty findings batch writes a zero-length artifact instead of skipping, so every downstream iteration reads a false 'filed' verdict until someone fixes it — deferred this iteration and severe enough to carry on the backlog.",
      "effort": "M"
    },
    {
      "severity": "NIT",
      "kind": "fix",
      "priority": "P3",
      "file": "internal/djinn/session/file_nits.go",
      "line": "241",
      "action": "The skip path logs the batch id twice, so the run log double-counts skipped batches — a deferred behavior defect, but the sidecar record is enough.",
      "effort": "S"
    },
    {
      "severity": "NIT",
      "kind": "fix",
      "priority": "P4",
      "file": "internal/djinn/session/file_nits_test.go",
      "line": "88",
      "action": "The empty-batch error path is untested — add a case.",
      "effort": "S"
    },
    {
      "severity": "NIT",
      "kind": "counter",
      "file": "internal/djinn/session/formula_prompts.go",
      "line": "330",
      "action": "Do NOT extract a shared helper for the two builders — they diverge on the codex fallback and the shared shape would grow a mode flag.",
      "effort": "S"
    }
  ]
}
```

Field contract:

  • verdict — exactly one of SHIP, SHIP-WITH-FIXES, REWORK.
  • severity_counts — an object counting BLOCKER, IMPORTANT, NIT, INVENTED. The BLOCKER count here MUST equal the number of BLOCKER entries in promoted_findings; a mismatch is a structural fault and halts the loop.
  • invented_rate_pct — INVENTED findings as a percentage of all findings (0 when you found none).
  • criteria — an array with one entry per acceptance_criteria line, in the bead's order, each {index, status, file, line, note}. Count lines the way the harness does: every non-blank line is one criterion. index is the 1-based line number among those; status is exactly pass, partial, fail or unverified (lowercase); file and line cite the code or test that satisfies the criterion (for a fail, where the work belongs); note says in one sentence what you observed there. Before you mark a criterion partial or fail because it says recorded in the evidence comment or names a capture or measurement, open the prompt's ## Evidence on the bead block and judge what its comments record; run no bd command for it. Proof found only there passes the criterion when it shows what the criterion asks, and the note names the comment (author and time). The harness copies each row onto the bead as its per-criterion evidence record, sets evidence_failed to the count of partial and fail rows, and sets evidence_unverified to the count of unverified rows. A sidecar missing a row for any line, or a row whose status is outside those four, is refused and the review re-runs — walk every line, including the ones about docs, tests and lint.

    A check you cannot run is unverified, never graded. When a criterion's check cannot run on your machine for an environment reason — a module proxy or network you cannot reach, a port you cannot bind, a tool not installed — first try the nearest check you can run (the installed tool's version, go vet, the package's own tests) and name it. Then write the row with "status": "unverified" and a note that opens could not run:, quotes the command and its error, and names the nearest check and its result. Such a row is never partial or fail, and the failure to run is never a BLOCKER or IMPORTANT finding: it says nothing about the work, and the operator decides. A check that runs and fails is graded as usual. A row whose only gap is a kind: "lead" finding is unverified too, with a note that opens lead action: and names the lead_action (Step 3).

  • suite — {revision, exit} copied from the prompt's ## Test suite block: the revision line (full, or abbreviated to at least 7 characters) and the exit code as a number. A sidecar whose suite is absent, or whose revision or exit differs from that block, is refused and the review re-runs. Omit it only when the prompt carries no ## Test suite block. Every criteria row whose check is a test run names the suite run in its note (for example "the suite-run at 8fe8b9ae exited 0"), not a run of your own.
  • mutation_survivors — an array of {test, disposition, note}, one entry per survived test in the prompt's ## Mutation check report that you judge a guard (rubric 7). test is the report's file:Name (or bare Name), disposition is exactly guard, and note names the behaviour it pins. A survivor you do not accept as a guard is instead an IMPORTANT kind: "fix" finding citing its file. A sidecar that leaves a survivor with neither is refused and the review re-runs. Omit the array when there is no report or it names no survivor.
  • prior_findings — an array of {file, line, status, reason}, one entry per finding the PREVIOUS iteration promoted and one per finding under ## Findings the fix step declined, with status exactly resolved, unresolved, upheld or withdrawn (see "Answering the previous iteration"). upheld and withdrawn are for declined findings only and each needs a reason, one sentence on what the evidence showed; reason is optional on the other two. upheld counts as unresolved and withdrawn as resolved. Absent on iteration 1, where there is no previous review; an absent array on a later iteration reads as "no prior finding could be confirmed resolved". Each unresolved or upheld entry MUST have a matching promoted_findings row at the same citation; a withdrawn entry has none.
  • promoted_findings — an array (possibly empty) of {severity, kind, file, line, action, effort}, plus origin from iteration 2 on, priority on NIT fix findings and caller_of_changed_code on a caller finding (see Step 3). kind is fix, counter or lead. A lead finding also carries lead_action, exactly one of reinstall-binary, file-bead or edit-seat-file (Step 3); any other value reads as kind: "fix". A lead finding still counts in severity_counts, but not in the verdict. effort is a rough size (S / M / L).
  • origin — "regression" (the last fix introduced this finding) or "latent" (it pre-existed that fix). Omitted or unrecognized reads as regression. It decides whether an IMPORTANT holds the loop open or is filed as a P2 follow-up bead; a BLOCKER blocks under either origin. It applies only to findings NEW at their citation — a re-promotion of a finding the loop is already carrying, from any earlier pass, carries no origin, and any origin on one is ignored.
  • priority — the per-finding filing grade for NIT fix findings: "P4" (report-only — the default, including the polish and absent-verification shapes), "P3" (a deferred behavior defect — report-only, below the P2 floor), or "P2" (a deferred behavior defect severe enough to be carried on the backlog until fixed, worth a tracked review-follow-up bead — the ONLY grade that files), per the within-NIT rubric in Step 3. Optional and unused for BLOCKER/IMPORTANT (they route to the fix step, not the filer) and for counters; omit it or leave "" there. An omitted or empty grade on a NIT falls back to the filer's batch default priority, which is below the P2 floor — an ungraded NIT is therefore report-only.

After the JSON is in your visible text, stop.

Scope boundary

This skill judges the diff. It does NOT:

  • Judge whether the bead was the right work to do (that is settled at filing, by /create-bead).
  • Judge whether the bead's criteria are concrete enough to implement against (that is /ac-quality-review, which already ran before implementation).
  • Render the bead's final acceptance verdict (that is /verify-acceptance, which runs after this loop on the settled tree).
  • Apply its own findings (that is the loop's paired fix step).

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.