Section 1 · shape-spec
Structured Feature Shaping
Ensure the AI and team fully understand a feature before writing code. Replace assumption-driven vibe-coding with structured clarification.
Conversation Phases
Phase 1
Frame the Feature
- ·What problem does this solve? (user pain, not technical solution)
- ·Who is the user? (specific role, not 'everyone')
- ·What does success look like? (measurable outcome)
- ·What is explicitly out of scope?
Phase 2
Map the Journey
- ·Trigger — What causes the user to need this?
- ·Steps — What do they do, in order?
- ·Decision points — Where might paths branch?
- ·End state — What changed when done?
Phase 3
Define Contracts
- ·Inputs — What data enters the system?
- ·Outputs — What must be produced?
- ·Acceptance criteria — How do we know it works?
- ·Edge cases — What happens when things go wrong?
Phase 4
Capture Open Items
- ·List anything still unclear with [OPEN] status
- ·Do not proceed until all items are [RESOLVED]
- ·Log items in requirements.md Clarification Gate table
Checklist
- Problem statement written (1–2 sentences)
- User role identified
- Success criteria defined (checkboxes, not vibes)
- User journey mapped (trigger → steps → end state)
- Out-of-scope items listed
- Acceptance criteria written
- Data contracts sketched (if applicable)
- Open items logged in requirements.md
- All open items resolved (Clarification Gate passed)
Anti-Patterns
| Avoid | Instead |
|---|---|
| Just build it and we'll iterate | Shape first, then build |
| Specs in chat only | Commit specs to the repo |
| "Looks good to me" as done criteria | Write checkboxes |
| Implementation details in user stories | Focus on user goals |
| Skipping open items | Log and resolve every ambiguity |