spec-design

Spec Design

Requirements clarification dispatcher. Turns vague requests (a one-liner, an HTML prototype, a PRD, a Figma link, or even a "spec" the user wrote themselves) into two files that downstream processes can mechanically consume:

• docs/specs/<topic>/spec.md — Why + Findings + What + Out of scope + Open questions（+ References）
• docs/specs/<topic>/validation-contract.md — VAL-XXX-NNN assertions, each containing Behavior + Tool + Evidence
• docs/specs/<topic>/umbrella.md — generated only when the scale gate triggers a split

The Validation Contract is the load-bearing artifact.test-designer uses VAL as its primary input;deep-review 's spec-conformance reviewers read VAL to confirm that a PR's diff satisfies every assertion.

When to use

• Someone proposes a new feature, a public API change, a schema migration, a CLI subcommand, or any user-visible behavior change
• The user says "let's write a spec", "clarify the requirements", "write a spec for X", "brainstorm a feature"
• The user's own spec needs to be reviewed against auriga standards before downstream stages can consume it

Do not use for:

• Pure implementation strategy adjustments where the external behavior contract does not change (refactoring, swapping algorithms, swapping libraries) — go straight to plan
• Bug-fix tasks with existing reproduction steps (the bug report itselfisthe requirement) — use systematic-debugging
• Pure documentation / configuration tasks with no behavior surface

Iron rules (spec / plan boundary)

spec = why + what; plan = how.

If a change would move the external behavior contract — anything observable by users, external callers, API consumers, or downstream file formats — it must go through this skill before entering plan.

If a change is purely internal — same observable behavior, just a different implementation strategy — skip this skill and go straight to plan.

spec.md records the external surface and the motivation. Once a section reads like "we will use file X, function Y, together with helper function Z", it has overstepped into how — leave that part for the plan stage, and do not write it into spec.md。

Prohibitions (dispatcher boundaries)

• Do not invoke this skill again after implementation has started or a draft has already been made. The audit and Q+GUESS loop dispatched by
• Do not let spec.md accumulate How. Module names, class names, exact API signatures, data structure choices, library names — none of these are in scope. If the user proactively provides them, write them into the future plan, not into the spec.
• Do not skip Q+GUESS's confidence stopping point. Stopping at about 95% predictive confidence is discipline; forcing all the way to 100% narrows the conversation too much and turns the spec into a plan in disguise.
• Do not fabricate VAL numbers. Every VAL must come from a real and independent external behavior. Padding them to look thorough turns the contract into noise.

Inputs (five modes)

Mode	Form	A1 handling
1. Text description	A sentence or a paragraph	Go straight to Q+GUESS after repository pre-research
2. Static HTML prototype	User-provided HTML file	Open, screenshot / enumerate pages, extract interactive elements, infer user stories
3. PRD	Notion / Markdown / PDF	Summarize key sections, flag ambiguities, add to Q list
4. Figma link	URL	Ask the user to attach screenshots or PNG exports of key pages;Do notattempt to scrape Figma directly
5. User-provided spec	The user thinks it is already written	Mustaccording to ## 用户自带 spec 审计 review it once—never accept it wholesale

All five modes share the same downstream contract:docs/specs/<topic>/ under spec.md + validation-contract.md a pair of files.

Flow

A. 调研   →  B. 定方向、定切分  →  C. 落到文件   →  D. 闸门与交接

Phase A — Research

A1. Pre-research + intake + audit. Before asking any clarifying questions:

