{{Project / Feature Name}} — Requirements

Status: Draft → In Review → Approved → Superseded · Version: {{0.1}} · Updated: {{YYYY-MM-DD}} Owner: {{Name, function}} · Build lead: {{Name}} · Source: {{scoping meeting / brief / ticket, date}}

Executive Summary

In brief: {{One or two sentences a CEO could repeat in a hallway — what this is and why it matters, in plain language.}}

At a glance


What	{{The thing being built, in one line}}
Why now	{{Business driver — the opportunity or problem forcing the timing}}
Who it's for	{{Primary users / beneficiaries}}
Expected value	{{The outcome, ideally measurable — revenue, retention, cost, risk reduced}}
Rough effort	{{T-shirt size or estimate; note confidence}}
Headline timeline	{{Phase 1 by {{date}}; see §15}}
Top risk	{{The one risk leadership should know about; full list in §10}}

{{Optional: 3–5 sentences of narrative for the reader who wants slightly more than the table but far less than the full document. Keep it strategic, not technical.}}

How to Read This Document

Skim the In brief line under each heading for a fast overview; drop into a section's body only where it's your area.

If you are a…	Start with	You can skip
Non-technical executive	Executive Summary, §1 (Context), §10 (Risks)	Everything §5–§9
Technical executive (CTO/CISO)	Exec Summary, §6 (NFRs), §9 (Architecture & Decisions), §10 (Risks)	Detailed behaviour in §5
Engineering manager	§2 (Scope), §10 (Risks), §11 (Dependencies), §12 (Open questions), §15 (Timeline)	Deep glossary
Product manager	§1–§5, §12 (Open questions), §14 (Phasing)	Low-level data/interface detail
Engineer	§5 (Functional), §6 (NFRs), §7 (Data), §8 (Interfaces), §13 (Acceptance)	Exec framing
Systems architect	§6 (NFRs), §7 (Data), §8 (Interfaces), §9 (Architecture), §11 (Dependencies)	—

Conventions used

MUST / SHOULD / MAY — obligation level inside a requirement.
Priority (MoSCoW): Must · Should · Could · Won't (this release).
FIXED / PROPOSED — a decision vs. a placeholder awaiting input.
IDs — FR- functional, NFR- non-functional, CON- constraint, DATA- data item, INT- interface, DEC- decision, DEP- dependency, RISK- risk, Q- open question. IDs never change once published.

Document Control

Field	Value
Document owner	{{Name, role}}
Author(s)	{{Names}}
Contributors / reviewers	{{Names, roles}}
Approvers	{{Names, roles}}
Classification	{{Public / Internal / Confidential}}
Related documents	{{Design doc, PRD, tickets, meeting notes — links}}

Revision history

Version	Date	Author	Summary of change
0.1	{{YYYY-MM-DD}}	{{Author}}	Initial draft

Approvals — the release does not proceed until these are recorded.

Role	Name	Decision	Date
{{Product owner}}		☐ Approved ☐ Changes requested
{{Engineering lead}}		☐ Approved ☐ Changes requested
{{Security / Architecture}}		☐ Approved ☐ Changes requested

1. Context & Rationale

In brief: {{One line — the problem or opportunity, and the outcome we want.}}

1.1 Problem statement

{{What's the situation today, what's wrong or missing, and who feels it.}}

1.2 Strategic fit & business objectives

{{How this connects to a larger objective — growth, retention, cost, risk, compliance, a strategic bet. Name the objective explicitly.}}

1.3 Goals (and non-goals)

Goals

{{Goal 1 — an outcome}}
{{Goal 2}}

Non-goals (things we are deliberately NOT trying to achieve here)

