majiayu000 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:
- Overview section present and clear
- Workflow type determined with rationale
- Task scope defined with in/out of scope
- Files to modify listed with specific changes
- Files to reference listed with patterns
- Functional requirements documented
- Edge cases identified
- Implementation notes included
- Success criteria defined
- QA acceptance criteria complete
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.