generated from Lerking/python-repo-template
156 lines
3.8 KiB
Markdown
156 lines
3.8 KiB
Markdown
# 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 |
|