eng-spec-driven

# 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:** ```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" } ``` ### Database Schema ```sql 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 ```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 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 ```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] ``` ### 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 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