spec-writer

What this skill does

# Spec Writer

This skill manages the complete specification lifecycle: creating living spec documents in `docs/specs/<name>/`, updating them to reflect current implementation, identifying gaps between spec and code, and proposing change documents in `docs/changes/` to close those gaps.

## Scope — Documentation Only

**CRITICAL: This skill writes ONLY specs and change documents. It MUST NOT write, modify, or generate any implementation code.**

- Do NOT edit source files (`.ts`, `.tsx`, `.js`, `.py`, etc.)
- Do NOT create or run database migrations
- Do NOT modify tests, configs, or any non-documentation file
- Do NOT install packages or run build commands
- The ONLY files this skill creates or modifies are in `docs/` (specs, changes, indexes)

If the user asks to "write a spec AND implement it", write the spec/changes first, then stop and tell the user to use `/dev` for implementation.

## Core Principles

1. **Specs are living knowledge** — They describe the CURRENT state of the system, not a future plan. They MUST be kept in sync with implementation.
2. **One spec per major feature** — Never create a single monolithic spec for an entire application. Each major feature area (e.g., authentication, file storage, upload system, password protection) gets its own spec. A general "architecture" or "setup" spec is appropriate for project-level concerns (tech stack, directory structure, deployment topology), but feature behavior belongs in feature-specific specs. This keeps specs focused, readable in one sitting, and independently maintainable.
3. **Changes are plans** — Planning, task tracking, and implementation details go in `docs/changes/NNNN-name.md`, never in specs.
4. **RFC 2119 everywhere** — All specs and changes MUST use RFC 2119 keywords (MUST, MUST NOT, SHALL, SHALL NOT, SHOULD, SHOULD NOT, MAY, OPTIONAL) for requirement precision.
5. **Behavioral scenarios** — Every requirement SHOULD have GIVEN/WHEN/THEN scenarios that map directly to test cases.
6. **Exhaustive exploration** — Research the codebase deeply before writing anything. Every claim in a spec must be verified against actual code.
7. **Clarify before writing** — Use AskUserQuestion for scope decisions and design choices.

## RFC 2119 Reference

Per RFC 2119, these keywords indicate requirement levels:
- **MUST / SHALL / REQUIRED** — Absolute requirement
- **MUST NOT / SHALL NOT** — Absolute prohibition
- **SHOULD / RECOMMENDED** — Strong recommendation; exceptions need justification
- **SHOULD NOT / NOT RECOMMENDED** — Strong discouragement; exceptions need justification
- **MAY / OPTIONAL** — Truly optional; interoperability must work with or without

---

## Workflow

### Phase 0: Setup

**Every time this skill is invoked**, run the setup skill first to ensure docs structure and instruction files are in place:

```
Skill tool: skill="fx-dev:setup"
```

This is fast and idempotent — it checks what exists and only creates/modifies what's missing. It handles:
- `docs/` folder structure (specs/, changes/, tasks.md, index.yml, index.md)
- `CLAUDE.md` task-tracking instructions
- `.github/copilot-instructions.md` PR review instructions

Wait for setup to complete before proceeding.

---

### Phase 1: Deep Research

This phase MUST be thorough. Insufficient research leads to inaccurate specs.

#### 1.1 Local Codebase Exploration

Launch `Explore` sub-agents (subagent_type: `Explore`) to deeply understand the relevant parts of the codebase:

- Map all files, modules, and data models the feature touches
- Identify existing patterns, abstractions, and conventions
- Find related features or systems already implemented
- Note constraints (auth patterns, API conventions, DB schema patterns, component libraries)
- Read test files to understand expected behaviors
- Check git history for recent changes in relevant areas

Launch **multiple Explore sub-agents in parallel** if the feature spans distinct areas (e.g., frontend + backend + database + tests).

#### 1.2 Technology and Pattern Research

Launch a sub-agent that loads the tech-scout skill (Skill tool: skill='fx-research:tech-scout') to:

- Discover how similar features are commonly implemented
- Identify relevant libraries, APIs, or standards
- Find best practices and anti-patterns

Skip only when the feature is purely internal with no new technology.

#### 1.3 Web Discovery

Use `WebSearch` to find:

- How other products implement similar features
- Relevant RFCs, standards, or specifications
- Community discussions about tradeoffs

#### 1.4 Existing Specs and Changes

Read all existing specs and changes to understand the current documentation landscape:

```bash
ls docs/specs/ docs/changes/ 2>/dev/null
cat docs/index.yml 2>/dev/null
```

Check if a spec already exists for this area. If so, this is an **update**, not a creation.

#### 1.5 Synthesize Research

Before proceeding, compile a mental model of:
- What exists in the codebase today (actual behavior, not aspirational)
- What patterns and conventions must be followed
- What external patterns and best practices apply
- What the key design decisions and tradeoffs are
- What existing specs cover and what gaps remain

---

### Phase 2: Mode Selection

Determine what work is needed:

**A) New Spec** — No spec exists for this system/feature area. Go to Phase 3.

**B) Update Existing Spec** — A spec exists but is outdated or incomplete. Go to Phase 4.

**C) Spec + Changes** — User wants to define desired behavior (spec) AND plan implementation work (changes) to get there. Go to Phase 3 or 4, then Phase 5.

When the mode is ambiguous, use `AskUserQuestion`:

```
AskUserQuestion:
  question: "A spec already exists at docs/specs/<name>/. What would you like to do?"
  options:
    - label: "Update the spec to match current implementation"
      description: "Audit the code and update the spec to reflect reality"
    - label: "Update the spec AND propose changes"
      description: "Update the spec to the desired state, then create change documents for unimplemented parts"
    - label: "Only propose changes"
      description: "Keep the spec as-is and create change documents for new work"
```

---

### Phase 3: Create New Spec

#### 3.1 Create Spec Directory

```bash
mkdir -p docs/specs/<spec-name>
```

Where `<spec-name>` is a brief, descriptive kebab-case name (e.g., `user-authentication`, `payment-processing`, `notification-system`).

#### 3.2 Write the Spec

Read the template at `references/spec-index-template.md` and write `docs/specs/<spec-name>/index.md`.

**Critical rules:**
- Describe the system **as it currently exists in the codebase**. If the feature doesn't exist yet, describe the desired behavior and note it as unimplemented.
- Use RFC 2119 language for all requirements.
- Include GIVEN/WHEN/THEN scenarios for every requirement.
- Include actual code snippets from the codebase where they clarify the design.
- Verify every claim against the actual code — do not guess or assume.
- NO task lists in specs. Tasks belong in change documents.
- Initialize the Changelog with a creation entry.

#### 3.3 Scope Analysis

**CRITICAL: Do NOT create a single spec for an entire application.** Break the work into multiple specs by major feature area.

A single spec MUST:
- Cover **one** cohesive feature or domain (e.g., "authentication", "file-upload", "password-protection")
- Be readable in one sitting
- Have clear boundaries that don't overlap with other specs

**Spec organization for a new project:**

1. **Architecture/setup spec** (optional) — Covers project-level concerns: tech stack, directory structure, deployment topology, dev workflow. Does NOT contain feature requirements.
2. **Feature specs** (one per major feature) — Each covers a distinct capability of the system. Change documents reference the feature spec they implement.

**Example:** For a file hosting app, create separate specs:
- `architecture` — Tech stack, project structure, deployment
- `file-serving` — HTTP serving, Conten