SPEC Phase
Formalize the plan into technical specification.
Spec Structure
1. Overview
One paragraph linking back to the plan. What is being built and why (from PLAN.md).
2. Architecture
Describe the technical approach:
- •Components and their responsibilities
- •Data flow between components
- •External integrations
- •Key technical decisions with rationale
Use diagrams where helpful (mermaid, ASCII, or description).
3. Data Model
Define data structures:
- •Entities and relationships
- •Key fields and types
- •Validation rules
- •Storage approach
4. Interface Contracts
For each boundary (API, UI, integration):
- •Inputs (with types and constraints)
- •Outputs (with types and error cases)
- •Behavior specification
5. Domain Bridge (Width)
Explicitly connect technical decisions to business/user intent:
| Business Need | Technical Implementation |
|---|---|
| [need from plan] | [how spec addresses it] |
This prevents spec drift from plan intent.
6. Quadrant Coverage
Ensure spec addresses all perspectives:
| Quadrant | Spec Element |
|---|---|
| Individual Outer | Components, interfaces, data structures |
| Individual Inner | Skills/knowledge required to implement |
| Collective Outer | System integrations, infrastructure |
| Collective Inner | Team alignment, review needs |
7. Skill Dependencies (Height)
Document implementation prerequisites:
- •What capabilities must the team have?
- •What domain expertise is required?
- •What learning must happen before or during implementation?
8. Identity Trap Check
Flag where spec might be protecting assumptions rather than solving problems:
- •Are any technical decisions "because we always do it this way"?
- •What alternatives were dismissed too quickly?
9. Testability Criteria
For each spec item, define how correctness is verified:
| Spec Item | Verification Method |
|---|---|
| [item] | [how we know it's right] |
If you can't define verification, the spec is too vague.
10. Transcend and Include (Time)
Document what existing code/patterns are being:
- •Kept: [what stays unchanged]
- •Extended: [what's being built upon]
- •Replaced: [what's being deprecated]
Output Format
Produce a standalone document titled SPEC.md with sections above.
Include enough detail that implementation is unambiguous, but no more.
Exit Criteria
Proceed to GAP ANALYSIS when:
- •Every plan item maps to spec item
- •All interfaces are defined
- •Verification criteria exist for each component
- •User confirms spec matches intent