Use this structure when writing spec documents. Adapt section depth to the complexity of the feature — not every spec needs every section.
Before writing: Read 1-2 existing specs in the target folder to match local conventions (tone, heading depth, use of tables vs prose, code example density).
# [Feature Name]
> **Status**: 📋 **PROPOSED** — Ready for implementation.
_One-sentence summary of what this feature does and why._
---
## TL;DR
- **Problem**: What's broken or missing today
- **Solution**: What we're building
- **Key insight**: The non-obvious thing that shaped the design
- **Phase 2 vision** (optional): Where this could go next
---
## Motivation
### Current State
What exists today and why it's insufficient.
### Desired State
What the world looks like after this is implemented. Include file trees,
output examples, or user flows where helpful.
---
## Design
Technical design decisions. Include:
- API surfaces and interfaces
- Data flow / architecture diagrams (ASCII art)
- Key decision tables (scenario → behavior)
- Failure handling strategy
- Integration points with existing systems
- Configuration options
---
## Implementation
### Phase 1: [Name]
Break into logical phases. For each phase, include:
- What's being built
- Key code changes with file paths
- Interface definitions (TypeScript, etc.)
### Phase 2: [Name] (Future)
Optional. Describe future phases with enough detail to validate
Phase 1 design decisions, but don't over-specify.
---
## File Changes Summary
| File | Change Type | Description |
| ---- | ----------- | ----------- |
| `path/to/file.ts` | Modify | What changes |
### No Changes Required
| File | Reason |
| ---- | ------ |
| `path/to/other.ts` | Why it doesn't need changes |
---
## Risks and Mitigations
| Risk | Likelihood | Impact | Mitigation |
| ---- | ---------- | ------ | ---------- |
| Description | Low/Medium/High | Low/Medium/High | How to handle |
---
## Success Definition
This spec is successful if:
- [ ] Checkable criterion 1
- [ ] Checkable criterion 2
- [ ] Checkable criterion 3
- [ ] No regression in existing behavior when feature is not used
---
## Related Documents
- [RELATED_SPEC.md](./RELATED_SPEC.md) — Brief description of relationship| Status | Meaning |
|---|---|
| 📋 PROPOSED | Ready for implementation |
| 🚧 IN PROGRESS | Currently being implemented |
| ✅ COMPLETE | Fully implemented |
| ✅ PHASE N COMPLETE | Partial completion with remaining phases noted |
- TL;DR: 3-4 bullets max. Someone should understand the whole spec from this alone.
- Motivation: Focus on why, not what. The "what" belongs in Design.
- Design: Be specific enough that implementation is unambiguous. Include TypeScript interfaces, ASCII diagrams, and decision tables.
- Implementation: Organize by phase. Include actual file paths and code snippets.
- File Changes Summary: List every file that changes AND files that explicitly don't change (with reasons). This prevents scope creep.
- Success Definition: Use checkbox format (
- [ ]) so the user can track progress. Each criterion should be independently verifiable. - Risks: Be honest about likelihood and impact. Every risk needs a mitigation.