How the specification writing rule works

---
description: Specification writing standard for Domain, Feature, and Programme specs. Use when drafting, rewriting, or reviewing the product specification.
alwaysApply: false
---

# Specification writing standard

This standard governs Domain, Feature, and Programme specifications. It applies to human authors, AI assistants, and reviewers. Its purpose is to make intended behaviour understandable, reviewable, and maintainable across projects, regardless of the author's technical background.

**Core rule:** write enough that a reader unfamiliar with the original discussion can understand the intended behaviour without inventing business rules. Use the smallest document that achieves this.

## 1. Choose the right document

| Type | Purpose | Lifecycle |
| --- | --- | --- |
| **Domain** | Explain shared or reusable concepts, their meaning, relationships, and rules. A Domain spec may augment a glossary but is not limited to definitions. | Maintained as those concepts evolve. |
| **Feature** | Specify a flow that delivers an outcome, such as transferring money to another bank or applying for a quick loan. | Maintained as the intended feature behaviour evolves. |
| **Programme** | Specify a change to the system, including changes spanning multiple features or projects. | Active until implementation and incorporation into enduring specs are complete; then archived as historical context. |

Domain and Feature specs are the enduring description of intended behaviour. Programmes describe proposed or in-progress changes to that description. Implementation tickets divide a Programme into work; they do not replace these specifications.

Put reusable rules in Domain specs and flow-specific behaviour in Feature specs. Link to the owning spec rather than copying its rules. If a Feature has an authorised exception to a Domain rule, state the exception explicitly and record it in the owning Domain spec as well.

## 2. Common writing rules

- Use plain language and consistent domain terminology. Explain unfamiliar terms on first use or link to their definition.
- Describe user and business intent, conditions, rules, and observable outcomes. Include technical detail only when it is necessary to define a contract or constraint.
- Make each rule precise enough to review or verify. Prefer “When X happens, Y must happen” to phrases such as “handle appropriately”, “seamlessly”, or “as needed”.
- Use **must** for requirements, **should** for recommendations where exceptions are allowed, and **may** for permitted options. Explain the conditions for an exception when they matter.
- Separate confirmed requirements from proposals, assumptions, and open questions. An AI-generated suggestion is not an agreed requirement.
- Include concrete examples where they clarify a rule, boundary, calculation, or exception. Examples illustrate rules; they do not silently add requirements.
- Reference existing definitions and rules instead of repeating them. Summaries are allowed when useful, but identify the authoritative source.
- Describe relevant failure, cancellation, retry, and recovery behaviour. Include permissions, timing, limits, and externally visible side effects where they affect the outcome.
- State meaningful exclusions so readers can distinguish intentional scope boundaries from omissions.
- Do not infer intended behaviour solely from existing code. Distinguish observed implementation from agreed requirements when they differ or are uncertain.

### Length and presentation

There is no word-count target. Prefer short paragraphs for explanations, lists for steps and rules, and tables for combinations of conditions and outcomes. Avoid repeating the same information in several formats.

The templates below define required substance, not a form to fill mechanically. Combine sections when that improves readability. Omit an inapplicable section; if its absence could look like an oversight, briefly explain why it does not apply. Never invent content to fill a heading.

### Common document header

Every spec must include:

```markdown
# <Clear, descriptive title>

- Type: Domain | Feature | Programme
- Status: <See lifecycle rules below>
- Confidence: confirmed | observed | specified
- Owner: <Accountable person or team; use “Unassigned” until known>
- Scope: <Applicable products, projects, or contexts>
- Repositories: <Affected repository identifiers or links>
- Services: <Affected service or microservice identifiers>
- Related specs: <Links to relevant specifications, or None>
```

Use stable links or identifiers so documents can be referenced across repositories. Where implementations support different versions of a shared contract, identify the applicable version explicitly. A shared spec must not imply that all projects have already adopted a change.

### Repositories and services

Record affected repositories and services in metadata alongside confidence. A specification may span multiple services and repositories; do not split a coherent feature solely to match deployment boundaries.

