# Writing Specification Driven Development

> Write specification documents for features using specification-driven development practices, including requirements with user stories, architecture design documents with correctness properties, and implementation plans with task breakdowns. Use when planning a new feature, designing system architecture, creating implementation roadmaps, or documenting technical specifications.

- Skill: `majiayu000/writing-specification-driven-development` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add majiayu000/writing-specification-driven-development`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/writing-specification-driven-development/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/writing-specification-driven-development

---



# Overview
This skill guides you through writing comprehensive specification documents using specification-driven development (SDD) methodology. The workflow creates three interconnected documents:

1) Requirements Document - What to build (user stories, acceptance criteria)

2) Design Document - How to build it (architecture, properties, data models)

3) Tasks Document - Implementation roadmap (task breakdown, dependencies)

Each document follows a proven pattern that ensures:
- Clear traceability from requirements → design → implementation

- Formal correctness properties that guide testing

- Maintainable, reference-able structure

## When to Use This Skill

Use this skill when:
- Designing architecture before implementation
- Planning a new feature or enhancement
- Designing system architecture or components
- Creating implementation roadmaps
- Documenting technical specifications
- Conducting technical reviews
- Creating specification documents for stakeholders
- Defining correctness properties for validation
- Breaking down large features into actionable tasks

## Workflow

The specification-driven development workflow follows these phases:

### Phase 1: Requirements Gathering
**Goal:** Understand what needs to be built and why

See detailed guide: [reference/requirements.md](reference/requirements.md)

**Key Activities:**
- Initial discovery and clarifying questions
- User stories creation
- Acceptance criteria definition
- Requirements review and approval

**Output:** `requirements.md` - Approved requirements document

**⚠️ CRITICAL:** Do NOT proceed to Phase 2 until user explicitly approves the requirements document.

---

### Phase 2: Architecture & Design
**Goal:** Define how the system will be built

**Prerequisites:** ✅ Phase 1 requirements.md must be approved by user

See detailed guide: [reference/design.md](reference/design.md)

**Key Activities:**
- System architecture design
- Correctness properties definition
- API & interface design
- Design review and approval

**Output:** `design.md` - Approved design document with correctness properties

**⚠️ CRITICAL:** Do NOT proceed to Phase 3 until user explicitly approves the design document.

---

### Phase 3: Implementation Planning
**Goal:** Break down work into actionable tasks

**Prerequisites:** ✅ Phase 2 design.md must be approved by user

See detailed guide: [reference/tasks.md](reference/tasks.md)

**Key Activities:**
- Task breakdown and hierarchical structure
- Dependency mapping
- Property-based test planning
- Tasks review and approval

**Output:** `tasks.md` - Approved implementation task list

**⚠️ CRITICAL:** Do NOT proceed to implementation until user explicitly approves the tasks document.

---

## Key Principles

1. **User as Ground Truth:** Always validate with user before moving to next phase. NEVER proceed without explicit approval.
2. **Sequential Approval:** Requirements → Design → Tasks. Each phase requires user approval before proceeding.
3. **Traceability:** Maintain clear links between requirements → design → tasks
4. **Formal Correctness:** Define testable properties, not just descriptions
5. **Iterative:** Expect to refine specs as understanding deepens
6. **Documentation:** Keep specs updated as single source of truth

---

## Approval Gates

### Gate 1: Requirements Approval
**Before creating design.md:**
- Present requirements.md to user
- Ask: "Do you approve these requirements? Can I proceed to design?"
- Wait for explicit approval
- Only proceed to Phase 2 after approval

### Gate 2: Design Approval
**Before creating tasks.md:**
- Present design.md to user
- Ask: "Do you approve this design? Can I proceed to create tasks?"
- Wait for explicit approval
- Only proceed to Phase 3 after approval

### Gate 3: Tasks Approval
**Before starting implementation:**
- Present tasks.md to user
- Ask: "Do you approve this task breakdown? Can I start implementation?"
- Wait for explicit approval
- Only proceed to implementation after approval

---

## Quick Reference

### Document Templates
- Requirements template: See [reference/requirements.md](reference/requirements.md#document-template)
- Design template: See [reference/design.md](reference/design.md#document-template)
- Tasks template: See [reference/tasks.md](reference/tasks.md#document-template)

### Handling Incomplete Information
See [reference/requirements.md](reference/requirements.md#handling-incomplete-information) for strategies on:
- Asking structured questions
- Making reasonable assumptions
- Using placeholders
- Iterative refinement

---

## Best Practices

1. **Start Simple:** Begin with minimal viable spec, expand as needed
2. **Be Specific:** Use concrete examples, avoid vague descriptions
3. **Link Everything:** Connect requirements → design → tasks explicitly
4. **Test Early:** Define properties before implementation
5. **Iterate Often:** Refine specs based on implementation learnings
6. **Document Decisions:** Capture "why" not just "what"
7. **Keep Updated:** Specs are living documents, not one-time artifacts

---

## Common Pitfalls to Avoid

- ❌ Writing specs without user validation
- ❌ Proceeding to next phase without explicit user approval
- ❌ Creating design.md before requirements.md is approved
- ❌ Creating tasks.md before design.md is approved
- ❌ Skipping correctness properties
- ❌ Creating tasks before design is clear
- ❌ Making specs too detailed upfront
- ❌ Not updating specs during implementation
- ❌ Treating specs as write-once documents
- ❌ Ignoring non-functional requirements

---

## Example Usage

**User Request:** "I need an API to manage user authentication"

**Phase 1 - Requirements:**
- Ask: What auth methods? (email/password, OAuth, etc.)
- Ask: What security requirements? (2FA, password rules, etc.)
- Write user stories and acceptance criteria
- Present requirements.md to user
- **WAIT for user approval** ⏸️
- ✅ User approves → Proceed to Phase 2

**Phase 2 - Design:**
- Design auth flow and JWT structure
- Define correctness properties (e.g., "tokens expire after N minutes")
- Design API endpoints (/login, /logout, /refresh)
- Present design.md to user
- **WAIT for user approval** ⏸️
- ✅ User approves → Proceed to Phase 3

**Phase 3 - Tasks:**
- Break down: Setup, Auth logic, Token management, Testing
- Create PBT tasks for each property
- Order by dependencies
- Present tasks.md to user
- **WAIT for user approval** ⏸️
- ✅ User approves → Proceed to Phase 4

---

## Success Criteria

A well-written specification should:
-  Be understandable by both technical and non-technical stakeholders
-  Have clear traceability from requirements to implementation
-  Include testable correctness properties
-  Provide actionable implementation guidance
-  Be maintainable and updatable
-  Serve as single source of truth for the feature