Spec-Driven Development Skill

Expert guidance for planning and documenting before implementation.

When to Use

• Before implementing new features
• When requirements are unclear
• For complex architectural decisions
• When multiple implementation paths exist
• Before major refactoring efforts

Spec-Driven Workflow

Overview

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  1. Gather  │ ──▶ │  2. Analyze │ ──▶ │  3. Specify │ ──▶ │ 4. Implement│
│ Requirements│     │    Risks    │     │   & Approve │     │    (TDD)    │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘

Phase 1: Gather Requirements

Use thinking-socratic skill to clarify requirements:

Questions to Ask:

• What problem are we solving?
• Who are the users/stakeholders?
• What are the success criteria?
• What are the constraints (time, tech, budget)?
• What existing systems are affected?
• What are the non-functional requirements?

Output:

## Requirements Summary

### Problem Statement
[Clear description of the problem]

### Users/Stakeholders
- Primary: [who]
- Secondary: [who]

### Success Criteria
1. [Measurable outcome]
2. [Measurable outcome]

### Constraints
- Technical: [constraints]
- Timeline: [deadline]
- Dependencies: [systems]

Phase 2: Analyze Risks

Use thinking-pre-mortem skill to identify risks:

Pre-Mortem Exercise:

"Imagine this feature has failed spectacularly. What went wrong?"

Risk Categories:

• Technical risks (complexity, unknown tech)
• Integration risks (APIs, databases, services)
• Performance risks (scale, latency)
• Security risks (auth, data exposure)
• Operational risks (deployment, monitoring)

Output:

## Risk Analysis

### High Priority Risks
| Risk | Impact | Likelihood | Mitigation |
|------|--------|------------|------------|
| [risk] | High | Medium | [strategy] |

### Assumptions
1. [assumption to validate]
2. [assumption to validate]

### Open Questions
1. [question needing answer]

Phase 3: Write Specification

Spec Document Structure:

# Feature: [Name]

## Overview
[1-2 paragraph summary]

## Requirements
- [REQ-1] [Description]
- [REQ-2] [Description]

## Technical Design

### Architecture
[Diagram or description of component interactions]

### API Design

POST /api/resource Request: { "field": "value" } Response: { "id": "123", "field": "value" }

### Database Schema

CREATE TABLE resource ( id SERIAL PRIMARY KEY, field VARCHAR(255) NOT NULL, created_at TIMESTAMP DEFAULT NOW() );

### Components
1. **Component A** - [responsibility]
2. **Component B** - [responsibility]

## Test Plan
- Unit: [what to test]
- Integration: [what to test]
- E2E: [what to test]

## Implementation Plan
1. [ ] Step 1 - [description]
2. [ ] Step 2 - [description]
3. [ ] Step 3 - [description]

## Rollout Plan
- [ ] Deploy to staging
- [ ] QA verification
- [ ] Deploy to production (% rollout)

## Metrics & Monitoring
- [Metric to track]
- [Alert to set up]

## Timeline
| Milestone | Date |
|-----------|------|
| Spec approved | [date] |
| Implementation complete | [date] |
| QA complete | [date] |
| Production release | [date] |

Phase 4: Review & Approve

Use ExitSpecMode tool to present spec for approval:

The spec is ready for review. Key decisions:

1. **API Design**: REST vs GraphQL → Chose REST for simplicity
2. **Database**: PostgreSQL for ACID compliance
3. **Auth**: JWT tokens with refresh mechanism

Options to consider:
- Option A: [approach] - Pros: [x], Cons: [y]
- Option B: [approach] - Pros: [x], Cons: [y]

Recommendation: Option A because [reason]

Phase 5: Implement with TDD

After approval, use eng-tdd skill:

1. Red: Write failing test
2. Green: Write minimal code to pass
3. Refactor: Improve code quality

Spec Templates

API Endpoint Spec

# API: [Endpoint Name]

## Endpoint
`POST /api/v1/resources`

## Purpose
[What this endpoint does]

## Authentication
- Required: Yes
- Method: Bearer token