- **Domain:** identify the known repositories and services that implement or depend on the concept and its rules.
- **Feature:** identify the repositories and services that participate in delivering the documented flow.
- **Programme:** identify repositories and services requiring changes, and dependencies or consumers whose compatibility must be checked. Distinguish these roles explicitly.

Use existing repository and service names consistently. Repositories and services are distinct: one repository can contain several services, and a service can depend on code from several repositories. Include frontends, shared libraries, and external services when relevant; do not limit impact tracking to backend microservices.

For specifications spanning services, include a short impact map in the body or structured metadata:

| Service or component | Repository | Role in the flow or change | Impact |
| --- | --- | --- | --- |
| `<Known service name>` | `<Repository link or identifier; external if applicable>` | `<Responsibility or dependency>` | `<Change required, compatibility check, or participation only>` |

The metadata provides a discoverable index; the impact map explains why each entry matters. Keep them consistent. Mark unresolved ownership or impact as unknown and record the investigation needed. An empty list must not silently mean “not yet investigated”. Do not invent a service decomposition for a new feature whose technical design has not been decided.

Confidence applies to the documented behaviour across the stated scope. Browser observation of an end-to-end journey does not establish which internal services implement it. Support the service mapping with code, configuration, or other architectural evidence, and mark tentative mappings explicitly. Where confidence differs by service responsibility or flow segment, record those differences in the evidence section; retain the same criteria for each confidence value. A `confirmed` frontend does not make an entire multi-service flow `confirmed`.

For changes across services, describe relevant API or event contracts, compatibility expectations, and adoption order in the Programme. Link to detailed contracts rather than copying them. Update the impact metadata when investigation changes the known scope.

### Confidence and evidence

Existing functionality may not yet be fully documented. The `confidence` metadata records the basis for the description, so readers can distinguish verified implementation, observed behaviour, and intent awaiting implementation. Use the exact values below, including when the repository stores metadata in YAML front matter.

| Confidence | Meaning | Evidence required |
| --- | --- | --- |
| `confirmed` | The documented behaviour has been validated in the browser and through inspection of all relevant implementation code. | Browser verification of the described behaviour and review of the code paths, layers, and dependencies that determine it within the stated scope. |
| `observed` | The behaviour has been seen using the browser, but its implementation has not been fully inspected or understood. | Direct browser observation, with the scenarios exercised and remaining unknowns identified. |
| `specified` | The document describes a new feature or change that has not yet been implemented. | Explicit intended behaviour; no claim that the implementation already exists. |

These values describe evidence and implementation state, independently of approval status. An approved new feature can be `specified`. An `observed` flow may expose an existing defect rather than an agreed business rule. `confirmed` means the implementation supports the description within the checked scope; it does not mean every observed behaviour is desirable or that the entire system is defect-free.

For `observed` and `confirmed` specs, include a short **Evidence and gaps** section recording:

- When the checks were performed and which environment, build, or revision was checked, where identifiable.
- The scenarios, roles, and relevant conditions exercised in the browser.
- For `confirmed`, the implementation areas inspected and references sufficient to locate the supporting code.
- Unchecked behaviour, unresolved discrepancies, and limits on what the evidence establishes.

Do not infer hidden rules from a successful browser journey. Do not assign `confirmed` after inspecting only the UI code when backend logic or other components determine the documented behaviour. Code inspection alone does not satisfy either browser-based confidence level; record it as partial evidence and leave confidence unassigned until an applicable level can be justified. An unassigned draft is a documentation gap, not a fourth confidence level. Never use `specified` as a fallback label for existing behaviour that has not been investigated.

For documents containing different kinds of evidence:

- Keep current behaviour and proposed changes clearly separated. Prefer keeping proposed changes in the Programme until they are incorporated into enduring specs.
- Scope the document-level tag explicitly and label sections whose confidence differs. A Programme tagged `specified` may cite `observed` or `confirmed` current behaviour without claiming its proposed change is implemented.
- Use `observed` for an implemented flow whose browser behaviour has been checked but whose relevant code has only been partly inspected; identify any confirmed portions separately.
- If a single tag would misrepresent the document, split its scope or use an explicit section-level confidence table. Never silently apply the strongest tag to the whole document.

