tjboudreaux 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
```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] |
### 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]
### 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)
{
"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
### 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
ALTER TABLE users
ADD COLUMN last_login_at TIMESTAMP;
Indexes
CREATE INDEX idx_users_last_login ON users(last_login_at);
Data Migration
UPDATE users SET last_login_at = created_at WHERE last_login_at IS NULL;
Rollback Plan
ALTER TABLE users DROP COLUMN last_login_at;
DROP TABLE feature_flags;
Impact
- Downtime required: No
- Estimated duration: < 1 minute
- Affected services: [list]
### 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
## 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
- 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