Specification Writing Skill

Overview

Transform gathered requirements and codebase context into a comprehensive, actionable specification document. The spec is the contract between planning and implementation.

Core principle: Synthesize context into actionable spec. No user interaction needed during writing.

When to Use

Always:

After requirements gathering is complete
When you have codebase context available
Before implementation planning begins

Exceptions:

Simple changes that don't need formal specs
Exploratory work without clear requirements

The Iron Law

NO IMPLEMENTATION WITHOUT A COMPLETE SPEC FIRST

A spec must have ALL required sections before implementation can begin.

Inputs Required

Before writing a spec, ensure you have:

Requirements document - What needs to be built
Project context - Tech stack, structure, patterns
Files to modify - Identified from codebase analysis
Files to reference - Patterns to follow

Workflow

Phase 1: Load All Context

Read all input files to understand the full picture:

# Read requirements
cat .claude/context/requirements/[task-name].md

# Read project context
cat .claude/context/product.md
cat .claude/context/tech-stack.md

# Read any analysis results
cat .claude/context/analysis/[task-name].json 2>/dev/null

Extract from these files:

From requirements: Task description, workflow type, acceptance criteria
From project context: Services, tech stacks, patterns
From analysis: Files to modify, files to reference, patterns

Phase 2: Analyze Context

Before writing, think about:

Implementation Strategy:

What's the optimal order of implementation?
Which area should be built first?
What are the dependencies between components?

Risk Assessment:

What could go wrong?
What edge cases exist?
Any security considerations?

Pattern Synthesis:

What patterns from reference files apply?
What utilities can be reused?
What's the code style?

Phase 3: Write Specification Document

Create the spec with ALL required sections:

# Specification: [Task Name]

## Overview

[One paragraph: What is being built and why]

## Workflow Type

**Type**: [feature|refactor|investigation|migration|simple]

**Rationale**: [Why this workflow type fits the task]

## Task Scope

### Areas Involved

- **[area-name]** (primary) - [role from context analysis]
- **[area-name]** (integration) - [role from context analysis]

### This Task Will:

- [ ] [Specific change 1]
- [ ] [Specific change 2]
- [ ] [Specific change 3]

### Out of Scope:

- [What this task does NOT include]

## Technical Context

### Tech Stack

- Language: [from project context]
- Framework: [from project context]
- Key directories: [from project context]

### How to Run

```bash
[commands from project context]
```

Files to Modify

File	Purpose	What to Change
`[path]`	[purpose]	[specific change needed]

Files to Reference

These files show patterns to follow:

File	Pattern to Copy
`[path]`	[what pattern this demonstrates]

Patterns to Follow

[Pattern Name]

From [reference file path]:

[code snippet or description]

Key Points:

[What to notice about this pattern]
[What to replicate]

Requirements

Functional Requirements

[Requirement Name]
- Description: [What it does]
- Acceptance: [How to verify]
[Requirement Name]
- Description: [What it does]
- Acceptance: [How to verify]

Edge Cases

[Edge Case] - [How to handle it]
[Edge Case] - [How to handle it]

Implementation Notes

DO

Follow the pattern in [file] for [thing]
Reuse [utility/component] for [purpose]
[Specific guidance based on context]

DON'T

Create new [thing] when [existing thing] works
[Anti-pattern to avoid based on context]

Development Environment

Start Services

[commands from project context]

Required Environment Variables

VAR_NAME: [description]

Success Criteria

The task is complete when:

[From requirements acceptance_criteria]
[From requirements acceptance_criteria]
No console errors
Existing tests still pass
New functionality verified

QA Acceptance Criteria

CRITICAL: These criteria must be verified by QA before sign-off.

Unit Tests

Test	File	What to Verify
[Test Name]	`[path/to/test]`	[What this test should verify]

Integration Tests

Test	Areas	What to Verify
[Test Name]	[area-a + area-b]	[API contract, data flow]

End-to-End Tests

Flow	Steps	Expected Outcome
[User Flow]	1. [Step] 2. [Step]	[Expected result]

QA Sign-off Requirements

All unit tests pass
All integration tests pass
All E2E tests pass
No regressions in existing functionality
Code follows established patterns
No security vulnerabilities introduced


### Phase 4: Verify Spec

After creating, verify the spec has all required sections:

```bash
# Check required sections exist
grep -E "^##? Overview" spec.md && echo "Overview present"
grep -E "^##? Workflow Type" spec.md && echo "Workflow Type present"
grep -E "^##? Task Scope" spec.md && echo "Task Scope present"
grep -E "^##? Success Criteria" spec.md && echo "Success Criteria present"
grep -E "^##? QA Acceptance" spec.md && echo "QA Criteria present"

# Check file length (should be substantial)
wc -l spec.md

If any section is missing, add it immediately.

Phase 5: Save and Signal Completion

Save the spec to the appropriate location:

# Save to context directory
cat > .claude/context/specs/[task-name]-spec.md << 'EOF'
[Spec content]
EOF

Verification Checklist

Before completing spec writing:

Common Mistakes

Generic Content

Why it's wrong: "Implement the feature" is not actionable.

Do this instead: Be specific to this project and task. Use exact file paths.

Missing Tables

Why it's wrong: Empty tables provide no guidance.

Do this instead: Fill in tables with data from context analysis.

No QA Criteria

Why it's wrong: QA agent needs clear criteria to validate.

Do this instead: Include unit, integration, and E2E test expectations.

Integration with Other Skills

This skill works well with:

spec-gathering: Provides the requirements input
spec-critique: Reviews the spec for issues
complexity-assessment: Determines spec complexity for planning

Memory Protocol

Before starting: Read .claude/context/memory/learnings.md

After completing:

New pattern -> .claude/context/memory/learnings.md
Issue found -> .claude/context/memory/issues.md
Decision made -> .claude/context/memory/decisions.md

ASSUME INTERRUPTION: If it's not in memory, it didn't happen.

spec-writing