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

code

┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│  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:

markdown

## 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:

markdown

## 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:

markdown

# 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" }

code


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

Components

•Component A - [responsibility]
•Component B - [responsibility]

Test Plan

•Unit: [what to test]
•Integration: [what to test]
•E2E: [what to test]

Implementation Plan

• Step 1 - [description]
• Step 2 - [description]
• 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]

code


### Phase 4: Review & Approve

Use `ExitSpecMode` tool to present spec for approval:

The spec is ready for review. Key decisions:

•API Design: REST vs GraphQL → Chose REST for simplicity
•Database: PostgreSQL for ACID compliance
•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]

code


### 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

```markdown
# 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
```json
{
  "name": "string (required, 1-100 chars)",
  "description": "string (optional, max 500 chars)",
  "category_id": "integer (required)"
}

Response

Success (201 Created)

json

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

Errors

Code	Description
400	Invalid request body
401	Unauthorized
404	Category not found
422	Validation error

Business Rules

•Name must be unique within category
•User must have write permission
•[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

code


### Database Migration Spec

```markdown
# Migration: [Name]

## Purpose
[Why this migration is needed]

## Changes

### New Tables
```sql
CREATE TABLE feature_flags (
    id SERIAL PRIMARY KEY,
    name VARCHAR(100) UNIQUE NOT NULL,
    enabled BOOLEAN DEFAULT false,
    created_at TIMESTAMP DEFAULT NOW()
);

Altered Tables

sql

ALTER TABLE users
ADD COLUMN last_login_at TIMESTAMP;

Indexes

sql

CREATE INDEX idx_users_last_login ON users(last_login_at);

Data Migration

sql

UPDATE users SET last_login_at = created_at WHERE last_login_at IS NULL;

Rollback Plan

sql

ALTER TABLE users DROP COLUMN last_login_at;
DROP TABLE feature_flags;

Impact

•Downtime required: No
•Estimated duration: < 1 minute
•Affected services: [list]

code


### Feature Spec

```markdown
# 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

markdown

## 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

bash

# 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

•Spec before code - Always document before implementing
•Keep specs updated - Update when requirements change
•Link to issues - Reference GitHub issues/Jira tickets
•Include diagrams - Visual architecture aids understanding
•Define done - Clear acceptance criteria
•Consider edge cases - Error handling, empty states
•Plan for rollback - Always have a backout plan
•Get early feedback - Share drafts before finalizing
•Time-box speculation - Don't over-engineer specs
•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