Spec Writer Skill

Purpose

Operator Context

Hardcoded Behaviors (Always Apply)

• Phase 3 (Out of Scope) is MANDATORY -- never skip it. Without explicit exclusions, scope creep is invisible until it's too late. Every "while we're at it" addition started as an unwritten assumption.
• Minimum 3 out-of-scope items -- if you cannot list 3 things this feature does NOT do, the scope is not yet defined. This forces real boundary thinking rather than a rubber-stamp section.
• Max 7 user stories -- more than 7 means the feature is too broad. Decompose into multiple specs first. This constraint forces prioritization: which stories are essential vs. nice-to-have?
• Acceptance criteria must be testable -- no subjective language ("should feel fast", "user-friendly", "intuitive"). Every criterion must have a verifiable assertion. WHY: untestable criteria become opinion debates during review.
• Spec says WHAT, not HOW -- no code, no architecture, no database schemas, no implementation details. Those belong in feature-design.

Default Behaviors (ON unless disabled)

• Save output as SPEC.md in project root, or

  .feature/SPEC.md

  if worktree is active
• Include all 5 sections in order (stories, criteria, out-of-scope, risks, estimation)
• Use GIVEN/WHEN/THEN format for acceptance criteria

Optional Behaviors (OFF unless enabled)

• Skip estimation -- omit Section 5 for exploratory or research-phase work
• Test stub generation -- render acceptance criteria as pseudocode test stubs

Instructions

Step 1: Gather Context

1. Read the repository CLAUDE.md if present
2. Ask the user what feature or capability they want to specify
3. Identify the target users/roles (who benefits?)
4. Identify existing related functionality (what already exists?)

Step 2: Write SPEC.md

# Spec: [Feature Name]

## 1. User Stories

> Max 7 stories. Each has single responsibility.

- **US-1**: As a [role], I want [action] so that [benefit].
- **US-2**: As a [role], I want [action] so that [benefit].

## 2. Acceptance Criteria

> 2-5 criteria per story. All must be verifiable.

### US-1: [Story title]
- GIVEN [context] WHEN [action] THEN [result]
- GIVEN [context] WHEN [action] THEN [result]

### US-2: [Story title]
- GIVEN [context] WHEN [action] THEN [result]

## 3. Out of Scope

> Minimum 3 items. Each states WHY it is excluded.

This feature does NOT:
- [ ] Handle X (deferred to future work because Y)
- [ ] Support Y (explicitly excluded because Z)
- [ ] Replace Z (existing solution remains because W)

## 4. Risks & Assumptions

| Risk/Assumption | Impact | Mitigation |
|-----------------|--------|------------|
| Assumption could be wrong | What breaks | How to detect/recover |
| External dependency blocks | Delay estimate | Fallback plan |

## 5. Estimation

| Dimension | Assessment | Justification |
|-----------|------------|---------------|
| T-shirt size | S / M / L / XL | Why this size |
| Files changed | ~N files | Which areas of codebase |
| Testing complexity | Low / Medium / High | What makes testing easy or hard |

Step 3: Validate and Save

1. Review each acceptance criterion -- flag any that use subjective language
2. Review out-of-scope -- flag if fewer than 3 items
3. Review story count -- flag if more than 7
4. Save the spec:
   • If

     .feature/

     directory exists: save to

     .feature/SPEC.md

   • Otherwise: save to

     SPEC.md

     in project root
5. Report the artifact location and suggest next step:

   Spec saved to [path]. Run /feature-design to begin design exploration.

Error Handling

Anti-Patterns

Integration

spec-writer (SPEC.md)
  --> feature-design (reads stories + scope boundaries)
    --> feature-plan (reads acceptance criteria for test requirements)
      --> feature-implement
        --> feature-validate (checks acceptance criteria as quality gates)
          --> feature-release

References

• Anti-Rationalization
• Gate Enforcement