ac-quality-review
Skill4 starsChanged 3 days agoMITView on GitHub
Filing-time review of a bead's acceptance_criteria. Probes whether each criterion is concrete enough that the cheapest literal implementation would not embarrass the author, without ever demanding an implementation choice. Emits a structured CONCRETE | UNDERSPEC verdict so `/create-bead` (the filing gate, contract §2) can refuse to emit a vague bead. Runs at filing time, inside /create-bead, before `bd create`; `summoner --preflight` also reads its operator_required[] field.
In this repository14 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- beadsSkill
- consult-councilSkill
- create-beadSkill
- freshness-triageSkill
- playwright-cliSkill
- reaperSkill
- reviewSkill
- rubSkill
- verify-acceptanceSkill
- wishSkill
- create-beadSkill
- wishSkill
The file
We split this skill into the rules it gives an agent
8 rules. About 0 are common, 5 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
3
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.
- Very specific: line 20
If it would, the criteria are under-specified: the verdict is UNDERSPEC, naming each line that admits a skin-deep result.
- Very specific: line 41
Use the draft verbatim, or the bd show fields.
- Distinctive: line 49
Ask the Minimum-Output Simulation of each line:
- Distinctive: line 76
If not, the line is operator-required.
- Distinctive: line 99
No middle ground: one weak line among ten still rolls UNDERSPEC, because the worker will produce the embarrassing minimum for that line.
- Distinctive: line 161
No shipped formula runs this skill after the claim.
- Distinctive: line 253
Read-only: Never edit the bead; tightening is the caller's job.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “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 -->AC-Quality Review
Overview
This skill is the filing-time acceptance-criteria quality gate. It answers one question per bead:
"What is the cheapest implementation that literally satisfies every line of this bead's
acceptance_criteria? Would shipping that be embarrassing?"
If it would, the criteria are under-specified: the verdict is UNDERSPEC, naming each line that admits a skin-deep result. /create-bead runs it on every draft before bd create, which is where the work contract (§2) settles acceptance-criteria quality; summoner --preflight reads the same sidecar.
One agent, one pass, one verdict: no iteration, no fan-out. Filing is the cheapest moment to refuse a vague bead.
What it judges. The acceptance_criteria text alone — not the description (intent prose may be conversational), not code (none exists yet), not whether the bead is the right work. The bar is the outcome, never the build: a line that states what a user sees and can do, what a command prints or what an endpoint returns is concrete without naming a technology, library, file, function or test. Implementation is the worker's call, and a gate that demands one passes the author's guesses downstream.
Second, orthogonal axis — mode-compatibility. A criterion can be concrete AND still require a human: an operator continuing between steps, or an action outside the repository. This axis is operator_required[], independent of the verdict: a CONCRETE bead can carry a non-empty operator_required[] (Step 3b).
Inputs
Exactly one of:
- Draft (filing time —
/create-bead, no ID yet): the draft'sacceptance_criteria, plus itsdescriptionandtypewhen known. Review the supplied text; do not callbd show. bead_id(an already-filed bead —summoner --preflight): readbd show <bead_id> --json | jq -r '.[0] | {type, acceptance_criteria, description}'.
Both supplied: review the draft and echo the bead_id in bead. Neither: stop and ask.
Process
Step 1. Read the criteria
Use the draft verbatim, or the bd show fields. A missing type is echoed as "". Empty or null acceptance_criteria → UNDERSPEC (Failure-mode handling).
Step 2. Split criteria into segments
Each non-blank line is one segment. Trim whitespace, preserve order, index 1..N.
Step 3. Apply the rubric to each segment
Ask the Minimum-Output Simulation of each line:
"If a junior implementer read this single line and wrote the cheapest code that literally satisfies it — no taste, no extra effort, just 'the words on the page' — would the result embarrass the bead author?"
| Rubric question | Triggers UNDERSPEC when |
| Observable? | An abstract noun or adjective with no observable signature: "works well", "idempotence contract", "well-defined behaviour", "passes correctness", "scales well". Rewrite as the named operation, equivalence and scope (Render(Render(F)) byte-identical to Render(F) on every step). |
| Number measured where? | A number — a threshold, a count, a size, a time ("under 5 s", "500 ticks", "10k rows") — with no place it is measured: no test, fixture, command, env-var-gated integration test or "verified by dogfooding" step. |
| Precondition or trigger unstated? (behavioural) | The given-state or trigger is omitted AND the omission changes the cheapest implementation. "Returns 401 for expired tokens" passes; "Shows an error message" fails (error from what? one hard-coded banner satisfies it). Rewrite as Given X → Y. Never flag an implicit precondition that is unambiguous in the bead's context. |
| Action and result named? (interactive UI) | "Interactive table", "clickable rows", "a chart the user can explore" with no line naming what the user does and what happens (hover → what is shown, click → where it goes, which key → what). |
| Volume named? (UI showing a list or data set) | "Shows a list of alerts" with no data volume the view must stay usable at, and no filter, sort or paging line. |
| Test artifact as outcome? | "100% coverage", "component renders with props" — a property of the build, not the result. Acceptable when the bead is about the tests themselves. |
Epic closing line checkable at HEAD? (bead_type is epic) | A line predicts a measurement of a live artifact ("the live ledger ends at or under 32 KB") or asks for a sighting in a log, ledger or run, with no command, test or query that checks it at HEAD. Rewrite hint: "state the rule a command checks at HEAD (a test name, a grep, a bd query)". |
Never flag a line for:
- naming no render primitive, library, file, function, axis implementation or test name, when it states what the user sees and can do or what the system does;
- being structural on a technical bead (API, infrastructure, developer tool, refactor): "POST /api/tokens returns 201 with {token, expires_at}" and "no reference to
old_columnremains underinternal/" are concrete; - missing UI lines on a bead with no user interface;
- missing empty, loading or error states, keyboard reach or tooltip fit: work contract §4 makes them implicit criteria for every visual change.
Step 3b. Apply the mode-compatibility check to each segment
Independently of the rubric, ask of each line:
"Could the unattended autonomous harness — no human present, formula-autonomous mode (the harness owns terminal status: it records the evidence comment on the bead and writes
last-status.jsonitself) — satisfy this criterion on its own?"
If not, the line is operator-required. There are exactly two trigger classes, and both turn on a human being needed:
| Trigger class | Fires when the criterion requires… | Canonical example |
| (a) interactive-operator | a human operator interacting mid-task — continuing between steps, answering a prompt, driving an --interactive workflow, making a live judgment call. | "Dogfood /wish --interactive end-to-end, continuing past each step." |
| (b) external-action | a human's action OUTSIDE the repository — a login, a physical device, an approval in another system, a console-only deploy with no API. | "Get the design partner to approve the layout in a screen-share." |
Naming a recording surface is not a trigger. A criterion that names the bead's evidence comment, last-status.json, or the verify report as where a verification is recorded is satisfied by the harness writing it in formula mode, and is never operator-required. Judge the VERIFICATION the line asks for, not the surface it names: "manual bd round trip" or "documented by hand in the evidence record" describe a record, not a human step.
Emit one operator_required[] entry per operator-required line: its 1-based index, the verbatim criterion, the reason (trigger class and why) and the manual_step (what the operator does by hand). Flag a line ONLY when the harness genuinely cannot satisfy it, not when a human could do it faster. No drain step re-checks this after filing: /create-bead rewords it, and summoner --preflight reports it before a drain.
Step 4. Tag each segment
pass— the cheapest literal implementation would not embarrass you.embarrassing— it would ship something skin-deep; give a one-sentenceminimum_outputand arewrite_hint.
A rewrite hint asks for an outcome, a precondition, an action and its result, or a place a number is measured — never for a technology, a library or a file layout.
Step 5. Emit the verdict
- All segments
pass→ CONCRETE. - Any segment
embarrassing→ UNDERSPEC.
No middle ground: one weak line among ten still rolls UNDERSPEC, because the worker will produce the embarrassing minimum for that line. The cheapest fix is to tighten the one line.
Output
Emit one fenced json sidecar matching the schema below. Optional prose may precede it; the gate reads only the first json fence. Never emit several JSON fences or unfenced JSON.
JSON sidecar schema
{
"verdict": "CONCRETE" | "UNDERSPEC",
"bead": "phoenix-abcd",
"criteria_count": 4,
"embarrassing_count": 2,
"findings": [
{
"index": 2,
"criterion": "The dashboard works well on large accounts",
"minimum_output": "Any dashboard that renders at all satisfies 'works well'; nothing says what a large account is or what must stay true",
"rewrite_hint": "Name the volume and the outcome: e.g. 'with 5,000 orders the dashboard lists them paged 50 at a time, sorted newest first', checked by a fixture at that size"
},
{
"index": 4,
"criterion": "Search returns in under 200 ms",
"minimum_output": "No test times a search; reasoning in prose passes the number",
"rewrite_hint": "Name where the number is measured: a benchmark, a fixture-backed test, or 'verified by dogfooding'"
}
],
"operator_required_count": 0,
"operator_required": [],
"bead_type": "feature",
"acceptance_criteria": "Orders list shows the newest 50 orders\nThe dashboard works well on large accounts\n..."
}Field rules
verdict— exactlyCONCRETEorUNDERSPEC. Callers branch on this token; any other is a failed review.bead— the reviewed bead id; for a draft with no ID,"draft".criteria_count— total non-blank segments.embarrassing_count— segments taggedembarrassing;0whenCONCRETE.findings[]— one entry perembarrassingsegment (index, verbatimcriterion,minimum_output,rewrite_hint); empty whenCONCRETE.operator_required[]— one entry per line the unattended autonomous harness cannot satisfy (Step 3b), ORTHOGONAL toverdictandfindings[];[]in the common case. Each entry:index, verbatimcriterion,reason(trigger class — interactive-operator / external-action — and why),manual_step. A non-empty array blocks/create-beadand marks the beadOPERATOR-REQUIREDinsummoner --preflight.operator_required_count—len(operator_required).bead_type— the bead'stype, echoed verbatim; the epic row reads it.acceptance_criteria— the raw criteria text, echoed verbatim.
Required tokens (skill-prompt-contract gate)
The startup-time prompt-contract check scans this file for these literal strings. Each MUST remain present:
CONCRETEUNDERSPECoperator_required
Verdict mapping
| Caller | When | Reads | Acts |
/create-bead | on every draft, before bd create, passing the draft text (no bead_id) | verdict, findings[], operator_required[] | CONCRETE with an empty operator_required[] → continues in the same turn to its bd create --graph filing; UNDERSPEC or a non-empty operator_required[] → rewords the flagged lines and re-runs, inside a 2-attempt tightening budget; still failing on the third pass → no bd create |
summoner --preflight (cmd/summoner/preflight_checker.go) | over the scoped ready set, before a drain, passing each bead_id | operator_required[] (decoded as checks.ACQualitySidecar) | reports each bead as OPERATOR-REQUIRED, autonomous-ready or CHECK-FAILED |
No shipped formula runs this skill after the claim.
Worked examples
Example 1 — CONCRETE (a UI bead that names no implementation)
acceptance_criteria:
The revenue view shows one bar per month for the last 20 months, ranked by revenue, with month and revenue labels readable at 20 bars
Hovering a bar shows its month, revenue, order count and change on the year before
Clicking a bar filters the orders table below to that month
Given no orders in a month → its bar reads "no orders" instead of a zero-height gapEvery line states what the user sees and can do. None names SVG, Canvas or a charting library, and none needs to: a CSS-div that shows those bars, that hover payload and that click filter is not embarrassing, because it does what the bead asks. Verdict: CONCRETE.
Example 2 — UNDERSPEC (weak lines)
acceptance_criteria:
Bar chart shows revenue per period
Scales to large datasets
Test coverage for all branches- Line 1 names no period, no ranking, nothing the user can read off it or do with it: one aggregate bar satisfies it. The hint asks for the bars, the labels and the hover or click result — not for a library.
- Line 2's "large datasets" has no number and no place it is measured.
- Line 3 is a property of the build, not an outcome.
Verdict: UNDERSPEC, one finding per line.
Example 3 — CONCRETE (a technical bead, structural lines)
acceptance_criteria:
POST /api/tokens returns 201 with {token, expires_at} for valid {user_id}
Returns 400 with error code 'invalid_user' for unknown user_id
Returns 429 after 5 requests/minute per user_id, in the endpoint's integration testEach line names an observable signature. A technical bead carries no UI lines, and none is asked for. Verdict: CONCRETE.
Example 4 — CONCRETE verdict WITH a populated operator_required[] (orthogonality proof)
Bead djinn-ipee.8 (the real bead that motivated this axis — djinn-ccyz.40):
acceptance_criteria:
/wish parses a goal string into an ordered list of formula steps
--dry-run prints the resolved step plan without executing
Each step's prompt is rendered from the goal + the step template
Errors in a step halt the wish and print the failing step id
Unit tests cover the parser, the renderer, and the halt path
Dogfood /wish --interactive end-to-end, continuing past every step prompt, and note each place the executed step order diverged from the --dry-run planLines 1–5 are concrete and autonomously satisfiable. Line 6 is ALSO concrete (it names the exact command and observation) — but it is operator-required under class (a): /wish --interactive blocks on a human continuing past each step prompt, so no unattended agent reaches the end of the walkthrough. Note what does NOT contribute: the line could have added "and record it in the bead's evidence comment" and still be class-(a)-only, because the harness records that itself. So the verdict is CONCRETE AND operator_required[] is non-empty:
{
"verdict": "CONCRETE",
"bead": "djinn-ipee.8",
"criteria_count": 6,
"embarrassing_count": 0,
"findings": [],
"operator_required_count": 1,
"operator_required": [
{
"index": 6,
"criterion": "Dogfood /wish --interactive end-to-end, continuing past every step prompt, and note each place the executed step order diverged from the --dry-run plan",
"reason": "Trigger (a) interactive-operator: /wish --interactive blocks on a human continuing past each step prompt, so an unattended agent never reaches the end of the walkthrough.",
"manual_step": "Operator runs /wish --interactive by hand and walks the steps, noting each divergence from the --dry-run plan."
}
]
}/create-bead refuses to file this bead as written, and summoner --preflight reports it OPERATOR-REQUIRED.
Example 5 — UNDERSPEC (an epic closing line predicts a live figure)
Draft epic, type epic: line 1 Both children are closed: bd list --parent <this epic id> --all --flat --json shows no child in any status but closed passes — a command checks it at HEAD. Line 2 After the rotation child lands, the live ledger ends at or under 32 KB trips the epic row: it predicts a size the live ledger reaches only after a later seat run, so the closer has nothing to run. Finding hint: state the rule a command checks at HEAD, e.g. go test -short ./internal/djinn/seat/ -run TestRotateLedger_TodayAndYesterdayNeverMove exits 0.
Failure-mode handling
- Bead not found (
bead_idinput) —bd showexits non-zero:UNDERSPECwith one finding naming the lookup failure. acceptance_criteriaempty or null —UNDERSPECwith one finding{index: 0, criterion: "(empty)", minimum_output: "Zero criteria means any implementation passes by vacuous truth", rewrite_hint: "File the criteria before implementing"}.bdunavailable (bead_idinput) —UNDERSPECwith one finding naming the toolchain absence.
Universal constraints
- Judge the criteria text verbatim, never the title or description.
- Read-only. Never edit the bead; tightening is the caller's job.
- Cap prose at ~500 words plus the JSON sidecar.
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.