Change confidence only when supporting evidence changes. Implementation, passing tests, approval, or Programme completion alone does not automatically promote a spec to `confirmed`. Reassess evidence when behaviour changes, and retain the checked revision or date so readers can judge its applicability.

## 3. Domain specifications

A Domain spec explains a reusable concept deeply enough that features can use it consistently. It is not a catalogue of implementation classes, tables, or services.

Suggested structure:

```markdown
## Purpose and meaning
What is this concept? Why does it exist? Where does it apply?
Define important terms and distinguish similar concepts.

## Rules and invariants
What must always be true? Under what conditions do rules apply?
Identify permissions, constraints, and authorised exceptions where relevant.

## Relationships
How does this concept relate to other domain concepts?
Link to their owning specifications.

## Lifecycle
If the concept has meaningful states, define the states, allowed transitions,
their triggers, and any relevant restrictions.

## Examples and boundaries
Give representative examples and clarify what does not belong to this concept.

## Open questions
List unresolved decisions and their effect on the specification.
```

For example, a **Beneficiary** Domain spec might define what a beneficiary represents, who can manage one, and what its verification states mean. The steps for sending a transfer to that beneficiary belong in the relevant Feature spec.

## 4. Feature specifications

A Feature spec describes a flow and its intended outcomes. A reader must be able to understand what happens during normal use and relevant alternatives without reconstructing a history of Programmes or tickets.

Suggested structure:

```markdown
## Purpose and outcome
What does this feature let an actor achieve? What counts as success?

## Actors and prerequisites
Who participates? What permissions and starting conditions are required?

## Main flow
Describe the normal flow as numbered steps, including important actor actions,
system responses, and the final outcome.

## Alternative and failure flows
Identify the point of departure from the main flow, the condition that causes it,
what happens next, and how the actor can recover or finish.

## Rules and observable behaviour
State feature-specific requirements and reference shared Domain rules.
Include relevant limits, timing, permissions, and side effects.

## Verification examples
Give representative scenarios with conditions, actions, and expected outcomes.
Cover consequential boundaries and failures as well as success.

## Scope exclusions
Explain meaningful related behaviour this feature does not cover.

## Open questions
List unresolved decisions and the behaviour they prevent us from specifying.
```

Verification examples describe expected behaviour; they need not prescribe test frameworks or implementation details. User stories may help explain motivation, but do not replace rules and flows.

## 5. Programme specifications

A Programme explains why a change is needed, what it changes, and how completion will be assessed. It must identify the affected Domain and Feature specs, including any that need to be created.

Choose one of two writing modes:

- **Difference-based:** for a bounded change, reference the existing spec and state precisely what is added, removed, or replaced.
- **Full proposed flow:** for a complex change, describe the intended flow in full and identify which existing behaviour it replaces. Reference shared Domain rules rather than reproducing them.

Use the full proposed flow when a reviewer would otherwise have to mentally combine several documents to understand the change. Different parts of a Programme may use different modes if their boundaries are clear.

Suggested structure:

```markdown
## Problem and intended outcome
Why is this change needed? What result are we trying to achieve?

## Current behaviour and affected specs
Summarise the relevant starting point and link to the authoritative specs.
Identify affected projects and any known implementation/specification mismatch.

## Proposed change
State whether this section describes differences or a full proposed flow.
Make new, changed, and removed behaviour explicit.

## Scope and exclusions
What is included? What related work is intentionally excluded?

## Acceptance criteria
List observable conditions that demonstrate the change works.
Cover relevant success, failure, and boundary cases.

## Dependencies and transition
Where relevant, describe prerequisites, adoption order, compatibility,
migration, and behaviour while old and new versions coexist.

## Enduring specification updates
List each Domain or Feature spec to update or create and what it must capture.

## Open questions and decisions
Record unresolved questions, consequential assumptions, and agreed decisions.
Link to technical design or architectural decisions where needed.
```

Keep detailed delivery tasks in linked tickets or plans. Include implementation constraints in the Programme only when they materially affect the agreed change.

## 6. Diagrams