• Read the repository entry points in this priority order: first AGENTS.md and CLAUDE.md(agent-facing sources of truth), then the relevant docs/ subdirectories, then use git log to look at recent commits. Only when AGENTS.md and CLAUDE.md both do not exist, read README.md(README is human-facing, may be promotional, or may already be outdated relative to the agent contract).
• Collect project-level spec rules: search for rules under docs/rules/spec/ that are relevant to this requirement—they specify which questions must be clarified at the spec stage (required clarification dimensions, required sections, domain-specific acceptance requirements). The directory is anchored at the repository root: use git rev-parse --show-toplevel to resolve the repository root, search <仓库根>/docs/rules/spec/; when cwd is not at the repository root and there is a closer docs/rules/spec/(monorepo subpackage) between cwd and the repository root, collect both levels—subpackage-level rules are treated as supplements/narrowing of the repository-level rules, and in case of conflict the subpackage level prevails; for non-git repositories, fall back to searching relative to cwd. When the directory does not exist or has no relevant files, record "no project-specific spec rules". Every item that the rules require to be explicit but for which there is not yet an answer in the input goes into the A2 clarification list.
• If the user gave a file path / commit / issue number,open them—do not paraphrase
• If the input belongs to modes 2–4 (HTML / PRD / Figma), extract the key visible elements into a draft ## Findings section
• If the input is mode 5 (user-provided spec), run the audit checklist below; any missing item becomes a Q in A2
• Exception: only when the user's message simultaneously explicitly gives the target file pathandthe exact change surface, skip A1. Even then, record a sentence "skipping pre-research because the user gave X" so that this decision is traceable.

A1.5. Scale check. Estimate whether this needs to be split (see ## 拆分规模闸门). If any signal triggers, go to B0 in Phase B.

A2. Q+GUESS clarification loop.

• Each round, via AskUserQuestion / request_user_input ask only one question
• Every question comes with a hypothesis + confidence (e.g., "I guess it is X, ~60% confident")
• Stop at about 95% predicted confidence—do notforce it to 100%
• At most about 10 rounds; if confidence still has not converged, fall back to asking the user: do they want to split (B0), or does this requirement itself need to be done across multiple sessions

A3. 6-line restatement.

• Compress the clarified requirement to ≤ 6 lines
• Before entering Phase B, you must get an explicit "yes"; do not infer agreement from silence or topic continuation

Phase B — Set direction, set split

B0. Split (only when triggered by A1.5). Use the decision tree below to choose a split axis, produce a sub-spec list and a umbrella.md。

B1. Give 2–3 candidate options. State the trade-offs clearly and recommend one. Put the recommended item first; the alternatives are there for the user to change direction.

B2. Present by section. For each major section of the design (architecture, user flow, validation surface, downstream impact), set a mid-way user confirmation beat. Do not dump the entire What all at once.

Phase C — Land in files

Language rules (apply to all of C1/C2/C2.5): in each template, the section headingsare bilingual (English anchor + Chinese hint) and must be preserved verbatim—test-designer and deep-review the spec-conformance reviewers will grep the English anchors, so they must not be translated away.validation-contract.md instructural keywords（VAL-XXX-NNN、Behavior、Tool、Evidence, Tool category names) likewise remain in English.All body content—the Why / Findings / What body, the Behavior + Evidence descriptions of VALs, the split-axis rationale, Open questions, etc.—must be written in the language used in this conversation. Chinese conversation→body written in Chinese; English conversation→English. Do not mix Chinese and English within the same paragraph.

C1. Write references/spec-template.md according to docs/specs/<topic>/spec.md。

C2. Write references/validation-contract-template.md according to docs/specs/<topic>/validation-contract.md. Anti-pattern check: each VAL only sayswhatcounts as passing, nothowto test it—the latter is the job of test-designer . Use the A1 research results to fill in the ## Toolchain table (the specific tool corresponding to each category in the repository), passing the toolchain research conclusions downstream so downstream does not have to rediscover them.

C2.5. If B0 triggered a split, write references/umbrella-template.md according to docs/specs/<topic>/umbrella.md。

Phase D — Gate and handoff

D1. Handoff review. Apply ## 交接审查清单（D1）from the perspective of the consumer (test-designer / planner / you one month later). Fix problems on the spot—do not rerun the earlier phases.

D1.5. Provide review assistance (choose one of three). Use AskUserQuestion / request_user_input to give:

• (c) Skip — go directly to D2. The default for small-scale specs (≤ 5 VALs, single file).
• (a) Playground — use the document-critique template to dispatch playground:playground(Anthropic official plugin); pass spec.md + validation-contract.md (and umbrella.md if present) as input. Hide this item if the playground plugin is not installed.
• (b) Static HTML — generate a self-contained docs/specs/<topic>/review.html, rendering both documents with anchors + a VAL table. Execute open <file>.html. No interaction, no dependency on playground.

