Spec Writing Skill
BRD Analysis Checklist
Before writing stories, extract from the BRD:
- Users/Personas: Who uses the system? What are their goals?
- Core Workflows: What are the 3-5 main things users do?
- Data: What data flows in, through, and out?
- Integrations: External systems, APIs, services?
- Constraints: Performance, security, compliance, tech stack?
- Non-functional: Scale, availability, latency requirements?
Epic Decomposition Rules
- Each epic = one shippable vertical slice (UI + API + backend for one capability).
- Epics should be deliverable in 1-2 weeks of agent work.
- Order epics by dependency: foundation first, features second, polish last.
- Typical ordering: Types/Models → Core Backend → API → Frontend → Integration → Polish.
Story Writing Format
See templates/story-template.md for the required story format with all fields.
Dependency Mapping
- Hard dependency: Story B cannot start until Story A's code exists (e.g., API depends on types).
- Soft dependency: Story B is easier after A but can start independently.
- Only map hard dependencies. Group soft-independent stories for parallel execution.
Parallel Group Assignment
Stories in the same parallel group have NO hard dependencies on each other.
The implementer agent will spawn concurrent sub-agents for each group.
Group A: [foundation — types, config]
Group B: [depends on A — repositories, services]
Group C: [depends on B — API endpoints]
Group D: [depends on C — UI pages]
Gotchas
- Vague BRDs yield bad stories — If the BRD is ambiguous about workflows or data, flag
[CLARIFY: ...] items and ask the user before writing stories. Do not invent details.
- Acceptance criteria that are not testable — Avoid "system should be fast" or "user should be happy". Acceptance criteria must be objective: specific file sizes, timeouts, error messages, state transitions.
- Stories that span multiple layers — A single story should trace through one vertical slice (types → repo → service → API → UI). If a story requires changes in 5+ files across different domains, it's too big — split it.
- Circular dependencies — If Story A depends on B and B depends on A, the BRD decomposition is wrong. Refactor to break the cycle by extracting a shared type or interface.
- Missing parallel groups — Stories marked as parallel but later blocked by implicit dependencies cause implementation to stall. Double-check that parallel group stories truly have zero hard dependencies on each other.
- Stories without layer assignments — Each story must explicitly state which layers it touches: Types, Repository, Service, API, UI. Missing assignments cause ambiguity during implementation.
1---2name: spec-writing3description: Decompose a Business Requirements Document into epics and user stories with acceptance criteria, estimate effort, and identify hard dependencies for parallel execution. Output stories in `specs/stories/` with dependency-graph.md and story files.4---56# Spec Writing Skill78## BRD Analysis Checklist910Before writing stories, extract from the BRD:11- **Users/Personas**: Who uses the system? What are their goals?12- **Core Workflows**: What are the 3-5 main things users do?13- **Data**: What data flows in, through, and out?14- **Integrations**: External systems, APIs, services?15- **Constraints**: Performance, security, compliance, tech stack?16- **Non-functional**: Scale, availability, latency requirements?1718## Epic Decomposition Rules1920- Each epic = one shippable vertical slice (UI + API + backend for one capability).21- Epics should be deliverable in 1-2 weeks of agent work.22- Order epics by dependency: foundation first, features second, polish last.23- Typical ordering: Types/Models → Core Backend → API → Frontend → Integration → Polish.2425## Story Writing Format2627See `templates/story-template.md` for the required story format with all fields.2829## Dependency Mapping3031- **Hard dependency**: Story B cannot start until Story A's code exists (e.g., API depends on types).32- **Soft dependency**: Story B is easier after A but can start independently.33- Only map hard dependencies. Group soft-independent stories for parallel execution.3435## Parallel Group Assignment3637Stories in the same parallel group have NO hard dependencies on each other.38The implementer agent will spawn concurrent sub-agents for each group.3940```41Group A: [foundation — types, config]42Group B: [depends on A — repositories, services]43Group C: [depends on B — API endpoints]44Group D: [depends on C — UI pages]45```4647## Gotchas48491. **Vague BRDs yield bad stories** — If the BRD is ambiguous about workflows or data, flag `[CLARIFY: ...]` items and ask the user before writing stories. Do not invent details.502. **Acceptance criteria that are not testable** — Avoid "system should be fast" or "user should be happy". Acceptance criteria must be objective: specific file sizes, timeouts, error messages, state transitions.513. **Stories that span multiple layers** — A single story should trace through one vertical slice (types → repo → service → API → UI). If a story requires changes in 5+ files across different domains, it's too big — split it.524. **Circular dependencies** — If Story A depends on B and B depends on A, the BRD decomposition is wrong. Refactor to break the cycle by extracting a shared type or interface.535. **Missing parallel groups** — Stories marked as parallel but later blocked by implicit dependencies cause implementation to stall. Double-check that parallel group stories truly have zero hard dependencies on each other.546. **Stories without layer assignments** — Each story must explicitly state which layers it touches: Types, Repository, Service, API, UI. Missing assignments cause ambiguity during implementation.
cwijayasundara