SDStart Section 1

Process

SDD Workflow

The path from feature idea to verified implementation — each step enforces clarity before speed.

Loading Workflow pipeline…
  1. 1

    Feature idea

    A need emerges

  2. 2

    shape-spec

    Structured conversation — clarify, don't assume

  3. 3

    requirements.md

    Living doc — stories, criteria, open items

  4. 4

    Clarification Gate

    Open items = 0?

  5. 5

    Generate & implement

    Tasks, plans, prompts, code

Gate condition: open items = 0 → then generate tasks & implement

Development Stages

From intent to verified software — each stage has a clear question, artifact, and output. Never skip ahead: spec before plan, plan before tasks, tasks before code.

Stage 1

Specification

What must be built?

Capture intent before any implementation. Use shape-spec to clarify requirements, write user stories, define acceptance criteria, and resolve all open items through the Clarification Gate.

Artifact

requirements.md · shaped spec

Anti-pattern

Skipping straight to prompts — vibe-coding without a spec

Outputs

  • User stories with success criteria
  • Acceptance criteria and data contracts
  • Zero open items (Clarification Gate passed)
Specification → Plan → Tasks → Code → Verify

Stage Reference

1

Specification

What must be built?

Capture intent before any implementation. Use shape-spec to clarify requirements, write user stories, define acceptance criteria, and resolve all open items through the Clarification Gate.

2

Plan

How will we build it?

Translate the approved spec into a structured plan. Define milestones, dependencies, technical approach, and the order of work — still without writing feature code.

3

Tasks

What are the concrete steps?

Break the plan into small, actionable, ordered tasks. Each task should trace back to a user story or acceptance criterion — executable enough for AI or a developer to pick up and run.

4

Code

Build it — does it match the spec?

Implement against the spec and tasks — not against vibes. Code is the output of clear intent, not the source of truth. When code and spec diverge, fix the code.

5

Verify

Does it match what the spec says should happen?

Validate against the spec — not against what the code happens to do. Run acceptance criteria, behaviour checks, and review open items are still resolved.

Shaping Workflow

1

Feature idea

A need emerges — but resist the urge to prompt-and-pray.

2

shape-spec

Structured conversation: frame the problem, map the journey, define contracts, capture open items.

3

requirements.md

Living document with user stories, acceptance criteria, and open items — committed to the repo.

4

Clarification Gate

Hard stop: open items must equal zero. Ambiguity is not carried forward.

5

Generate & implement

Tasks, plans, and AI prompts derived from the spec — then code, then verify against spec.

Remember: What does the spec say should happen — not what does the code happen to do. Verify implementation against the spec, not the other way around.