The option order must be skip → playground → static HTML. skip is deliberately placed first; small specs should not be pushed into tooling red tape.

If the user chose playground and gives reject / comment feedback, parse it, fix on the spot, and run D1 once more before entering D2.

D2. Explicit consent gate. Print the spec file path back to the user and wait for explicit approval. Do not start planning or pre-coding preparation just because of silence.

D3. Handoff. Apply the scale determination from CLAUDE.md / AGENTS.md :

• All three QDF predicates hold (single module, acceptance criteria ≤ 5, no cross-boundary interfaces) → skip plan, go straight to pre-coding preparation / branch creation
• Otherwise → hand off to the plan-phase tool chosen by the user (built-in Plan,planning-with-files, or any downstream planning skill the user chooses). Do not hardcode a specific plan-phase skill name; that decision belongs to the workflow CLAUDE.md / AGENTS.md.

User-supplied spec audit

When the user says "this is my spec", check each item below one by one. Any missing item becomes a Q in A2—do not accept it wholesale.

1. Why is clear — the motivation can be expressed in one sentence; if missing, work with the user to add 1–3 sentences
2. Findings are substantiated — there is concrete evidence (file paths, commit SHA, external links); if it is just an unsupported assertion, dig in the repo, or ask the user for the source
3. Validation Contract exists — there is structured VAL-XXX-NNN assertions or an equivalent; if it is only prose, refactor it into a VAL list
4. Out of scope is marked — there is an explicit "not doing this time" list
5. No How leakage — no module names, class names, signatures, library choices; if present, mark as out of bounds and move to plan

Templates

The three Phase-C output templates each exist as separate files next to this skill:

Output file	Template	When to use
docs/specs/<topic>/spec.md	references/spec-template.md	Always (Phase C1)
docs/specs/<topic>/validation-contract.md	references/validation-contract-template.md	Always (Phase C2)
docs/specs/<topic>/umbrella.md	references/umbrella-template.md	Only when B0 triggers a split (Phase C2.5)

Before writing the corresponding Phase-C output, first read the relevant template file. The skill body retainsintent(what each section is for);form(the exact headings, placeholders, table layout, numbering conventions) is governed by the template file. Copy the template block into docs/specs/<topic>/<file>.md, replacing every <占位符>。

