The 3-Phase Process
Relevant source files
The following files were used as context for generating this wiki page:- spec-process-guide/process/README.md
- spec-process-guide/process/design-phase.md
- skills/spec-driven-development/SKILL.md
- spec-process-guide/methodology/overview.md
- spec-process-guide/templates/tasks-template.md
- spec-process-guide/templates/design-template.md
- skills/requirements-engineering/SKILL.md
- spec-process-guide/process/workflow-diagrams.md
Spec-driven development is a systematic methodology for software feature development that transforms vague ideas into well-defined, implementable solutions. It emphasizes thorough planning and clear documentation to reduce ambiguity, improve quality, and enable effective collaboration, particularly with AI assistants. The core of this methodology is a structured three-phase workflow: Requirements, Design, and Tasks.
Each phase builds upon the previous one, with explicit approval gates to ensure quality and alignment before proceeding. This structured approach helps identify issues early, manages cognitive load by separating concerns, and creates a repository of knowledge for future maintenance and development.
Sources: spec-process-guide/methodology/overview.md:14-17, skills/spec-driven-development/SKILL.md:5-7, spec-process-guide/process/README.md:23-26, spec-process-guide/methodology/philosophy.md:46-51
Overall Workflow
The 3-Phase Process follows a sequential but iterative path from an initial idea to a state where it is ready for implementation. Each phase must be explicitly approved before the next one begins, with loops for refinement based on feedback.
This diagram illustrates the high-level state transitions between the three core phases.
Phase 1: Requirements Gathering
The goal of this phase is to transform a rough idea into a set of clear, structured, and testable requirements. This ensures all stakeholders have a shared understanding of what is being built and provides clear success criteria.
Sources: spec-process-guide/methodology/overview.md:21-23, skills/spec-driven-development/SKILL.md:19-21
Key Activities
- Capture User Stories: Express the feature's value and purpose from a user's perspective using the format:
As a [role], I want [feature], so that [benefit]. - Define Acceptance Criteria: Use the EARS (Easy Approach to Requirements Syntax) format to create specific, testable criteria for each user story.
- Identify Edge Cases and Constraints: Document error conditions, boundary values, and non-functional requirements like performance and security.
- Validate and Review: Present the requirements to stakeholders for feedback and approval to ensure completeness and feasibility.
Sources: skills/spec-driven-development/SKILL.md:22-27, skills/requirements-engineering/SKILL.md:39-65
EARS Format
The EARS format provides a structured way to write unambiguous requirements.
| Keyword | Purpose | Format |
|---|---|---|
| WHEN | For event-driven requirements. | WHEN [event] THEN [system] SHALL [response] |
| IF | For state-driven requirements. | IF [precondition] THEN [system] SHALL [response] |
| WHILE | For requirements that must be maintained continuously. | WHILE [condition] [system] SHALL [continuous behavior] |
Sources: skills/spec-driven-development/SKILL.md:29-33, spec-process-guide/resources/standards.md:18-45, skills/requirements-engineering/SKILL.md:16-28
Requirements Phase Flow
The following diagram shows the detailed workflow for the requirements gathering phase.
Phase 2: Design Documentation
This phase transforms the approved requirements into a comprehensive technical blueprint for implementation. It involves research, architectural decisions, and detailed planning to bridge the gap between what to build and how to build it.
Sources: spec-process-guide/process/design-phase.md:20-23, skills/spec-driven-development/SKILL.md:50-52
Key Activities
- Requirements Analysis & Research: Thoroughly review requirements to identify technical unknowns and plan research activities into technology stacks, integrations, and architectural patterns.
- System Architecture Definition: Describe the high-level system overview, component architecture, data flows, and technology choices.
- Component & Interface Design: Detail the responsibilities of each component, their dependencies, and the interfaces through which they communicate.
- Data Modeling: Define core data structures (entities), their properties, validation rules, and relationships.
- Error Handling & Testing Strategy: Plan for error scenarios, recovery mechanisms, and define the approach for unit, integration, and end-to-end testing.
Sources: spec-process-guide/process/design-phase.md:31-112, skills/design-documentation/SKILL.md:22-98
Design Document Structure
A standard design document serves as the primary output of this phase.
| Section | Description |
|---|---|
| Overview | High-level summary of the feature and technical approach. |
| Architecture | System context, high-level architecture diagrams, and technology stack decisions. |
| Components & Interfaces | Detailed descriptions of each component, its responsibilities, and its APIs. |
| Data Models | Definitions of data structures, validation rules, and entity relationships. |
| API Design | Specifications for any new or modified API endpoints. |
| Security Considerations | Authentication, authorization, and data protection strategies. |
| Error Handling | Categorization of potential errors and the system's response strategies. |
| Testing Strategy | The approach for unit, integration, and end-to-end testing. |
Sources: spec-process-guide/templates/design-template.md:25-220, skills/spec-driven-development/SKILL.md:54-70
Design Phase Flow
This diagram outlines the workflow for creating the technical design.
Phase 3: Task Planning
The final phase of the spec process involves breaking down the approved design into a sequence of actionable, discrete coding tasks. This creates a clear implementation plan that makes large features manageable and enables progress tracking.
Sources: spec-process-guide/methodology/overview.md:55-57, skills/spec-driven-development/SKILL.md:72-74
Key Activities
- Decomposition: Convert design components, interfaces, and data models into specific, small coding tasks.
- Sequencing: Order tasks to respect dependencies, often following a "foundation-first" or "feature-slice" approach.
- Detailing: Define clear objectives, completion criteria, and implementation notes for each task.
- Traceability: Reference the specific requirements and design elements that each task addresses to ensure full coverage.
Sources: spec-process-guide/templates/tasks-template.md:100-116, spec-process-guide/methodology/overview.md:58-62
Task Structure Example
Tasks are typically structured hierarchically in a checklist format.
- [ ] 1. Phase 1: Foundation and Setup
- [ ] 1.1 Set up project structure and dependencies
- _Requirements: [REQ-01]_
- [ ] 1.2 Implement core data models and interfaces
- _Requirements: [REQ-05, REQ-06]_
- [ ] 2. Phase 2: Core Business Logic
- [ ] 2.1 Create [Component Name] service
- _Requirements: [REQ-02]_
- [ ] 3. Phase 3: API Layer
- [ ] 3.1 Implement REST API endpoints for [Resource]
- _Requirements: [REQ-03, REQ-04]_
Sources: spec-process-guide/templates/tasks-template.md:36-98, skills/spec-driven-development/SKILL.md:76-83
Tasks Phase Flow
This diagram shows the process of creating an implementation plan from the design.
Quality Gates and Iteration
A core principle of the 3-Phase Process is validation at every stage. Each phase concludes with a review and an explicit approval gate. Feedback can trigger a revision loop within the current phase or, if a fundamental issue is discovered, a backtrack to a previous phase.
This feedback loop ensures that misunderstandings are caught early and that each phase is built on a solid, validated foundation.
Conclusion
The 3-Phase Process (Requirements, Design, Tasks) provides a structured and systematic framework for developing software features. By emphasizing clarity before code, iterative refinement, and documentation as a communication tool, it reduces risk, improves quality, and enhances collaboration. This methodology ensures that development effort is focused and aligned with business needs, resulting in more robust, maintainable, and successful software.
Sources: spec-process-guide/methodology/overview.md:64-85, spec-process-guide/methodology/philosophy.md:11-28