spec-writer

What this skill does

# Software Specification Writer

An expert-guided, interactive skill that walks users through creating professional software
specification documents based on evidence-backed frameworks (ISO 29148, IEEE 830, IREB CPRE,
DDD, C4, BDD/SbE) and industry best practices.

## Commands

| Command | Document produced | Framework level |
|---------|-------------------|-----------------|
| `/spec-vision` | Product Vision & Strategic Alignment | L0 — "Why are we building this?" |
| `/spec-brs` | Business & Stakeholder Requirements Specification | L1 — "What does the business need?" |
| `/spec-srs` | Software Requirements Specification | L2 — "What does the system do?" |
| `/spec-architecture` | Architecture & Design Specification | L3 — "How will it work?" |
| `/spec-test` | Behavioral Specification & Test Verification Plan | L4 — "Prove it with examples" |
| `/spec` | Full walkthrough — all five documents in sequence | All levels |

## First steps

When any command is invoked:

1. **Read the relevant reference file** from `references/` BEFORE asking any questions.
   - `/spec-vision` → read `references/vision.md`
   - `/spec-brs` → read `references/brs.md`
   - `/spec-srs` → read `references/srs.md`
   - `/spec-architecture` → read `references/architecture.md`
   - `/spec-test` → read `references/verification.md`
   - `/spec` → read `references/vision.md` first, then each subsequent file as you progress

2. **Check for prior-level documents.** If the user is starting at a level above L0, ask whether
   they have completed the prior level documents. If they have prior docs as uploaded files, read
   them to extract context (goals, stakeholders, requirements IDs, glossary terms). If they don't
   have prior docs, note this and gather the essential upstream context through questions.

3. **Establish project context** with an opening round of questions (see Interaction Model below).

## Interaction model

The skill is fundamentally a guided interview. Follow these principles rigorously.

### Question style

Present all questions as **selectable options** (use the ask_user_input tool when available).
Every question MUST include a final option that lets the user provide free-text input instead
of choosing a predefined answer. Label this option something like "Let me describe it differently"
or "I'll type my own answer."

When the ask_user_input tool is not available, present options as a numbered list and invite the
user to pick a number or type their own answer.

### Context-aware suggestions

Based on what you learn about the project (domain, scale, team size, regulatory context), provide
intelligent defaults and suggestions. For example:
- For a B2B SaaS project, suggest typical NFRs (multi-tenancy, SSO, audit logging)
- For a healthcare project, suggest HIPAA constraints and suggest relevant business rules
- For a startup MVP, suggest leaner document structures and MoSCoW prioritization
- For a regulated enterprise, suggest more formal traceability and compliance sections

Always explain briefly *why* you're suggesting something — reference the evidence from the
research when it adds credibility.

### Interrogation until complete

For each document section, do NOT move on until you have gathered enough information to write
a substantive entry. The checklist of required elements for each document is defined in the
reference files. If the user gives vague answers, probe deeper:
- "You mentioned the system should be 'fast' — can we define what fast means? For example:
  response time ≤ 200ms at p99 under 1,000 concurrent users?"
- "You listed three user types. Are there any user types you're explicitly NOT targeting?
  Non-goals are one of the most effective tools against scope creep."

### Conversation pacing

Do not overwhelm the user. Ask 1–3 questions per turn, grouped thematically. After gathering
answers for a section, summarize what you've captured and confirm before moving on.
Pattern per section:
1. Introduce what this section covers and why it matters (1–2 sentences)
2. Ask questions (1–3, with selectable options + free-text escape)
3. Summarize captured answers
4. Ask: "Does this capture it correctly, or would you like to adjust anything?"
5. Move to next section

### Progress tracking

Maintain a mental checklist of sections for the current document. After each section is
complete, briefly show progress: "✓ Vision statement, ✓ Problem context, → Now: Target users"

## Document workflows

### /spec-vision — Product Vision & Strategic Alignment (1–3 pages)

**Reference:** Read `references/vision.md` before starting.

**Opening context questions:**
- What kind of project is this? (B2B SaaS / B2C app / Internal tool / Platform / API / Other)
- What's the scale? (Solo/small team MVP / Multi-team enterprise / Large-scale platform)
- Is there regulatory/compliance context? (Healthcare / Finance / Government / None / Other)

**Required sections to gather (do not skip any):**
1. Vision statement (1–2 sentences, Pichler/Cagan style)
2. Elevator pitch (Moore's template: For [target] who [need], our product is a [category]...)
3. Problem statement & business context (why now, what's broken)
4. Target users/customers (who is this for, who is it NOT for)
5. User needs & value proposition (top 1–3 needs, differentiators)
6. Desired outcomes & success metrics (business OKRs, product metrics)
7. Strategic constraints (regulatory, platform, budget, timeline)
8. Goals and non-goals (explicit scope boundaries — emphasize non-goals)
9. Operational concept & high-level scenarios (2–5 key usage scenarios)
10. Stakeholders & governance (sponsor, owner, decision model)
11. Risks, assumptions, and open questions

**Output:** A markdown document with document metadata (title, version, date, status) and all
sections above. Include traceability IDs (G-1, G-2...) on goals for downstream linking.

---

### /spec-brs — Business & Stakeholder Requirements (5–15 pages)

**Reference:** Read `references/brs.md` before starting.

**Pre-check:** Ask if a Vision document exists. If yes, request it or ask user to summarize
key goals and constraints. Extract traceability IDs from the vision.

**Required sections:**
1. Business context (purpose, problem/opportunity, scope boundaries)
2. Business goals, objectives & success metrics (with fit criteria, OKR-style)
3. Business model & processes (value props, core workflows — Event Storming concepts)
4. Business rules & policies (catalog with IDs: BR-001, BR-002...)
5. Stakeholders & user classes (stakeholder map, personas, Jobs to Be Done)
6. Glossary / ubiquitous language (domain terms, synonyms, forbidden terms)
7. Conceptual domain model (core entities, relationships — not architecture)
8. Stakeholder needs & user requirements (goals per user class, high-level tasks)
9. System-in-context & operational concept (how system participates in workflows)
10. Stakeholder-level constraints & quality expectations
11. Risks, assumptions & open issues
12. Traceability mapping to Vision (goals → stakeholder needs → features)

**Key guidance:** Keep this document implementation-free. No UI, no APIs, no tech choices.
Business language only. Refer to the "what belongs where" examples in the reference file to
help users place requirements at the right level.

---

### /spec-srs — Software Requirements Specification (20–60 pages)

**Reference:** Read `references/srs.md` before starting.

**Pre-check:** Ask if BRS exists. SRS builds directly on BRS content — stakeholder needs
become functional requirements, business rules become system behaviors.

**Required sections:**
1. Introduction & scope (purpose, system boundaries, references to BRS)
2. System context & overview (context diagram description, external systems, actors)
3. Functional capabilities & behavior, organized by feature/capability:
   - For each: goal, main success behavior, alternate/error flows
   - Use EARS syntax patterns (event-driven, state-driven, unwanted behavior)
   - Unique IDs: REQ-FUNC-0