# Development Specification — Template & Method

A reusable, product-agnostic template for turning a **prototype + screen references** into a clear, build-ready development specification.

Copy this file, rename it `<Product> — Specification.md`, delete the guidance blocks (the `> Guidance:` lines), and fill in every `[bracketed placeholder]`.

---

## How to use this template

### What a spec like this is for
It documents **what the product does and what is required to build it** — behaviour, states, rules, edge cases, and the open decisions blocking delivery. It is written for a mixed audience (Product, Design, Engineering, QA) and reads like product documentation: calm, precise, factual. It is not a pitch and not a visual style guide.

### The one rule: ground everything, invent nothing
Every requirement must trace back to something real — a prototype interaction, a screen reference, or a written decision. Where information does not exist, **say so explicitly** and ask the owner, rather than guessing. A spec that quietly invents behaviour is worse than one with honest gaps.

### Status vocabulary
Tag every claim so readers know how much to trust it:

- **Confirmed** — observed in the prototype or an agreed reference. Safe to build.
- **Recommendation** — a suggestion not yet agreed. Needs sign-off.
- **Needs confirmation** — a real gap or decision that blocks part of the work.
- **Missing information** — the answer does not exist yet; paired with a question to a named owner.

### Priority vocabulary (MoSCoW)
Prioritise each functional requirement:

- **Must have** — release fails without it.
- **Should have** — important, but the release can ship without it if forced.
- **Could have** — desirable; first to be cut.

### Inputs to gather before you start
- [ ] Interactive prototype, or the most complete clickable artefact available
- [ ] Static screen references / mockups for every screen
- [ ] Any written brief, PRD, or decision log
- [ ] A named owner for each discipline (Product, Engineering/Data, Design)
- [ ] Target platform(s) and audience

### Process
1. **Inventory the screens.** List every distinct screen and its states from the prototype/references.
2. **Walk the primary journey** end to end and write it down as a step list (Section 3).
3. **Derive functional requirements** from observed behaviour — one per discrete capability (Section 4). Tag priority and status as you go.
4. **Capture each screen's states and entry points** in a table (Section 5).
5. **Extract the rules** that govern access and behaviour (Section 6).
6. **Stress-test** for edge cases and failures (Section 7).
7. **Write acceptance criteria** (Given/When/Then) for the load-bearing behaviours (Section 8).
8. **Propose analytics** to measure the journeys (Section 9) — flag as recommendations.
9. **Collect every gap** into Open Questions, grouped by owner (Section 10).
10. **Add a screenshot to each requirement** so the spec is legible at a glance.

> Guidance: Keep copy in sentence case. Use short declarative sentences. No marketing language, no hype, no emoji. When you address the reader, "you" is fine.

---
---

# [Product name] — Development Specification

> Guidance: This is the start of the deliverable. Everything below is the fill-in template.

**Status:** [Working draft / In review / Approved]
**Version:** [0.1]
**Date:** [DD Month YYYY]
**Platform:** [iOS · Android / Web / …]
**Audience:** [Product · Design · Dev · QA]

*[One- or two-sentence summary of what the product is and who it serves.]*

> Guidance: State how this spec was derived and how to read the tags, e.g.: "This specification is derived from the interactive prototype and supplied screen references. Behaviour observed in the prototype is tagged **Confirmed**; suggestions not yet agreed are **Recommendation**; gaps that block delivery are **Needs confirmation**. Where information is unavailable it is marked *Missing information* with a question for the relevant owner. Nothing has been invented."

