Design spec
A design spec fixes what a capability must do, in terms an outsider can check without reading the code. It is a
pair: intent (what the capability is for, argued with) and criteria (what must be true of the outcome,
evaluated). Intent without criteria cannot be checked. Criteria without intent cannot be questioned when they turn
out to encode the wrong goal.
This skill is spec-anchored: the spec stays and is compared against on every change. It is not scaffolding discarded
after the build.
Route
| The request |
Mode |
| write a spec for a capability, or backfill one for existing code |
Write |
| change what an existing spec says |
Write, then Review the changed parts |
| split a spec that has grown past what its readers need |
Write, the steps under Split a spec |
| judge a spec, or decide whether it is ready |
Review |
| derive tests from a spec |
Derive tests |
| a criterion whose verdict flipped on an unchanged state |
Write: split its graph path, placement test first |
A criterion whose verdict flips on an unchanged state is not a function under its judge. In practice this is an
eval-checked criterion of a skill-instruction use case.
Not for a node of a first-generation SDD project spec (under .agents/specs/, with a .feature suite): that is
the sdd plugin's start-mission. This skill covers the design spec only, not the functional spec beneath it.
Write
Put one capability in one folder: README.md holds the spec, graph.md holds the decision graph when the
behavior branches. Write these sections of README.md, in order. Keep each as short as it can be.
- Title and outcome. One sentence naming the single outcome.
- What. Open with the problem: who has it, and what goes wrong without this capability. Then the intent: what the
capability does about it. Legible to a non-engineer. A definition belongs in Key terms, not here.
- Non-goals. Plausible goals this capability excludes. "Must not crash" is not a non-goal.
- Key terms. Each term a criterion leans on, defined once.
- Actors and goals. A table of ID, actor, and goal (
A1.1, A1.2, ...), one row per goal. Include people affected
by the outcome who never invoke it; a missed use case usually hides there. Derive use cases from actors, never by
walking the interface.
- Use cases. One per actor goal, each its own heading
### UCn — <title> (<actor IDs>) with these labelled
bullets, in this order: Trigger, Entry node (only when graph.md exists: the graph node the trigger enters
at), Entry points (grouped by surface, the primary delivery first and named as such), Inputs, Success, and Extensions, every path from the trigger that does not reach the goal, as
UCn.m sub-bullets. A use case with no extensions says extensions: none, <why>. The use case states the goal and
result and is delivery agnostic; the delivery (a skill, a command, a library call) appears only under Entry points,
and in the criteria group for that adapter.
- Criteria. A list of boolean statements about the outcome, one per line, each with an ID and bound to a use
case and, where a graph exists, to an edge in it. Each is self-contained: decidable from its own text, with any
context it depends on, such as the path or the use case, written into it. The cited use case and edge are a trace,
not part of its meaning.
- Open questions. What is unresolved, marked. Empty before the spec is ready.
- References. Links to rationale, sibling specs, and the home of any shared fact.
Give every item of these lists an ID a reader can cite: N1 for a non-goal, K1 for a key term, A1 for an actor and
A1.1 for its goal, UC1 for a use case and UC1.1 for its extension, R1 for a criterion, E1 for a graph edge,
Q1 for an open question. An ID is never reused: a removed item retires its ID.
An ID labels a criterion's text; the text is the criterion. Use the ID to cite it and to name its tests. Before
the spec is first ready, revise criteria freely. After that, changing a criterion's text retires its ID, gives the
criterion a new one, and rechecks the tests derived from it. A key term counts as part of the text of every criterion
that names it, so changing a key term changes every such criterion and retires each one's ID.
Settle one section at a time. Grill the spec with the user, one section at a time, in the order above. Each
section is derived from the ones before it, so a wrong outcome or a missed actor carries into every criterion. For
each section:
- Draft it. In a backfill the code supplies the draft, and it still goes through these steps: code shows what the
capability does, not what it should do. Decided behavior the code lacks is still written as a criterion; the gap
goes to the tracker.
- Judge the draft against the criteria that apply to it: C1 on the outcome, C2 on the non-goals, C3 on the actors and
use cases, C4 to C6 on the criteria, C8 on the open questions. Bracket each criterion as you write it: state its
strictest and its most lenient reasonable reading, and check both against the use case's extensions and its graph
paths. If they agree, the criterion is crisp. If they disagree, apply the placement test (under Design spec
versus functional spec) first, and tighten the text only after that. The readings are a check made while writing, not text in the spec.
- Show the user that section and the questions it raises, and nothing beyond it.
- When the user agrees, commit the section, then go to the next.
A change to an earlier section reopens every section after it. With no user to ask (a headless run), draft every
section and put each question under Open questions; the spec is not ready until they are answered.
Split by capability, never by layer. A child spec is a capability an actor can name (what they get), such as
update or history, so the folder names say what the system does. Never split into a library spec, a CLI spec, and a
skill spec: one capability reached through three deliveries is one spec, whose use cases list the deliveries as entry
points. A layer split writes the functional spec early and scatters one outcome across files.
Size the spec by the tasks that read it. When the actors and use cases are settled, list the tasks that will read
the spec: changing one behavior, deriving its tests, checking scope, a consumer checking its contract. If most of them
need less than half of it, split the capability into child specs along the line those tasks share, each with its own
outcome; the parent keeps the shared terms and links each child. Do not split by section type, such as a separate
criteria file: every task needs a slice of every section.
Split a spec. Decide the line once the use cases are settled, and move the text once every section is agreed, so
a revision never straddles files.
- Table the tasks, the sections each needs, and its share of the spec. Split only when most shares are under half.
- Put in the parent what every task needs: the What, Non-goals, Key terms, Actors, the criteria groups that span
children (such as
Adapters or the output contract), the open questions they share, References, and a table
linking each child with its use cases.
- Give each child its use cases, the criteria groups bound to them, its open questions, a title naming its own
outcome, and a line linking the parent's terms. A child is never read without its parent.
- Keep every ID: IDs are shared across the parent and its children, and a retired one stays retired. Move each graph
edge with the criteria that cite it; edges several children cite stay in the parent's
graph.md.
- Make the split a commit of its own that moves text without rewording it, and check that no line was lost.
Leave out implementation design, task lists, stack choices, alternatives analysis, and whether a criterion is built
yet. The gap between the criteria and the code is found by checking one against the other; the work to close it lives
in the project tracker, linked by criterion ID. Link rationale (an ADR, an issue, a research topic) and do not copy it
in.
Design spec versus functional spec. The design spec states outcomes: what the actor gets or can tell apart. An
encoding is how an outcome is spelled or carried: names, literal values and codes, exit numbers, output fields and
formats, flag syntax, message wording, the order of checks when every order gives the same kind of outcome. Encodings,
internal contracts, module behavior, and scenarios belong to the lower rung: the functional spec co-located with the
implementation, and the code and tests beneath it.
- Hold the outcome, vary the encoding. If the actor reaches the goal under any encoding that is stable and keeps
distinct outcomes distinct, the encoding belongs to the lower rung. The design spec keeps the outcome and the
property the actor needs ("distinct per cause", "stable"). A program actor reads encodings but needs no particular
one, so it is judged the same way. Only a case whose outcome differs between two readings of a criterion is a grain
defect in the design spec; a difference in encoding alone moves the encoding down. This is the placement test.
- Decide in prose only what building cannot settle. The design spec holds what must be judged: which goal and
which outcome are wanted. What writing and running the code settles goes to the rung that runs it, where a
deterministic test gives one verdict per state. A prose scenario an agent interprets does not.
Notation. The design spec names no scenario form. Use cases and criteria are the contract. A use case may carry
Gherkin or EARS for one scenario when it clarifies; the functional spec or test plan owns the form of the rest.
Several surfaces. When the same code is reached through several adapters (a CLI, a library, an MCP server), state
each outcome once without naming an adapter: "the reference is reported missing", not "exit 1". One criteria group,
Adapters, states what each adapter's actor needs of its form, such as each outcome told apart, distinct per cause,
and stable. The mapping from each outcome to an exit code, stream, return value, or thrown error belongs to the lower
rung, pinned by its tests. Group a use case's entry points by surface. Behavior that a skill's instructions add on top, such as a fallback or what to tell the user,
is its own use case. Its criteria are checked by an eval run of the skill, not by a deterministic test.
Decision graph. When the behavior branches, draw the decisions in graph.md, in the format of the decision graph
reference, and cite its edge IDs from the criteria. Omit it for a spec that states facts or a table.
Review
Load the criteria reference and judge the spec against C1 to C9 in number order. A spec is ready when none of C1 to
C9 fails, every check under Validate passes, and Open questions is empty.
Iterate before you present. After each judgment, fix every failing criterion in the spec yourself, then judge it again.
Repeat a few times, stopping when none fails or when a round fixes nothing new. Churn signals misplacement: a
criterion revised in two or more rounds goes through the placement test before it is revised again. Take only the fixes the spec and its
sources settle. A fix that needs a decision the user has not made (a scope call, a rule with two reasonable readings)
is not a fix: leave it, and put it under Open questions with the options and your recommendation. Keep each round a
change of the spec's text only; never move the spec's scope without asking.
Then present, in one message: what you changed across the rounds, grouped by criterion; the final pass or fail of each
criterion with the line that still fails it; and the open questions that need the user, each with a recommendation. A
reviewer asked only to judge, not to edit (a read-only review of someone else's spec), skips the iteration and reports
what is wrong and what would fix it.
Derive tests
Build tests from the criteria list, one test or group per criterion ID, as native, deterministic tests of the
project's own test stack. Put the criterion ID in the name of its test or group. Do not write a feature file for an
agent to run: an agent running prose scenarios spends tokens on every run and cannot be relied on to follow them. A
criterion of a skill-instruction use case is the exception: an eval run of the skill checks it. Any other criterion
that cannot become such a test fails C5; send it back to Write instead of guessing.
Lower-rung writes may add, never change. A test that pins an encoding the spec leaves open, such as the exit code for
an outcome, is the build adding to the lower rung: a minor change, made freely. Changing what an existing test
asserts is a breaking change: take it to the owner instead of making it.
Validate
Check the spec folder before you hand it back. A cold reader runs the same checks later against the folder and its
git history, not against your report. Each line is pass or fail; README.md and graph.md are the spec folder's.
- V1 A standalone or parent
README.md has an H1 title followed by a one-sentence outcome, then these ## sections
in this order: What, Non-goals, Key terms, Actors and goals, Use cases, Criteria, Open questions, References. A
child's README.md has an H1 title with its own outcome, a link to the parent's terms, then Use cases, Criteria,
and Open questions (grep -n '^##\? ' README.md).
- V2 Every item under Non-goals, Key terms, Actors and goals, Use cases, Criteria, and Open questions, and every edge
in
graph.md, starts with its ID (N, K, A, UC, R, Q, E), and no ID labels two items across the parent
and its children.
- V3 No ID that
git log -p shows removed from the spec labels a different item now.
- V4 Each use case is a
### UCn — <title> (<actor IDs>) heading with Trigger, Entry points, Inputs, Success, and
Extensions in that order, and its Extensions are UCn.m items or read extensions: none, <why>. When graph.md
exists, an Entry node bullet sits between Trigger and Entry points and names a node that exists in graph.md.
- V5 Every criterion cites a use case ID that exists. When
graph.md exists, every edge ID a criterion cites exists
in it, and every outcome node in it is reached by an edge some criterion cites.
- V6
grep -nEi '\b(TBD|TODO)\b|not (yet )?built' README.md graph.md finds nothing.
- V7 No criterion names a source file, module, or internal function of the implementation, or pins an encoding (an
exit number, a literal code or value, flag syntax, an output field or format, message wording) unless the actor's
goal fails under some other stable encoding that keeps distinct outcomes distinct.
- V8 The spec holds no implementation design, task list, stack choice, or alternatives analysis; rationale appears
only as links.
- V9 A spec presented as ready has no item under Open questions and no node in
graph.md marked open.
- V10 A Review run without the user (headless, or read-only) added or removed no non-goal, actor, or use case: the
diff of the spec over the review adds or removes no line that starts with an
N, A, or UC ID.
- V11 A split commit only moves lines.
git show -U0 --format= <commit> | grep -E '^[-+][^-+]' | cut -c2- | sort | uniq -u lists only the lines a split adds: each child's title and its link to the parent's terms, and the parent's
table of children.
- V12 After Derive tests, every criterion ID, except those of a skill-instruction use case, names at least one test or
group in the project's own suite, and no
.feature file was added for an agent to run.
- V13 No child spec folder is named for a delivery or layer (such as
cli, lib, library, skill, mcp).
References
- Criteria reference (
references/criteria.md): C1 to C9 with their pass conditions and the failure modes they
catch. Load it for Review, and for step 2 of each section in Write.
- Decision graph reference (
references/decision-graph.md): the shape of graph.md, its edge IDs, and the
decision table and state list that may replace it.
- Rationale and sources: the research topic
design-spec-criteria, decisions
D8 onward in its
conclusion.md.
1---2name: spec3description: Writes, revises, reviews, and splits a design spec, the document that states what a capability must do (intent, use cases, and checkable criteria on the outcome) before or alongside its code, and derives tests from one. Use when asked to spec a feature, write, revise, or backfill the spec for X, split a spec, judge whether a spec is ready, or turn a spec into tests, even if they only say "is this spec good" or "review the spec". Not for a node of a first-generation SDD project spec under .agents/specs/ that carries a .feature suite (the sdd plugin's start-mission).4metadata:5 source: https://skillmd.com/skills/cyberuni/spec6---78# Design spec910A **design spec** fixes what a capability must do, in terms an outsider can check without reading the code. It is a11pair: **intent** (what the capability is for, argued with) and **criteria** (what must be true of the outcome,12evaluated). Intent without criteria cannot be checked. Criteria without intent cannot be questioned when they turn13out to encode the wrong goal.1415This skill is spec-anchored: the spec stays and is compared against on every change. It is not scaffolding discarded16after the build.1718## Route1920| The request | Mode |21| --- | --- |22| write a spec for a capability, or backfill one for existing code | [Write](#write) |23| change what an existing spec says | [Write](#write), then [Review](#review) the changed parts |24| split a spec that has grown past what its readers need | [Write](#write), the steps under **Split a spec** |25| judge a spec, or decide whether it is ready | [Review](#review) |26| derive tests from a spec | [Derive tests](#derive-tests) |27| a criterion whose verdict flipped on an unchanged state | [Write](#write): split its graph path, placement test first |2829A criterion whose verdict flips on an unchanged state is not a function under its judge. In practice this is an30eval-checked criterion of a skill-instruction use case.3132Not for a node of a first-generation SDD project spec (under `.agents/specs/`, with a `.feature` suite): that is33the `sdd` plugin's `start-mission`. This skill covers the design spec only, not the functional spec beneath it.3435## Write3637Put one capability in one folder: `README.md` holds the spec, `graph.md` holds the decision graph when the38behavior branches. Write these sections of `README.md`, in order. Keep each as short as it can be.39401. **Title and outcome.** One sentence naming the single outcome.412. **What.** Open with the problem: who has it, and what goes wrong without this capability. Then the intent: what the42 capability does about it. Legible to a non-engineer. A definition belongs in Key terms, not here.433. **Non-goals.** Plausible goals this capability excludes. "Must not crash" is not a non-goal.444. **Key terms.** Each term a criterion leans on, defined once.455. **Actors and goals.** A table of ID, actor, and goal (`A1.1`, `A1.2`, ...), one row per goal. Include people affected46 by the outcome who never invoke it; a missed use case usually hides there. Derive use cases from actors, never by47 walking the interface.486. **Use cases.** One per actor goal, each its own heading `### UCn — <title> (<actor IDs>)` with these labelled49 bullets, in this order: **Trigger**, **Entry node** (only when `graph.md` exists: the graph node the trigger enters50 at), **Entry points** (grouped by surface, the primary delivery first and named as such), **Inputs**, **Success**, and **Extensions**, every path from the trigger that does not reach the goal, as51 `UCn.m` sub-bullets. A use case with no extensions says `extensions: none, <why>`. The use case states the goal and52 result and is delivery agnostic; the delivery (a skill, a command, a library call) appears only under Entry points,53 and in the criteria group for that adapter.547. **Criteria.** A list of boolean statements about the outcome, one per line, each with an ID and bound to a use55 case and, where a graph exists, to an edge in it. Each is self-contained: decidable from its own text, with any56 context it depends on, such as the path or the use case, written into it. The cited use case and edge are a trace,57 not part of its meaning.588. **Open questions.** What is unresolved, marked. Empty before the spec is ready.599. **References.** Links to rationale, sibling specs, and the home of any shared fact.6061**Give every item of these lists an ID** a reader can cite: `N1` for a non-goal, `K1` for a key term, `A1` for an actor and62`A1.1` for its goal, `UC1` for a use case and `UC1.1` for its extension, `R1` for a criterion, `E1` for a graph edge,63`Q1` for an open question. An ID is never reused: a removed item retires its ID.6465**An ID labels a criterion's text; the text is the criterion.** Use the ID to cite it and to name its tests. Before66the spec is first ready, revise criteria freely. After that, changing a criterion's text retires its ID, gives the67criterion a new one, and rechecks the tests derived from it. A key term counts as part of the text of every criterion68that names it, so changing a key term changes every such criterion and retires each one's ID.6970**Settle one section at a time.** Grill the spec with the user, one section at a time, in the order above. Each71section is derived from the ones before it, so a wrong outcome or a missed actor carries into every criterion. For72each section:73741. Draft it. In a backfill the code supplies the draft, and it still goes through these steps: code shows what the75 capability does, not what it should do. Decided behavior the code lacks is still written as a criterion; the gap76 goes to the tracker.772. Judge the draft against the criteria that apply to it: C1 on the outcome, C2 on the non-goals, C3 on the actors and78 use cases, C4 to C6 on the criteria, C8 on the open questions. Bracket each criterion as you write it: state its79 strictest and its most lenient reasonable reading, and check both against the use case's extensions and its graph80 paths. If they agree, the criterion is crisp. If they disagree, apply the placement test (under **Design spec81 versus functional spec**) first, and tighten the text only after that. The readings are a check made while writing, not text in the spec.823. Show the user that section and the questions it raises, and nothing beyond it.834. When the user agrees, commit the section, then go to the next.8485A change to an earlier section reopens every section after it. With no user to ask (a headless run), draft every86section and put each question under Open questions; the spec is not ready until they are answered.8788**Split by capability, never by layer.** A child spec is a capability an actor can name (what they get), such as89`update` or `history`, so the folder names say what the system does. Never split into a library spec, a CLI spec, and a90skill spec: one capability reached through three deliveries is one spec, whose use cases list the deliveries as entry91points. A layer split writes the functional spec early and scatters one outcome across files.9293**Size the spec by the tasks that read it.** When the actors and use cases are settled, list the tasks that will read94the spec: changing one behavior, deriving its tests, checking scope, a consumer checking its contract. If most of them95need less than half of it, split the capability into child specs along the line those tasks share, each with its own96outcome; the parent keeps the shared terms and links each child. Do not split by section type, such as a separate97criteria file: every task needs a slice of every section.9899**Split a spec.** Decide the line once the use cases are settled, and move the text once every section is agreed, so100a revision never straddles files.1011021. Table the tasks, the sections each needs, and its share of the spec. Split only when most shares are under half.1032. Put in the parent what every task needs: the What, Non-goals, Key terms, Actors, the criteria groups that span104 children (such as `Adapters` or the output contract), the open questions they share, References, and a table105 linking each child with its use cases.1063. Give each child its use cases, the criteria groups bound to them, its open questions, a title naming its own107 outcome, and a line linking the parent's terms. A child is never read without its parent.1084. Keep every ID: IDs are shared across the parent and its children, and a retired one stays retired. Move each graph109 edge with the criteria that cite it; edges several children cite stay in the parent's `graph.md`.1105. Make the split a commit of its own that moves text without rewording it, and check that no line was lost.111112Leave out implementation design, task lists, stack choices, alternatives analysis, and whether a criterion is built113yet. The gap between the criteria and the code is found by checking one against the other; the work to close it lives114in the project tracker, linked by criterion ID. Link rationale (an ADR, an issue, a research topic) and do not copy it115in.116117**Design spec versus functional spec.** The design spec states outcomes: what the actor gets or can tell apart. An118encoding is how an outcome is spelled or carried: names, literal values and codes, exit numbers, output fields and119formats, flag syntax, message wording, the order of checks when every order gives the same kind of outcome. Encodings,120internal contracts, module behavior, and scenarios belong to the lower rung: the functional spec co-located with the121implementation, and the code and tests beneath it.122123- **Hold the outcome, vary the encoding.** If the actor reaches the goal under any encoding that is stable and keeps124 distinct outcomes distinct, the encoding belongs to the lower rung. The design spec keeps the outcome and the125 property the actor needs ("distinct per cause", "stable"). A program actor reads encodings but needs no particular126 one, so it is judged the same way. Only a case whose outcome differs between two readings of a criterion is a grain127 defect in the design spec; a difference in encoding alone moves the encoding down. This is the placement test.128- **Decide in prose only what building cannot settle.** The design spec holds what must be judged: which goal and129 which outcome are wanted. What writing and running the code settles goes to the rung that runs it, where a130 deterministic test gives one verdict per state. A prose scenario an agent interprets does not.131132**Notation.** The design spec names no scenario form. Use cases and criteria are the contract. A use case may carry133Gherkin or EARS for one scenario when it clarifies; the functional spec or test plan owns the form of the rest.134135**Several surfaces.** When the same code is reached through several adapters (a CLI, a library, an MCP server), state136each outcome once without naming an adapter: "the reference is reported missing", not "exit 1". One criteria group,137`Adapters`, states what each adapter's actor needs of its form, such as each outcome told apart, distinct per cause,138and stable. The mapping from each outcome to an exit code, stream, return value, or thrown error belongs to the lower139rung, pinned by its tests. Group a use case's entry points by surface. Behavior that a skill's instructions add on top, such as a fallback or what to tell the user,140is its own use case. Its criteria are checked by an eval run of the skill, not by a deterministic test.141142**Decision graph.** When the behavior branches, draw the decisions in `graph.md`, in the format of the decision graph143reference, and cite its edge IDs from the criteria. Omit it for a spec that states facts or a table.144145## Review146147Load the criteria reference and judge the spec against C1 to C9 in number order. A spec is ready when none of C1 to148C9 fails, every check under [Validate](#validate) passes, and Open questions is empty.149150Iterate before you present. After each judgment, fix every failing criterion in the spec yourself, then judge it again.151Repeat a few times, stopping when none fails or when a round fixes nothing new. Churn signals misplacement: a152criterion revised in two or more rounds goes through the placement test before it is revised again. Take only the fixes the spec and its153sources settle. A fix that needs a decision the user has not made (a scope call, a rule with two reasonable readings)154is not a fix: leave it, and put it under Open questions with the options and your recommendation. Keep each round a155change of the spec's text only; never move the spec's scope without asking.156157Then present, in one message: what you changed across the rounds, grouped by criterion; the final pass or fail of each158criterion with the line that still fails it; and the open questions that need the user, each with a recommendation. A159reviewer asked only to judge, not to edit (a read-only review of someone else's spec), skips the iteration and reports160what is wrong and what would fix it.161162## Derive tests163164Build tests from the criteria list, one test or group per criterion ID, as native, deterministic tests of the165project's own test stack. Put the criterion ID in the name of its test or group. Do not write a feature file for an166agent to run: an agent running prose scenarios spends tokens on every run and cannot be relied on to follow them. A167criterion of a skill-instruction use case is the exception: an eval run of the skill checks it. Any other criterion168that cannot become such a test fails C5; send it back to Write instead of guessing.169170Lower-rung writes may add, never change. A test that pins an encoding the spec leaves open, such as the exit code for171an outcome, is the build adding to the lower rung: a minor change, made freely. Changing what an existing test172asserts is a breaking change: take it to the owner instead of making it.173174## Validate175176Check the spec folder before you hand it back. A cold reader runs the same checks later against the folder and its177git history, not against your report. Each line is pass or fail; `README.md` and `graph.md` are the spec folder's.178179- V1 A standalone or parent `README.md` has an H1 title followed by a one-sentence outcome, then these `##` sections180 in this order: What, Non-goals, Key terms, Actors and goals, Use cases, Criteria, Open questions, References. A181 child's `README.md` has an H1 title with its own outcome, a link to the parent's terms, then Use cases, Criteria,182 and Open questions (`grep -n '^##\? ' README.md`).183- V2 Every item under Non-goals, Key terms, Actors and goals, Use cases, Criteria, and Open questions, and every edge184 in `graph.md`, starts with its ID (`N`, `K`, `A`, `UC`, `R`, `Q`, `E`), and no ID labels two items across the parent185 and its children.186- V3 No ID that `git log -p` shows removed from the spec labels a different item now.187- V4 Each use case is a `### UCn — <title> (<actor IDs>)` heading with Trigger, Entry points, Inputs, Success, and188 Extensions in that order, and its Extensions are `UCn.m` items or read `extensions: none, <why>`. When `graph.md`189 exists, an Entry node bullet sits between Trigger and Entry points and names a node that exists in `graph.md`.190- V5 Every criterion cites a use case ID that exists. When `graph.md` exists, every edge ID a criterion cites exists191 in it, and every outcome node in it is reached by an edge some criterion cites.192- V6 `grep -nEi '\b(TBD|TODO)\b|not (yet )?built' README.md graph.md` finds nothing.193- V7 No criterion names a source file, module, or internal function of the implementation, or pins an encoding (an194 exit number, a literal code or value, flag syntax, an output field or format, message wording) unless the actor's195 goal fails under some other stable encoding that keeps distinct outcomes distinct.196- V8 The spec holds no implementation design, task list, stack choice, or alternatives analysis; rationale appears197 only as links.198- V9 A spec presented as ready has no item under Open questions and no node in `graph.md` marked `open`.199- V10 A Review run without the user (headless, or read-only) added or removed no non-goal, actor, or use case: the200 diff of the spec over the review adds or removes no line that starts with an `N`, `A`, or `UC` ID.201- V11 A split commit only moves lines. `git show -U0 --format= <commit> | grep -E '^[-+][^-+]' | cut -c2- | sort |202 uniq -u` lists only the lines a split adds: each child's title and its link to the parent's terms, and the parent's203 table of children.204- V12 After Derive tests, every criterion ID, except those of a skill-instruction use case, names at least one test or205 group in the project's own suite, and no `.feature` file was added for an agent to run.206- V13 No child spec folder is named for a delivery or layer (such as `cli`, `lib`, `library`, `skill`, `mcp`).207208## References209210- **Criteria reference** (`references/criteria.md`): C1 to C9 with their pass conditions and the failure modes they211 catch. Load it for Review, and for step 2 of each section in Write.212- **Decision graph reference** (`references/decision-graph.md`): the shape of `graph.md`, its edge IDs, and the213 decision table and state list that may replace it.214- **Rationale and sources**: the research topic215 [design-spec-criteria](https://github.com/cyberuni/cyber-sdd/tree/main/.research/design-spec-criteria), decisions216 D8 onward in its `conclusion.md`.