## Request
### Headers
| Header | Required | Description |
|--------|----------|-------------|
| Authorization | Yes | Bearer {token} |
| Content-Type | Yes | application/json |

### Body

{ "name": "string (required, 1-100 chars)", "description": "string (optional, max 500 chars)", "category_id": "integer (required)" }

## Response

### Success (201 Created)

{ "id": 123, "name": "Resource Name", "description": "Description", "categoryid": 1, "createdat": "2024-01-15T12:00:00Z" }

### Errors
| Code | Description |
|------|-------------|
| 400 | Invalid request body |
| 401 | Unauthorized |
| 404 | Category not found |
| 422 | Validation error |

## Business Rules
1. Name must be unique within category
2. User must have write permission
3. [Other rules]

## Test Cases
- [ ] Create with valid data → 201
- [ ] Create with missing name → 400
- [ ] Create without auth → 401
- [ ] Create with invalid category → 404
- [ ] Create duplicate name → 422

Database Migration Spec

# Migration: [Name]

## Purpose
[Why this migration is needed]

## Changes

### New Tables

CREATE TABLE featureflags ( id SERIAL PRIMARY KEY, name VARCHAR(100) UNIQUE NOT NULL, enabled BOOLEAN DEFAULT false, createdat TIMESTAMP DEFAULT NOW() );

### Altered Tables

ALTER TABLE users ADD COLUMN lastloginat TIMESTAMP;

### Indexes

CREATE INDEX idxuserslastlogin ON users(lastlogin_at);

## Data Migration

UPDATE users SET lastloginat = createdat WHERE lastlogin_at IS NULL;

## Rollback Plan

ALTER TABLE users DROP COLUMN lastloginat; DROP TABLE feature_flags;

## Impact
- Downtime required: No
- Estimated duration: < 1 minute
- Affected services: [list]

Feature Spec

# Feature: [Name]

## User Story
As a [user type]
I want to [action]
So that [benefit]

## Acceptance Criteria
- [ ] Given [context], when [action], then [outcome]
- [ ] Given [context], when [action], then [outcome]

## UI/UX
[Mockup link or description]

## Technical Approach

### Frontend
- Components: [list]
- State management: [approach]
- API calls: [list]

### Backend
- Endpoints: [list]
- Services: [list]
- Models: [list]

### Database
- Tables affected: [list]
- New migrations: [list]

## Dependencies
- [ ] [Dependency 1]
- [ ] [Dependency 2]

## Out of Scope
- [What's NOT included]

Integration with Factory

Using Thinking Skills

## Before Writing Spec

1. **Clarify with Socratic Method** (thinking-socratic)
   - What assumptions am I making?
   - What would happen if this failed?
   - Who else needs to be involved?

2. **Identify Risks** (thinking-pre-mortem)
   - What could go wrong?
   - What are we overlooking?

3. **Consider Second-Order Effects** (thinking-second-order)
   - How will this affect other systems?
   - What behavior will this incentivize?

4. **Debias Your Thinking** (thinking-debiasing)
   - Am I anchored to one solution?
   - Am I overconfident?

Spec Mode in Factory

# Enter spec mode for a feature
/spec Add user authentication

# Factory will:
# 1. Activate spec mode
# 2. Use thinking skills to clarify requirements
# 3. Draft specification
# 4. Present with ExitSpecMode for approval

Best Practices

1. Spec before code - Always document before implementing
2. Keep specs updated - Update when requirements change
3. Link to issues - Reference GitHub issues/Jira tickets
4. Include diagrams - Visual architecture aids understanding
5. Define done - Clear acceptance criteria
6. Consider edge cases - Error handling, empty states
7. Plan for rollback - Always have a backout plan
8. Get early feedback - Share drafts before finalizing
9. Time-box speculation - Don't over-engineer specs
10. Test the spec - Review with stakeholders

Anti-Patterns to Avoid

• Analysis paralysis - Spending too long on specs
• Waterfall specs - Not iterating on specs
• Missing stakeholders - Not involving the right people
• Undocumented decisions - Losing context over time
• Gold plating - Over-specifying implementation details
• No validation - Not checking assumptions