Product Development Life Cycle
docs/pdlc/ holds the durable product context behind a repository — problems, constraints, tradeoffs, and decisions — and nothing short-lived.
- Kind
- Architecture
- Domain
- Documentation & Metadata
- Applies at
docs/pdlc/- Status
- Stable
- Source · managed
docs/pdlc/README.md
01 Defines
The repository-specific materials that fit within the Product Development Life Cycle: focused documents that explain why the repository exists and what should guide its future changes.
02 Applies when
- A repository is treated as a product whose direction needs to survive changes of people and priorities.
- Reasoning behind the repository — problems, risks, constraints, tradeoffs — would otherwise live only in conversations.
- A future change needs a principle to be measured against.
03 Boundaries
- The directory is not the PDLC framework itself, only the materials that fit within it.
- It does not replace ticketing, project management, documentation, or implementation files.
- Progress of epics, milestones, or implementation efforts is not tracked here.
Expected behaviour
- 01Documents are focused, with a clear purpose and scope — a vision, a problem statement, a high-level design.
- 02Content is durable context rather than status updates, task lists, or discussion history.
- 03The materials explain the problems being solved, the constraints respected, the tradeoffs accepted, and the principles that guide change.
Behaviour#
Most of a repository explains what and how. The PDLC directory explains why, and is written to stay true for a long time. A reader opening it should learn what the repository is for, what went wrong when it lost its way, and which constraints any change should respect — without wading through the history of how each decision was reached.
The README calls these files the cornerstone of the repository: they are the reference point other documentation, structure, and code are measured against.
Layout#
- docs/pdlc/
- README.md Owner documentation for the area Owner Documentation
- VISION.md What the system solves, and for whom
- PROBLEM.md Problem statement, symptoms, constraints
- ISSUES.md How plans are written as an issue tree Issue Plan Tree
- decisions/
- README.md When a decision record is warranted Decision Records
- TEMPLATE.md The ADR template
Durable versus short-lived#
Belongs in docs/pdlc/
- Vision and problem statements
- Constraints, risks, and accepted tradeoffs
- Guiding principles for future change
- The rare decision record structure cannot express
- Guidance on how plans are written
Belongs elsewhere
- Status updates and progress reports
- Task lists and milestone tracking
- Discussion history
- How-to and operating guides (
docs/)
Examples#
The problem statement in this repository is a good illustration of durable context. Its constraints read as principles a future change can be checked against:
## Constraints
- The repository should remain service-scoped and intentionally small.
- Reusable units should continue to be copyable and explicit rather than hidden behind magic discovery.
- Durable reasoning belongs in PDLC docs; short-lived execution tracking should stay outside committed repository files.
Connections