Use Mermaid when a diagram materially improves understanding. Diagrams are not mandatory for every document.

Include an appropriate diagram when any of these are central to understanding the spec:

| Situation | Preferred diagram |
| --- | --- |
| Branching paths whose connections are difficult to follow in text | Flowchart |
| Ordering of interactions between multiple actors or systems | Sequence diagram |
| Meaningful states and constrained transitions | State diagram |

Diagram rules:

- Use the same names and terminology as the prose.
- Show behaviour at the level of the spec. Do not invent services or infrastructure merely to draw a sequence diagram.
- Keep diagrams focused. Split unrelated flows instead of creating one large diagram.
- Label meaningful branches and transitions; do not make readers infer their conditions.
- Put detailed rules, limits, and exceptions in prose or tables. Reference them from the diagram where helpful.
- Diagrams and text must agree. A contradiction is a defect to resolve before approval, not an invitation for the reader to choose one.
- Preview Mermaid to verify that it renders and remains readable.

A short linear flow can usually remain a numbered list. A decision table may communicate combinations of conditions more clearly than a flowchart.

## 7. Working with AI

AI assistants must follow the same standard as human authors.

- Read the relevant existing specs before drafting changes. If a referenced spec is unavailable, identify the missing context rather than guessing its contents.
- Help authors express business behaviour without requiring technical vocabulary. Ask concrete questions about actors, conditions, examples, and outcomes.
- Surface conflicting rules, missing cases, and ambiguous terminology. Ask focused questions about consequential gaps rather than presenting an exhaustive generic questionnaire.
- Never silently invent business policy, permissions, limits, deadlines, error recovery, or acceptance decisions. Mark proposals and assumptions explicitly until an accountable person confirms them.
- Keep business specification accessible to nontechnical reviewers. Place detailed technical design in linked documents when needed.
- Preserve agreed scope and meaning when editing. Flag substantive changes for review rather than presenting them as wording improvements.
- Never mark a spec approved merely because it is complete or well formatted. Approval requires the designated human or team decision process.
- Assign confidence only from evidence actually collected. Never claim browser validation or complete code inspection that did not occur; record gaps explicitly.

## 8. Review and lifecycle

Use **Draft**, **Approved**, and **Superseded** for Domain and Feature specs. Use **Draft**, **Approved**, **In progress**, **Completed**, and **Cancelled** for Programmes. Approval means agreement on the described intent; it does not mean the behaviour has been deployed.

Review must establish:

- Can a reader unfamiliar with the original conversation understand the purpose and behaviour?
- Could two competent readers derive materially different outcomes from the wording?
- Are consequential rules and exceptions explicit, with relevant failures and boundaries covered?
- Are references sufficient and accessible, and is each rule's authoritative home clear?
- Are proposals, assumptions, and unresolved questions visibly distinguished from agreed requirements?
- Can the specified outcomes be verified without inventing additional policy?
- Do diagrams and prose agree?
- Does the confidence tag match the recorded evidence and its scope, with any mixed-confidence sections clearly identified?
- Are affected repositories and services identified, their roles clear, and any unknown impact or compatibility work explicit?

Questions that materially affect correctness or scope must be resolved before approving the affected work. Independent, settled parts may proceed if the unresolved scope is explicitly excluded.

### Completing a Programme

A Programme is complete only when:

1. The agreed implementation and acceptance verification are complete.
2. Affected Domain and Feature specs have been updated or created, reviewed, and linked from the Programme.
3. Those enduring specs can be understood without consulting the Programme for current rules.
4. Any remaining work or deferred scope has an explicit disposition.
5. Confidence and evidence in the updated enduring specs accurately reflect the verification performed; completion does not imply `confirmed`.

Prepare enduring-spec updates alongside implementation where practical. If the documented target behaviour precedes adoption, clearly identify its applicability and transition state.

After completion, archive the Programme as historical context. Its requirements must no longer be the sole source of current behaviour. For cancelled Programmes, preserve the cancellation decision without incorporating abandoned proposals as current requirements.

**Final quality test:** a specification is ready when readers can agree on what must happen, when it must happen, and how they will know it happened—not merely when every heading has content.