Templates · CC BY 4.0

Feature spec template with Given/When/Then

A feature spec says what one feature must do, in words a founder can read and a test can run. This template covers user stories, acceptance criteria in Given/When/Then, states and edge cases, the data collected and why, and what is out of scope.

Updated 22 November 2026

When to use it

Write one feature spec for each feature, before any code. It inherits every rule from the constitution, so it only records what is specific to the feature. In an existing codebase, a change to a shipped feature is written as a delta against its spec: ADDED, MODIFIED or REMOVED.

The spec is done when someone outside the team could read it and say whether the feature works.

How to fill it in

Start with the user stories, then write criteria until every story is covered. Most of the value is in sections 4 and 5: the states and edge cases nobody draws in a design file, and the data the feature touches.

  • Acceptance criteria follow Given/When/Then. One behaviour per scenario. Each scenario becomes one automated test. See acceptance criteria for frontends for more examples.
  • States list everything the user can see: empty, loading, partial, error, offline, permission denied.
  • Data lists every field with its purpose, where it goes, and whether it is kept.
  • Out of scope is as important as scope. It stops the feature from growing in review.

The template

# Feature spec: [Feature name]

ID: [FEAT-000] · Version: [1.0] · Status: [draft / agreed / shipped]
Constitution: [link] · Owner: [role] · Last changed: [YYYY-MM-DD]

## 1. Summary
[Two or three sentences: what the feature does and why it exists.]

## 2. User stories
- As a [type of user], I want to [action], so that [outcome].
- As a [type of user], I want to [action], so that [outcome].

## 3. Acceptance criteria
Each scenario is one behaviour and one automated test.

~~~gherkin
Feature: [Feature name]

  Scenario: [AC-1 Happy path in a few words]
    Given [the starting state]
    When [the user does something]
    Then [what they see or what happens]
    And [a further observable result]

  Scenario: [AC-2 An error in a few words]
    Given [the starting state]
    When [the action fails in a specific way]
    Then [what the user sees and can do next]
~~~

| ID | Criterion (one line) | Covers story |
|---|---|---|
| AC-1 | [summary] | [story] |
| AC-2 | [summary] | [story] |

## 4. States and edge cases
| State | When it happens | What the user sees | Criterion |
|---|---|---|---|
| Empty | [condition] | [content] | [AC-x] |
| Loading | [condition] | [content] | [AC-x] |
| Error | [condition] | [content and next step] | [AC-x] |
| Offline | [condition] | [content] | [AC-x] |
| Permission denied | [condition] | [content] | [AC-x] |

Edge cases:
- [e.g. the user leaves halfway and returns on another device]
- [e.g. the same action is submitted twice]

## 5. Data collected and why
| Field | Purpose | Sent to | Stored (where, how long) | Consent needed |
|---|---|---|---|---|
| [field] | [purpose] | [service or none] | [no / location, lifetime] | [yes / no] |

## 6. Rules that apply
| Rule (from the constitution's matrix) | How this feature meets it | Criterion |
|---|---|---|
| [rule] | [behaviour] | [AC-x] |

## 7. Accessibility notes
[Focus order, announcements, error association, anything beyond the constitution's baseline.]

## 8. Out of scope
- [Something this feature will not do in this version]
- [Something another feature owns]

## 9. Open questions
| Question | Who answers (role) | Needed by |
|---|---|---|
| [question] | [role] | [YYYY-MM-DD] |

## 10. Change log
| Date | Delta (ADDED / MODIFIED / REMOVED) | Reason | Approved by (role) |
|---|---|---|---|
| [YYYY-MM-DD] | Initial version | — | [role] |

---
Based on the feature spec template by Tacet Works (tacetworks.com/templates/feature-spec/), CC BY 4.0.

Licence

This template is published under Creative Commons Attribution 4.0. You can copy, adapt and use it commercially. Keep the attribution line at the end of the file.

Next steps

When the feature ships, its criteria appear in the release’s trace report, each with its test and result. If you would like your first specs written with you, that is what a Spec Sprint produces.

Start with a Spec Sprint

One to two weeks to a versioned spec you own, whoever builds it.

Start a Spec Sprint