## Contents
1. [Overview](#1-overview)
2. [Scope](#2-scope)
3. [User flow](#3-user-flow)
4. [Functional requirements](#4-functional-requirements)
5. [Screens and states](#5-screens-and-states)
6. [Business rules and permissions](#6-business-rules-and-permissions)
7. [Edge cases and errors](#7-edge-cases-and-errors)
8. [Acceptance criteria](#8-acceptance-criteria)
9. [Analytics and instrumentation](#9-analytics-and-instrumentation)
10. [Open questions](#10-open-questions)

---

## 1. Overview
> Guidance: Why this product exists and what success looks like. Four short answers.

- **Purpose** — *[What the product does and the job it does for the user.]*
- **Problem being addressed** — *[The pain or inefficiency it removes.]*
- **Target users** — *[Who uses it. Tag unknowns: Needs confirmation.]*
- **Expected outcome** — *[The measurable change you expect. If no metric exists: Missing information.]*

---

## 2. Scope
> Guidance: Draw a hard line around the release. Three lists.

### In scope
- *[Capability included in this release.]*
- *[…]*

### Out of scope
- *[Explicitly excluded capability, and why / where it lives instead.]*
- *[…]*

### Future considerations
- *[Things worth doing later but not now.]*
- *[…]*

---

## 3. User flow
> Guidance: The primary journey from entry to core value, as numbered steps. For each step note the user action, the system response, and any alternate/error path.

1. **[Step name]** — *[What the user does.]* System: *[what the system does.]* Alt: *[branch or error path.]*
2. **[Step name]** — *[…]*
3. **[Step name]** — *[…]*

> Guidance: Add secondary flows below the primary one if they matter (e.g. recovery, sign-out, deep links).

---

## 4. Functional requirements
> Guidance: One entry per discrete capability. Number them FR-01, FR-02… Tag a priority (Must/Should/Could). Use the four fields below. Attach a screenshot of the relevant screen. Mark unknowns inline as *Missing information*.

**Priority key:** Must have · Should have · Could have

### FR-01 — [Requirement name]  ·  [Must have]
| | |
|---|---|
| **Description** | *[What it is, in one line.]* |
| **Trigger** | *[What initiates it.]* |
| **Behaviour** | *[What happens, including notable states.]* |
| **Rules** | *[Constraints. Mark gaps as Missing information.]* |

*Screenshot:* `screenshots/fr/[screen].png`

### FR-02 — [Requirement name]  ·  [Should have]
| | |
|---|---|
| **Description** | *[…]* |
| **Trigger** | *[…]* |
| **Behaviour** | *[…]* |
| **Rules** | *[…]* |

*Screenshot:* `screenshots/fr/[screen].png`

> Guidance: Repeat the block for every requirement. A real spec commonly has 10–25.

---

## 5. Screens and states
> Guidance: Every screen, its key states, how it is reached, and a short note. Flag unknown states.

| Screen | Key states | Entry | Notes |
|---|---|---|---|
| [Screen] | [Empty; loading; filled; error; …] | [How it's reached] | [Note / Missing information] |
| [Screen] | [...] | [...] | [...] |

---

## 6. Business rules and permissions
> Guidance: Constraints that govern access and behaviour across screens — auth gates, role differences, read-only data, state-driven display, regional rules. Tag gaps.

- *[Rule, e.g. "All sections except sign-in require an authenticated session."]*
- *[Rule.]*
- **Needs confirmation:** *[Role-based differences, regional restrictions, concurrency limits — whatever is unresolved.]*

---

## 7. Edge cases and errors
> Guidance: Conditions to design and test for. Give the expected handling and a status for each.

| Condition | Expected handling | Status |
|---|---|---|
| [Invalid input at submit] | [Clear, non-blocking error; preserve entered values] | [Missing information] |
| [No network connectivity] | [Indicate stale/unavailable data; allow retry] | [Recommendation] |
| [Session expiry mid-use] | [Prompt re-auth; return to entry point] | [Defined] |
| [...] | [...] | [...] |

---

## 8. Acceptance criteria
> Guidance: Given / When / Then for the load-bearing behaviours. One block per criterion, numbered AC-01… Keep them testable.

**AC-01 · [Title]**
- **Given** *[starting context]*
- **When** *[the action]*
- **Then** *[the observable outcome]*

**AC-02 · [Title]**
- **Given** *[…]*
- **When** *[…]*
- **Then** *[…]*

> Guidance: Cover at least every Must-have requirement and any behaviour with subtle state rules.

---

## 9. Analytics and instrumentation
> Guidance: If none exist in the source, say so and propose events as a Recommendation. Names and properties are placeholders until the data owner confirms.

*[State whether analytics are defined in the source. If proposing, label as Recommendation.]*

| Event | When | Key properties |
|---|---|---|
| [event_name] | [Trigger] | [prop_a, prop_b] |
| [event_name] | [...] | [...] |

*[Success metrics — if not defined, mark Missing information and point back to the Overview.]*

---

## 10. Open questions
> Guidance: Every unresolved decision, grouped by the owner who must answer it. This is the action list that unblocks the build.

### For Product
- **[Topic]:** *[Question.]*
- **[Topic]:** *[Question.]*

### For Engineering / Data
- **[Topic]:** *[Question — auth contract, data source & refresh, integrations, persistence.]*
- **[Topic]:** *[…]*

### For Design
- **[Topic]:** *[Question — error/empty/loading states, theming, platform scope.]*
- **[Topic]:** *[…]*

### At a glance
*[One paragraph: how many requirements across how many screens, what is well defined, and where the principal gaps are.]*

- **Confirmed:** *[the solid parts.]*
- **Needs confirmation:** *[the decisions outstanding.]*
- **Missing information:** *[the unknowns blocking build.]*

---

*[Product name] — Development specification · [Status] v[0.1] · [DD Month YYYY]*