SDSection 2 →

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

AvoidInstead
Just build it and we'll iterateShape first, then build
Specs in chat onlyCommit specs to the repo
"Looks good to me" as done criteriaWrite checkboxes
Implementation details in user storiesFocus on user goals
Skipping open itemsLog and resolve every ambiguity