# Project Specification: <Project Name>

> **How to use this template:** Copy this file to `docs/PROJECT_SPECIFICATION.md` in your new
> project, then work through it top to bottom. Every `<placeholder>` should be replaced or
> removed. Sections marked *(optional)* can be deleted if they genuinely don't apply — don't
> delete them just because they're hard to answer. Keep this document updated as the project
> evolves; it is the single source of truth for what the project is and why.

| | |
|---|---|
| **Status** | Draft / In Review / Approved |
| **Owner** | <name> |
| **Created** | <yyyy-mm-dd> |
| **Last updated** | <yyyy-mm-dd> |
| **Version** | 0.1 |

---

## 1. Summary

A short (3–5 sentence) description of the project, written so that someone outside the
project can understand what it is and why it exists without reading further.

## 2. Problem Statement

- What problem are we solving?
- Who has this problem, and how do they experience it today?
- What happens if we do nothing?

## 3. Goals

Concrete, testable statements of what success looks like. Prefer measurable outcomes over
vague aspirations.

- [ ] Goal 1
- [ ] Goal 2
- [ ] Goal 3

## 4. Non-Goals

Explicitly out of scope. This section prevents scope creep and mismatched expectations —
it is as important as the goals section.

- Non-goal 1
- Non-goal 2

## 5. Stakeholders

| Role | Name | Interest / Responsibility |
|---|---|---|
| Sponsor | | |
| Product owner | | |
| Tech lead | | |
| End users | | |
| Other | | |

## 6. Background & Context *(optional)*

Relevant history, prior attempts, related systems, or decisions that shape this project.
Link to the [Value Stream Map](../docs/value-stream-mapping/) if one has been produced —
it often surfaces the problem this project addresses.

## 7. Scope

### 7.1 In Scope
- Item 1
- Item 2

### 7.2 Out of Scope
- Item 1
- Item 2

## 8. Requirements

### 8.1 Functional Requirements

| ID | Requirement | Priority (Must/Should/Could/Won't) |
|---|---|---|
| FR-1 | | Must |
| FR-2 | | Should |

### 8.2 Non-Functional Requirements

Consider at least: performance, scalability, security, privacy, accessibility,
reliability/availability, maintainability, observability, compliance.

| ID | Requirement | Notes |
|---|---|---|
| NFR-1 | | |
| NFR-2 | | |

## 9. Users & Use Cases *(optional)*

Describe the primary user(s)/persona(s) and the key use cases or user stories.

- As a `<user type>`, I want to `<action>`, so that `<benefit>`.

## 10. Architecture & Design

- High-level architecture (diagram, or link to one).
- Key components and their responsibilities.
- Technology choices and why they were made.
- Data model / schema, if applicable.
- External interfaces / APIs / integrations.

## 11. Constraints & Assumptions

| Type | Description |
|---|---|
| Constraint | e.g. must run on existing infrastructure, fixed deadline, budget cap |
| Assumption | e.g. third-party API will remain stable, expected data volume |

## 12. Risks

| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| | Low/Med/High | Low/Med/High | |

## 13. Milestones & Timeline

| Milestone | Target date | Notes |
|---|---|---|
| Project kickoff | | |
| Specification approved | | |
| MVP / first working version | | |
| Release | | |

## 14. Success Metrics / Acceptance Criteria

How will we know the project succeeded? Prefer measurable, falsifiable criteria over
"it works."

- [ ] Criterion 1
- [ ] Criterion 2

## 15. Open Questions

Track unresolved questions here so they don't get lost. Move resolved items to a decision
log or into the relevant section above.

| Question | Owner | Status |
|---|---|---|
| | | Open |

## 16. Glossary *(optional)*

| Term | Definition |
|---|---|
| | |

## 17. Revision History

| Version | Date | Author | Summary of changes |
|---|---|---|---|
| 0.1 | <yyyy-mm-dd> | | Initial draft |