nathangeerinck/dotfiles/spec-writer

Spec Writer

Transform ideas into developer-ready specifications through structured brainstorming and planning.

The Process

Phase 1: Idea Honing (Brainstorm)

Ask ONE question at a time to develop a thorough spec. Each question builds on previous answers. Goal: detailed specification ready for implementation.

Start with:

I'll help you develop a detailed spec for this idea. I'll ask one question at a time.
 
Let's start: [First clarifying question about the core problem/goal]

Key areas to explore:

• Core problem: What pain point does this solve?
• Users: Who uses this? What are their workflows?
• Features: What are the must-haves vs nice-to-haves?
• Data: What entities exist? How do they relate?
• Integrations: What external systems are involved?
• Constraints: Performance, security, tech stack requirements?
• Edge cases: What could go wrong? How to handle it?

When brainstorming concludes naturally, compile into SPEC.md.

Phase 2: Architecture

Create ARCHITECTURE.md covering:

• System overview diagram (Mermaid)
• Component breakdown
• Data flow
• Key technical decisions
• File/folder structure

Phase 3: Implementation Plan

Break the spec into small, iterative chunks:

1. First pass: Major phases/milestones
2. Second pass: Break each phase into tasks
3. Third pass: Ensure tasks are:

• Small enough for safe implementation with tests
• Big enough to move the project forward
• Building on previous tasks (no orphaned code)
• Ending with integration/wiring

Output: PROMPT_PLAN.md with ready-to-use prompts for each step.

Phase 4: Checklist

Generate TODO.md as a checkable list that tracks progress.

Output Structure

analysis/                    # or docs/, specs/, etc.
├── SPEC.md                  # Full specification
├── ARCHITECTURE.md          # System design
├── PROMPT_PLAN.md           # Step-by-step implementation prompts
├── TODO.md                  # Checklist version
└── phases/                  # Optional: detailed phase docs
    ├── 01-phase-name.md
    ├── 02-phase-name.md
    └── ...

SPEC.md Template

# [Project Name] Specification
 
## Overview
[One paragraph summary]
 
## Problem Statement
[What pain point this solves]
 
## Users & Personas
[Who uses this and how]
 
## Features
 
### Must Have (MVP)
-[ ] Feature 1: [description]
-[ ] Feature 2: [description]
 
### Should Have
-[ ] Feature 3: [description]
 
### Nice to Have
-[ ] Feature 4: [description]
 
## Data Model
[Entities, relationships, key fields]
 
## User Flows
[Step-by-step workflows for key actions]
 
## Technical Requirements
-Stack: [technologies]
-Integrations: [external services]
-Performance: [requirements]
-Security: [considerations]
 
## Edge Cases & Error Handling
[What could go wrong and how to handle it]
 
## Success Criteria
[How do we know it's done? What tests prove it works?]
 
## Open Questions
[Anything still TBD]

PROMPT_PLAN.md Format

Each prompt section should:

1. Reference what exists (files, patterns to follow)
2. State the specific task
3. Include verification criteria (tests, expected output)
4. Be tagged with markdown code blocks for easy copy/paste

## Phase 1: [Name]
 
### Step 1.1: [Task Name]
 
**Context**: [What exists, what patterns to follow]
 
**Prompt**:
\`\`\`
[Ready-to-use prompt for the AI agent]
 
Verification:
-[ ] Test X passes
-[ ] Feature Y works as expected
\`\`\`
 
### Step 1.2: [Next Task]
...

Best Practices

1. One question at a time during brainstorming — don't overwhelm
2. Be specific — vague specs produce vague implementations
3. Include verification — every feature needs a "done" signal
4. Reference patterns — point to existing code as examples
5. Small steps — each prompt should be achievable in one session
6. No orphans — every step ends with integration
7. Test-first thinking — define expected behavior before implementation

When to Use Each Phase