{{Non-goal — and why it's excluded, if useful}}

1.4 Success metrics

Metric	Baseline (today)	Target	How / where measured
{{e.g. adoption, satisfaction, conversion, cost per X}}	{{value}}	{{value}}	{{tool / source}}

2. Scope

In brief: {{One line — what this release delivers and, crucially, what it deliberately leaves out.}}

2.1 In scope

{{Capability — a short name and one line of what it does}}
{{Capability}}

2.2 Out of scope

{{Excluded item}} — {{why excluded / where it belongs instead}}

2.3 Stretch / future (build only if the core lands early)

{{Stretch item}} — held out of this release because {{reason / open question ref}}.

2.4 Assumptions

{{Assumption}}

2.5 Constraints

ID	Constraint	Type	Rationale
CON-001	{{e.g. must run on existing infrastructure}}	Technical / Business / Regulatory	{{why it holds}}

3. Stakeholders & Users

In brief: {{One line — who decides, who's affected, and who uses it.}}

3.1 Stakeholders

Stakeholder	Interest / concern	Role	Sign-off?
{{Name / function}}	{{what they care about}}	{{Responsible / Consulted / Informed}}	{{Yes/No}}

3.2 Users / personas

Persona	Who they are	What they need to accomplish	Context of use
{{Persona}}	{{description}}	{{their job-to-be-done}}	{{device, setting, frequency}}

4. Overview of the Solution

In brief: {{One line — how the solution works at a conceptual level.}}

{{A few sentences describing the shape of the solution: the main pieces, how a user moves through it, and how it fits into the surrounding systems. Reference a diagram if you have one (see Appendix A). Resist implementation detail — that lives in §5–§9.}}

5. Functional Requirements

In brief: {{One line — the core things the system will let users do.}}

5.1 Requirements list

ID	Requirement	Priority	Source	Acceptance
FR-001	The system MUST {{do X}}	Must	{{goal / ticket}}	AC-FR-001
FR-002	The system SHOULD {{do Y}}	Should		AC-FR-002

5.2 Detailed requirements

FR-001 — {{Short title}}

Description: {{Full statement.}}
Priority: Must · Status: FIXED / PROPOSED
Rationale: {{Why it's needed — tie to a goal.}}
Acceptance criteria (AC-FR-001):
- Given {{precondition}} when {{action}} then {{result}}.
- {{Edge / failure scenario.}}
Dependencies: {{FR / DEP IDs}}
Open questions: {{Q- IDs, or "none"}}

5.3 Behaviour & edge cases

{{Rule / edge case and the exact expected behaviour.}}

5.4 User stories (optional — for teams that prefer them to FR tables)

As a {{persona}}, I want {{capability}}, so that {{benefit}}. Acceptance: {{Given/When/Then}}

6. Non-Functional Requirements (NFRs)

In brief: {{One line — the quality bar: how fast, how secure, how reliable, how accessible this must be.}}

ID	Category	Requirement (measurable target)	Priority
NFR-001	Performance	{{e.g. P95 response < 300 ms at {{load}}}}	Must
NFR-002	Scalability	{{e.g. absorb 10× current volume without redesign}}	Should
NFR-003	Availability	{{e.g. 99.9% monthly uptime excl. planned maintenance}}	Must
NFR-004	Reliability / recovery	{{e.g. RTO < 1h, RPO < 15 min}}	Must
NFR-005	Security	{{e.g. encrypted in transit & at rest; authN/authZ model}}	Must
NFR-006	Privacy / data protection	{{e.g. PII handling, retention, right-to-erasure}}	Must
NFR-007	Compliance	{{e.g. GDPR / HIPAA / SOC 2 / PCI-DSS / sector rules}}	Must
NFR-008	Accessibility	{{e.g. WCAG 2.2 AA}}	Must
NFR-009	Usability	{{e.g. core task completed unaided in < N min}}	Should
NFR-010	Compatibility	{{e.g. last 2 major versions of {{platforms}}}}	Should
NFR-011	Observability	{{e.g. structured logs, metrics, traces on all paths}}	Should
NFR-012	Maintainability	{{e.g. test coverage ≥ N%; documented APIs}}	Should
NFR-013	Localisation	{{e.g. languages, locale-aware formats}}	Could

7. Data & Storage

In brief: {{One line — what information the feature captures and any data sensitivity that matters.}}

7.1 Data the feature needs (FIXED — required regardless of layout)

ID	Data item	Type / values	Notes
DATA-001	{{field}}	{{type, allowed values}}	{{e.g. capture as-of submit time so historical exports stay correct}}

7.2 Storage approach (PROPOSED — pending the actual data model)

{{Describe the rough proposal and explicitly flag it as provisional. Note what information would firm it up — schema conventions, keying, which store it lands in, existing tables to join against.}}

7.3 Retention, volume & sensitivity

Aspect	Value
Expected volume	{{rows / growth rate}}
Retention	{{period / policy; append-only?}}
Sensitivity	{{PII / confidential / regulated — and any contractual limits on where it can live}}

7.4 What we need from other teams

{{Team}} — {{the specific question or artefact you need, and by when}}

8. Interfaces & Integrations

In brief: {{One line — what this connects to.}}

ID	Interface	Direction	Protocol / format	Notes (SLA, limits, auth, reuse)
INT-001	{{system / service}}	Inbound / Outbound	{{REST/JSON, event, file…}}	{{reuse existing mechanism where possible}}

UI / UX references: {{links to designs, wireframes, prototypes}}

9. Architecture & Key Decisions

In brief: {{One line — the technical approach and the one or two decisions that most shape it.}}

9.1 Approach

{{The intended architecture at a level an architect can critique: components, data flow, boundaries, where new code lives vs. what's reused. Reference a diagram in Appendix A if available.}}

9.2 Key decisions

ID	Decision	Status	Alternatives considered	Rationale
DEC-001	{{what was decided}}	FIXED / PROPOSED	{{what was rejected}}	{{why}}

10. Risks & Mitigations

In brief: {{One line — the biggest thing that could go wrong and how it's being managed.}}

ID	Risk	Category	L	I	Score	Mitigation	Contingency	Owner	Status
RISK-001	{{e.g. dependency changes without notice}}	Technical	3	4	12	{{version pinning + contract tests + monitoring}}	{{fallback provider / manual path}}	{{Name}}	Open
RISK-002	{{e.g. key requirement unclear at build time}}	Requirements	3	3	9	{{spike + sign-off before dev}}	{{timebox; flag as assumption}}	{{Name}}	Open
RISK-003	{{e.g. scope creep erodes timeline}}	Delivery	4	3	12	{{change control; scope frozen per milestone}}	{{re-baseline; defer}}	{{Name}}	Open

11. Dependencies

In brief: {{One line — the external things this work is waiting on.}}

ID	Dependency	Owner / team	Needed by	Blocking?	Status
DEP-001	{{e.g. access to X system}}	{{team}}	Build / Rollout	Yes/No	{{Pending}}

12. Open Questions

In brief: {{One line — what still has to be decided, and whether any of it blocks starting.}}

12.1 Blockers (work can't safely proceed until these resolve)

ID	Question	Owner	Needed by	Notes
Q-001	{{...}}	{{Name}}	{{date}}	{{...}}

12.2 Non-blocking (shape the work but don't stop it starting)

ID	Question	Owner	Notes
Q-010	{{...}}	{{Name}}	{{placeholder unblocks build}}

12.3 Owned & external (non-engineering; tracked to closure)

ID	Question	Owner	Needed by
Q-020	{{e.g. final copy, exclusion list, design feedback}}	{{Name}}	{{date}}

13. Acceptance & Definition of Done

In brief: {{One line — what "done" means for this release.}}

The release is complete when:

All Must requirements met and independently verified.
All acceptance criteria in §5 pass.
NFR targets in §6 validated (performance, security, accessibility…).
Test coverage / quality gates met.
Documentation, runbooks, and support handover updated.
A working kill switch / rollback exists and has been tested.
Sign-off recorded from the approvers in Document Control.

14. Validation & Testing Approach

In brief: {{One line — how we'll verify it works before shipping.}}

Requirement type	Verification method	Owner
Functional	{{automated tests / manual QA}}	{{QA}}
Non-functional	{{load test / pen test / accessibility audit}}	{{...}}
Acceptance	{{UAT with {{stakeholder}}}}	{{...}}

15. Phasing & Roadmap

In brief: {{One line — what ships first, what follows, what's "later or never".}}

Phase 1 (this document): {{the core deliverable}}
Phase 2 / stretch: {{next increment}} — pending {{Q-/DEP- refs}}
Later / if ever: {{parked ideas, and the lane they belong to}}

16. Timeline & Milestones (optional)

Milestone	Deliverable	Target date	Depends on
{{M1}}	{{...}}	{{YYYY-MM-DD}}	{{DEP-001}}

17. Traceability Matrix (optional but recommended)

Requirement	Business goal	Design ref	Test case	Status
FR-001	{{Goal 1.3}}	{{design}}	{{TC-001}}	{{Not started}}

18. Glossary & References

Glossary

Term	Definition
{{Term / acronym}}	{{plain-language meaning}}

decagondev/multi-tennant-template.md