The VAL numbering convention applies everywhere VALs are written:VAL-<CATEGORY>-<NNN>。CATEGORY is a 3–5 letter uppercase label (WORK / DEP / UI / CLI / …）。NNN zero-padded. When multiple VALs share the same domain, reuse the same category; do not skip numbers (skipping numbers means assertions were deleted, which breaks grep-based traceability).

Split scale gate

Any signal triggers B0:

• Estimated VAL count > 20
• Modules touched > 5
• Subsystems touched > 2 (e.g., changing CLI + Web UI + plugin manifest at the same time)
• UI components > 10
• The user explicitly says "this is probably > 3000 lines"

Split decision tree

Go in order; the first hit wins. These axes are deliberately aligned with the vocabulary of incremental-impl step 2—once the spec selects an axis, downstream plan and impl use the same name and do not decide again.

1. Greenfield (a brand-new subsystem) → Walking Skeleton: first get the thinnest end-to-end path working, then thicken it vertically afterward
2. High-risk / high-uncertainty technical surface → By risk: attack the most uncertain sub-spec first, validate, then expand
3. Cross-module, changes of similar shape across modules → Horizontal sweep: one sub-spec per module, serial
4. In-place migration of an existing surface → Branch by Abstraction: introduce the abstraction first, replace the implementation beneath the abstraction
5. Fallback → Vertical slice: split by user story

Tool vocabulary

VAL's Tool field must be chosen from the followingcategories—never write a specific tool name (to avoid locking in the implementation):

Tool	Used for
unit-test	unit-level logic
integration-test	cross-module / cross-process within a single runtime
e2e-browser	browser end-to-end (decide Browser Use / Playwright / Chrome MCP at plan time)
e2e-mobile	mobile / emulator end-to-end (decide Computer Use / XCUITest / Espresso at plan time)
e2e-cli	subprocess black-box testing of a CLI
http-probe	HTTP request + response assertions
repo-check	file existence / content / permissions
git-state	Git branch / commit / working tree state
gh-state	GitHub PR / Issue / Release state
lint	static checks (eslint / tsc --noEmit / shellcheck, etc.)
build	build artifact correctness (tsc / npm pack / artifact shape)
manual	manual verification only; must state "what counts as passing"

A single VAL's Tool field stays as acategory—this makes it greppable and keeps assertions independent of the implementation. The repository-specificconcretetool for each category (which test runner, which browser driver, which build command) is a fact obtained from A1 research, not an implementation decision of this feature—record it in the validation-contract.md of ## Toolchain tableonce, do not repeat it for every VAL. This passes the toolchain research conclusions downstream, so thattest-designer can aim at the correct runner / driver without re-inferring (it will still scan existing tests to figure out fixtures and naming conventions), and it also resolves real ambiguity within a category (e.g.,e2e-browser → Browser Use vs Playwright vs Chrome MCP, whose evidence shapes differ). Fill in Toolchain rows only for the categories actually used by VALs in the contract.

Handoff review checklist (D1)

Look at it from the position of downstream consumers (test-designer, the planner, you a month later). Fix on the spot—do not redo.

• has no TBD / TODO / placeholders
• Why is understandable even to a zero-context agent
• each VAL's Behavior has only a single meaning (there must not be two implementations that can both justify themselves as passing)
• no VAL says how to test, only what counts as passing
• validation-contract.md has a ## Toolchain table covering every category used by its VALs, with each row naming a concrete tool observed in A1 research (the repository's existing test infrastructure, not a design decision)
• Out of scope covers everything that "looks like it should be included" but actually is not
• no contradiction between What and VAL
• every item that project-level spec rules (docs/rules/spec/) require to be explicit is already in spec.md or validation-contract.md has a home; when A1 finds no rules, it has recorded "no project-specific spec rules"
• the Open questions contain only decisions deliberately deferred to downstream, each with a named owner (plan / impl) and a stated reason—no unresolved requirement ambiguity is hiding in there
• if it has been split, umbrella.md gives a complete overview without opening the sub-specs

Anti-patterns

• ❌ Asking multiple questions in one round—wears down the user's patience and mixes different dimensions together
• ❌ Pushing past 95% confidence—that marginal question over-specifies
• ❌ Writing implementation hints into spec.md("we will add a utils.ts function to validateX ")
• ❌ VALs that describe test mechanisms ("call assertEquals(parse(s), …)")—that belongs to test-designer
• ❌ Padding the VAL count to look thorough—a few well-formed VALs beat many vague ones
• ❌ Writing specific tool names in a single VAL's Tool field—specific tools are recorded only once in the ## Toolchain table
• ❌ Fabricating fake Open questions just to fill the section—for a well-clarified spec, "none" is a legitimate and common result
• ❌ Dumping unresolved requirement ambiguity into Open questions instead of resolving it in the A2 loop—Open questions hold only decisions deliberately deferred to downstream
• ❌ Accepting a user-supplied spec without running the audit
• ❌ Silently skipping D1.5—the review options must be presented; after that the user can choose to skip on their own
• ❌ Splitting a small spec into sub-specs to look organized—the size gate is the gate
• ❌ Treating a Figma URL as directly readable; always use exported PNGs / screenshots

Relationships with other skills

• test-designer — consumes validation-contract.md as the primary input (spec.md body as fallback context); writes failing tests
• incremental-impl — reuses the same set of split-axis vocabulary chosen in B0; carries spec + plan into per-slice execution
• plan-phase tools (built-in Plan,planning-with-files, or whatever planning skill the workflow CLAUDE.md names)—the downstream of D3 when the size assessment takes the full plan path
• deep-review 's spec-conformance reviewer — takes the PR diff and verifies it against the VAL list; findings are tagged VAL-XXX-NNN
• playground:playground(Anthropic official, soft dependency) — provides D1.5 review assistance via the document-critique template
• goalify — once this skill's spec is finalized,goalify consumes spec.md + validation-contract.md and packages long-horizon execution into a /goal script (autonomous continuous run, e.g. "push this to PR Ready"). Out of process: not invoked automatically here; the user invokes it themselves when they want to execute a clarified requirement unattended