Writing Spec

Purpose

Guide the developer through writing a feature spec before any code is written. The spec constrains intent and approach so implementation decisions are explicit, reviewed, and traceable. This skill produces three files in specs/NNN-feature-name/ — requirements.md, design.md, tasks.md — using the templates in ./templates/.

Prerequisites

• Read ./templates/requirements-template.md, ./templates/design-template.md, ./templates/tasks-template.md, and ./templates/contract-template.md before starting — they define the section structure
• Read @docs/architecture.md to understand current building block types and project structure
• Determine the next available sequence number by checking both specs/ directory listings AND git log for prior spec-related commits — use the higher of the two

Workflow: Four Phases with Gates

Each phase ends with a human review gate. Do NOT advance to the next phase without explicit developer approval ("continue", "ok", "next", "looks good", or similar). If something goes wrong, STOP and re-plan — do not push forward.

Phase 1 — Goal & Scope (Intent)

Collaborate with the developer to fill requirements.md.

1. Ask the developer to describe the feature in 2-5 sentences (or accept what they've already provided)
2. Before drafting, ask 3-5 clarifying questions about scope boundaries, error scenarios, and unstated assumptions — only where the answer would change the spec. Skip obvious ones.
   • If the feature introduces new API calls (queries or mutations): explicitly ask which server-side error responses each call must handle, and how the UI should react to each.
3. Draft the Goal & Context section — focus on the problem, not the solution
4. Draft Requirements using EARS notation: WHEN [condition] THE SYSTEM SHALL [behavior]. Assign stable IDs (R1, R2, …)
5. Draft Non-Goals — ask: "What should this feature explicitly NOT do?"
6. Present requirements.md for review

What to ask if unclear: "What's the observable user behavior when this works correctly?" Never invent requirements — if the developer hasn't specified a behavior, ask about it.

Phase 2 — Design (Approach)

Collaborate on design.md.

1. Propose a Building Blocks Diff — list every block that is ADDED, MODIFIED, or DELETED. Use the project's building block taxonomy from .agents/skills/building-blocks/SKILL.md. Reference by name and type only — do not define internals. Implementation details belong in coding standards and per-type skills, not specs. For changes that don't map to a typed building block, use the target file path + a short description instead.

2. Cross-slice concerns — ask whether any new block needs to interact with another feature or sub-feature slice. If yes, decide the wiring point (parent feature or page) and injection mechanism (callback, render prop, slot) in the design — don't defer to implementation.

3. Identify contract candidates. For each block in the diff, check the signal checklist below. For every block hitting ≥1 signal, present an inline proposal — one line each: `blockName` (type) — <signal(s) hit>; design problem: <one phrase>. The developer approves/rejects each. For approved blocks, create specs/NNN-feature-name/contracts/{block-slug}.md (slug = block name kebab-cased per code-style.md; on a slug collision, suffix the type, e.g. review-form-store.md) from ./templates/contract-template.md, and add a contract link to that block's design.md Building Blocks Diff entry. Contracts are signal-driven, not type-driven — most blocks hit zero signals and get nothing. If no block hits a signal, skip this step entirely: no contracts/ directory, no proposals. When a block hits a signal but the developer rejects the proposal (or you judge it trivial), record the skip reason inline in that block's design.md entry — e.g. `fooStore` (store) — contract skipped: shape is flat.

   Signals — a block warrants a contract proposal if ≥1 holds. Signals describe properties of the design problem, not block types:

   1. Multiple states & transitions — the block moves through several discrete states with conditional or guarded transitions.
   2. Structured internal state — more than a couple of flat fields: derived values, interdependent fields, or normalized collections.
   3. Branching domain logic — conditional rules, invariants, or multi-step computation where the rules themselves are the design.
   4. Cross-slice coordination — behavior depends on wiring into another feature or sub-feature slice; the seam (callback, slot, render-prop) needs design.
   5. No canonical pattern — the block matches no established pattern the agent can look up, so its shape must be designed from scratch.

4. For non-trivial features, propose two plausible designs with tradeoffs. Let the developer choose. Capture the winner and rationale in Design Decisions

5. Draft the Boundaries section using the three-tier system:

   • ✅ Always — proceed without asking (e.g., create files in the feature directory)
   • ⚠️ Ask first — needs approval (e.g., modify API contracts, change schema, create shared utilities)
   • 🚫 Never — hard stops (e.g., modify core auth, remove tests, commit secrets)

6. Present design.md for review

Critical rule for building blocks: Reference names and types. Do NOT define contracts, interfaces, or implementation — those live in separate coding-standards skills and existing code. The spec describes a CHANGE to the status quo. The agent reads relevant code to see the current status quo.

Phase 3 — Spec (Sequencing)

Fill tasks.md.

1. Break work into a Task Breakdown — ordered, independently testable tasks. Each task:
   • References building blocks from design.md if any are involved
   • Traces to requirement IDs (R1, R2, …)
   • Includes target file paths
   • Is marked [P] (parallelizable) or [S] (sequential)
2. Draft Error & Edge Cases using GIVEN/WHEN/THEN — cover failure modes (including fetch errors for data-fetching components), boundary conditions, concurrency
3. Add Open Questions for anything unresolved that blocks a specific task
4. Present tasks.md for review

Phase 4 — Review & Finalize

1. Run a structured self-audit and present findings to the developer (don't silently verify — show the results):
   • Coverage matrix: for each requirement ID, list which task(s) implement it. Flag any requirement with zero tasks
   • Orphan tasks: flag any task that doesn't trace back to a requirement ID
   • EARS compliance: flag any requirement missing WHEN/THE SYSTEM SHALL or using vague language ("handle properly", "work correctly")
   • Boundary specificity: flag any boundary item (✅/⚠️/🚫) that references a vague category instead of a file path or module name
   • Building block references: flag any block in design.md that doesn't exist in the building-blocks catalog — acceptable without a catalog match if the block has a contract (signal 5, no canonical pattern); flag it only if it lacks both
   • Contract coverage: every contract file links back from a design.md block entry; every design.md block that hits a signal either has a contract or an inline skip reason in its entry
   • Line count: report each file's count and the combined total. Caps: requirements.md ≤50, design.md ≤80, tasks.md ≤70, combined ≤200. Contracts are excluded from the combined cap — report each contract's count separately, ≤80 each. If any cap is exceeded, identify which section to compress or extract
   • Contract count: no hard cap — report the count. A high count (e.g. >3) signals the feature should be split into separate specs; surface it, don't enforce it
2. Fix any issues found in step 1 before proceeding
3. Set status to review in each Meta table
4. Present the audit results and the final spec for developer sign-off