← Spec-writing technique guides

How to convert a feature idea into a spec

How-To Spec-writing technique Beginner 1071009HOWTO-1071009

HOWTO-1071009Spec-writing techniqueBeginner

This guide shows you how to turn a rough feature idea into a SpecDD spec that can guide implementation in a spec-driven development workflow.

A feature idea is usually temporary and incomplete. A spec should be durable, local, reviewable, and neutral about implementation details unless the implementation choice is part of the contract.

Short answer

Start with the feature’s local subject and purpose. Convert clear decisions into Must, plausible non-goals into Must not, external relationships into Depends on or References, examples into Scenario, and implementation work into local Tasks. Mark unresolved questions explicitly instead of silently deciding them.

When to use this guide

Use this guide when:

Example feature idea

Rough idea:

Let users add itinerary items faster. If they leave the place blank, do not save the item. If the day is outside the trip range, show a validation error. Do not touch destination search.

That idea can become a small local spec:

Spec: Itinerary validation

Purpose:
  Prevent incomplete or out-of-range itinerary items from being saved.

Owns:
  ./itinerary-validation.js
  ./itinerary-validation.test.js

Must:
  Reject itinerary items without a place name.
  Reject itinerary items whose day is outside the trip date range.
  Preserve existing itinerary items when validation fails.

Must not:
  Change destination search behavior.

Depends on:
  ../dates/date-range.sdd

Scenario: Missing place name
  Given an itinerary item without a place name
  When the item is saved
  Then validation fails
  And the item is not added to the itinerary

Tasks:
  [ ] Add missing-place validation.
  [ ] Add out-of-range day validation.

Done when:
  Validation failure cases are covered by checks.
  Destination search behavior is unchanged.

Steps

1. Restate the feature as a local subject

Avoid starting with a broad product area:

Spec: Trip planning improvements

Prefer the smallest useful subject:

Spec: Itinerary validation

If the feature truly crosses several subjects, write one parent coordination spec and smaller local specs for the pieces that own behavior.

2. Separate decisions from assumptions

Read the idea and classify each line:

Only decided behavior should become durable Must rules. Unresolved questions should stay visible:

Tasks:
  [?] Confirm whether validation errors should be inline or modal.

3. Write required behavior

Convert decisions into outcome-focused Must rules:

Must:
  Reject itinerary items without a place name.
  Reject itinerary items whose day is outside the trip date range.

Do not write:

Must:
  Add a clean validation utility with good UX.

That hides multiple decisions and gives reviewers little to check.

4. Add boundaries and dependencies

If the idea says not to touch another area, make that a boundary:

Must not:
  Change destination search behavior.

If the feature needs another area’s behavior, name it:

Depends on:
  ../dates/date-range.sdd

This helps humans and agents avoid accidental cross-area changes.

5. Capture scenarios

Use Scenario for concrete behavior examples:

Scenario: Out-of-range itinerary day
  Given a trip from June 10 to June 12
  When an itinerary item is saved for June 14
  Then validation fails
  And the item is not added to the itinerary

Scenarios are not tests by themselves, but they make useful test inputs.

6. Create local tasks

Tasks should be small enough to implement inside the spec authority:

Tasks:
  [ ] Add missing-place validation.
  [ ] Add out-of-range day validation.
  [ ] Cover validation failure cases.

Avoid tasks that quietly expand scope:

Tasks:
  [ ] Redesign itinerary editing.

7. Review before implementation

Before treating the spec as authoritative, check:

Generated drafts are planning aids until a human reviews and accepts them.

Working with an agent

Good prompt examples:

Draft the Itinerary validation spec from this feature idea.

Revise the Itinerary validation spec so unresolved product decisions remain explicit.

Review the Itinerary validation spec for ambiguous behavior before implementation.

Each prompt names the human feature or spec. Keep the instruction narrow, then review the output before using it.

Common mistakes

How to verify the result

The feature idea has become a usable spec when:

← Spec-writing technique guides