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
- dzhng/skillstheir own version, first seen Nov 15, 2026
- muxy-app/muxytheir own version, first seen Nov 15, 2026
- macro-inc/macrotheir own version, first seen Nov 15, 2026
- yagizdo/quivertheir own version, first seen Nov 15, 2026
- markmhendrickson/neotomatheir own version, first seen Nov 15, 2026
- felipeam86/pipe-skillstheir own version, first seen Nov 15, 2026
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.
dzhngSkillclose-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
dzhngSkilldesign-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
LambenthanSkilldaily-arxiv
每日从 arXiv 拉取新论文,过滤相关性,auto-ingest 高优先级论文,检测 SOTA 更新
Also in 5 projects that use this
LambenthanSkillexp-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
Other versions192 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 192
- garrytan/gstack★ 142ksame name
- ansible/ansible★ 71ksame name
- docling-project/docling★ 71ksame name
- traefik/traefik★ 66ksame name
- ClickHouse/ClickHouse★ 51ksame name
- temporalio/temporal★ 24ksame name
- ccch1mneyyy/dsh-Go★ 24ksame name
- tisfeng/Easydict★ 15ksame name
- juicedata/juicefs★ 15ksame name
- elie222/inbox-zero★ 13ksame name
182 more not listed
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository14 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- ac-quality-reviewSkill
- beadsSkill
- consult-councilSkill
- create-beadSkill
- freshness-triageSkill
- playwright-cliSkill
- reaperSkill
- rubSkill
- verify-acceptanceSkill
- wishSkill
- create-beadSkill
- wishSkill
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
- Very specific: line 9
Before anything else: run djinn skills check --here in the repo you are working in.
- Distinctive: line 34
Do NOT invoke any other review skill or command to do the review for you.
- Very specific: line 35
Do NOT delegate any part of the review to a Task / Agent subagent — not for evidence-gathering, not for a "second opinion", not to …
- Distinctive: line 44
Do not modify code: No edits, no fixes, no "while I was in there".
- Very specific: line 61
Every promoted fix finding must cite a file:line that lands inside this diff — the harness ground-truths citations against exactly this …
- Very specific: line 108
If the prompt carries no <bead> block, stop and say so — a review with no acceptance criteria in hand cannot be scored.
- Very specific: line 126
Check the code, not the fix diff's intent.
- Very specific: line 205
Read the bead first so the acceptance criteria are in hand before the code frames your judgment.
- Distinctive: line 220
Read the diff in scope — implementation and tests in one sitting, not as two passes.
- Very specific: line 253
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 …
- Very specific: line 262
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 …
- Very specific: line 341
Within NIT, grade a filing priority (
priority): Every promoted NIT fix finding ALSO carries a priority grade that decides whether it … - Very specific: line 358
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 …
- Very specific: line 372
Every promoted fix finding MUST cite a real file and line from the diff.
- Very specific: line 424
Do not invent findings to look thorough, and do not suppress a real one to look agreeable.
- Very specific: line 550
A check you cannot run is
unverified, never graded: When a criterion's check cannot run on your machine for an environment reason — a … - Distinctive: line 615
After the JSON is in your visible text, stop.
“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.
Files
<!-- 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/Agentsubagent — 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:
- 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 nobdcommand: a reviewer may run in a sandbox with no beads database, and the block is the bead as the invoker read it. Theacceptance_criterialines are what the completeness concern below is scored against — onecriteriarow each. - The diff to review — either an explicit base ref, or the
pre-implementation baseline. Absent an explicit base, reconstruct it:
git diff <base>..HEAD(plusgit status/git difffor uncommitted work). Every promoted fix finding must cite afile:linethat lands inside this diff — the harness ground-truths citations against exactly this range. The round's scope, under
## Scope of this round—full,spot-checkorfix. It decides which diff you sweep; see Step 1. Absent, treat the round asfull.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 afixround## Criteria rows from round N-1, and## Findings the fix step declinedwhen 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.- 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'sdjinn-evidencerecords of earlier passes. Adjinn design reviewverdict 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. - 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 execsps, a test that writes a git index under the temp dir), so a module-widego 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. - 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: aDesign departure: <what changed> — <why>line in the message body of the commit that departs, which you read ingit 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 apromoted_findingsrow at the samefileandline, with anactionthat 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.
latentbuys 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:
fullorspot-check— the block namesgit diff <claim SHA>..HEAD, the bead's whole diff. Read all of it. Aspot-checkis a forced second look at a cleanSHIP: sweep it exactly as afullround, without trusting the earlier pass.fix— the block namesgit 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
| # | Concern | The question you answer |
| 1 | Correctness bugs | Bugs, 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? |
| 2 | Acceptance-criteria completeness | Which 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. |
| 3 | Simplicity / deletable code | What 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? |
| 4 | Behavior at scale | What 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? |
| 5 | Adversarial-caller boundary assumptions | Which 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
| # | Concern | The question you answer |
| 6 | Vacuously-true test assertions | Would 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. |
| 7 | Cheapest implementation that passes the tests | What 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. |
| 8 | Uncovered scenarios | What scenario is not covered at all — error paths, empty/boundary inputs, the concurrent case? |
| 9 | Tests coupled to implementation details | Do 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 nobdcommand 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 savedtmux capture-panetext) 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 beadblock 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'scriteriarow, so commit-push carries it into the evidence comment. A design departure needs its reason. Code that departs from the approved design note with noDesign departure:line naming it is an IMPORTANTfixfinding at minimum — cite the departingfile:lineand 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 scopesaid 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 theaction. 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
prioritygrade 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 realfile:linein 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 comparingdjinn init --print-leador--print-contractoutput against canon.file-bead— the fix is filing a bead, and/create-beadrefuses to file because the repo's skill copies are stale (its compatibility guard asks fordjinn init --resyncor 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-findingsSHIPon 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 ofSHIP,SHIP-WITH-FIXES,REWORK.severity_counts— an object countingBLOCKER,IMPORTANT,NIT,INVENTED. TheBLOCKERcount here MUST equal the number ofBLOCKERentries inpromoted_findings; a mismatch is a structural fault and halts the loop.invented_rate_pct—INVENTEDfindings as a percentage of all findings (0when you found none).criteria— an array with one entry peracceptance_criterialine, 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.indexis the 1-based line number among those;statusis exactlypass,partial,failorunverified(lowercase);fileandlinecite the code or test that satisfies the criterion (for afail, where the work belongs);notesays in one sentence what you observed there. Before you mark a criterionpartialorfailbecause it saysrecorded in the evidence commentor names a capture or measurement, open the prompt's## Evidence on the beadblock and judge what its comments record; run nobdcommand for it. Proof found only there passes the criterion when it shows what the criterion asks, and thenotenames the comment (author and time). The harness copies each row onto the bead as its per-criterion evidence record, setsevidence_failedto the count ofpartialandfailrows, and setsevidence_unverifiedto the count ofunverifiedrows. A sidecar missing a row for any line, or a row whosestatusis 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 anotethat openscould not run:, quotes the command and its error, and names the nearest check and its result. Such a row is neverpartialorfail, 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 akind: "lead"finding isunverifiedtoo, with anotethat openslead action:and names thelead_action(Step 3).suite—{revision, exit}copied from the prompt's## Test suiteblock: the revision line (full, or abbreviated to at least 7 characters) and the exit code as a number. A sidecar whosesuiteis 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 suiteblock. Everycriteriarow whose check is a test run names the suite run in itsnote(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 persurvivedtest in the prompt's## Mutation checkreport that you judge a guard (rubric 7).testis the report'sfile:Name(or bareName),dispositionis exactlyguard, andnotenames the behaviour it pins. A survivor you do not accept as a guard is instead an IMPORTANTkind: "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, withstatusexactlyresolved,unresolved,upheldorwithdrawn(see "Answering the previous iteration").upheldandwithdrawnare for declined findings only and each needs areason, one sentence on what the evidence showed;reasonis optional on the other two.upheldcounts as unresolved andwithdrawnas 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". Eachunresolvedorupheldentry MUST have a matchingpromoted_findingsrow at the same citation; awithdrawnentry has none.promoted_findings— an array (possibly empty) of{severity, kind, file, line, action, effort}, plusoriginfrom iteration 2 on,priorityon NITfixfindings andcaller_of_changed_codeon a caller finding (see Step 3).kindisfix,counterorlead. Aleadfinding also carrieslead_action, exactly one ofreinstall-binary,file-beadoredit-seat-file(Step 3); any other value reads askind: "fix". Aleadfinding still counts inseverity_counts, but not in theverdict.effortis 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 asregression. 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 NITfixfindings:"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 trackedreview-follow-upbead — 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).
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
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.

