agentleFS
kurofunekurofune/claudit/.agents/skills/ac-quality-review/SKILL.md

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.

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
  1. Very specific:

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

    line 9
  2. Very specific:

    If it would, the criteria are under-specified: the verdict is UNDERSPEC, naming each line that admits a skin-deep result.

    line 20
  3. Very specific:

    Use the draft verbatim, or the bd show fields.

    line 41
  4. Distinctive:

    Ask the Minimum-Output Simulation of each line:

    line 49
  5. Distinctive:

    If not, the line is operator-required.

    line 76
  6. Distinctive:

    No middle ground: one weak line among ten still rolls UNDERSPEC, because the worker will produce the embarrassing minimum for that line.

    line 99
  7. Distinctive:

    No shipped formula runs this skill after the claim.

    line 161
  8. Distinctive:

    Read-only: Never edit the bead; tightening is the caller's job.

    line 253

≈ “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.

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

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:

  1. Draft (filing time — /create-bead, no ID yet): the draft's acceptance_criteria, plus its description and type when known. Review the supplied text; do not call bd show.
  2. bead_id (an already-filed bead — summoner --preflight): read bd 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 questionTriggers 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_column remains under internal/" 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.json itself) — 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 classFires when the criterion requires…Canonical example
(a) interactive-operatora 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-actiona 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-sentence minimum_output and a rewrite_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 — exactly CONCRETE or UNDERSPEC. 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 tagged embarrassing; 0 when CONCRETE.
  • findings[] — one entry per embarrassing segment (index, verbatim criterion, minimum_output, rewrite_hint); empty when CONCRETE.
  • operator_required[] — one entry per line the unattended autonomous harness cannot satisfy (Step 3b), ORTHOGONAL to verdict and findings[]; [] in the common case. Each entry: index, verbatim criterion, reason (trigger class — interactive-operator / external-action — and why), manual_step. A non-empty array blocks /create-bead and marks the bead OPERATOR-REQUIRED in summoner --preflight.
  • operator_required_count — len(operator_required).
  • bead_type — the bead's type, 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:

  • CONCRETE
  • UNDERSPEC
  • operator_required

Verdict mapping

CallerWhenReadsActs
/create-beadon 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_idoperator_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 gap

Every 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 test

Each 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 plan

Lines 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_id input) — bd show exits non-zero: UNDERSPEC with one finding naming the lookup failure.
  • acceptance_criteria empty or null — UNDERSPEC with one finding {index: 0, criterion: "(empty)", minimum_output: "Zero criteria means any implementation passes by vacuous truth", rewrite_hint: "File the criteria before implementing"}.
  • bd unavailable (bead_id input) — UNDERSPEC with 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.

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.