docs: drop docs/INDEX.md, add PRD README with format
Remove the one-line docs/INDEX.md (its directory pointers are covered by docs/README.md's "when to write which document" table). Add docs/prds/README.md documenting the PRD naming, Status lifecycle, and section format. Repoint the AGENTS.md repository-layout list at the new READMEs and add the decisions/ dir. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
This commit is contained in:
@@ -1 +0,0 @@
|
||||
Research notes live in `research/`. Product requirement docs live in `prds/`. Decision records (ADR-lite) live in `decisions/`.
|
||||
@@ -0,0 +1,63 @@
|
||||
# Product requirement docs
|
||||
|
||||
One PRD per feature: what to build, why, and how it's scoped. The PRD
|
||||
is the durable spec — it should stand on its own without a forge issue
|
||||
thread (see [`../README.md`](../README.md) for when a PRD is the right
|
||||
document vs. a research note or a decision record).
|
||||
|
||||
## Naming and numbering
|
||||
|
||||
`NNNN-kebab-title.md`, zero-padded and sequential (`0024-…`, `0025-…`).
|
||||
Numbers are never reused; gaps are fine (there is no 0005). The number
|
||||
is assigned at creation and stays fixed for the life of the doc.
|
||||
|
||||
## Status
|
||||
|
||||
The `Status:` line near the top tracks the PRD's lifecycle:
|
||||
|
||||
- **Draft** — proposed, not yet shipped.
|
||||
- **Active** — the design has shipped to `main` and is in effect.
|
||||
- **Superseded by [PRD NNNN](…)** — replaced by a later PRD; kept for history.
|
||||
- **Retargeted by [PRD NNNN](…)** — folded into a later PRD's scope.
|
||||
|
||||
## Format
|
||||
|
||||
```markdown
|
||||
# PRD NNNN: <short title>
|
||||
|
||||
- **Status:** Draft
|
||||
- **Author:** <who>
|
||||
- **Created:** YYYY-MM-DD
|
||||
- **Issue:** #<n> # optional — convenience pointer only
|
||||
|
||||
## Summary
|
||||
One paragraph: what this builds and the pain it solves.
|
||||
|
||||
## Problem
|
||||
The current state and why it's inadequate.
|
||||
|
||||
## Goals / Success Criteria
|
||||
Bullets a reviewer can check the finished work against.
|
||||
|
||||
## Non-goals
|
||||
What this explicitly does not do — and won't, to head off scope creep.
|
||||
|
||||
## Scope
|
||||
In scope / out of scope, when the boundary needs spelling out.
|
||||
|
||||
## Design
|
||||
How it works: schema, data flow, diagrams, algorithms as needed.
|
||||
|
||||
## Implementation chunks
|
||||
Ordered, mergeable steps (optional; for multi-PR features).
|
||||
|
||||
## Open questions
|
||||
Unresolved decisions — resolve or fold into Design before shipping.
|
||||
```
|
||||
|
||||
Sections are a guide, not a straitjacket: drop the ones a given PRD
|
||||
doesn't need (a small change rarely needs Scope or Implementation
|
||||
chunks) and add others where they help (e.g. Testing strategy,
|
||||
Alternatives considered, References). Keep the rationale self-contained
|
||||
— inline the reasoning rather than linking out to an issue thread, so
|
||||
the PRD survives a forge migration.
|
||||
Reference in New Issue
Block a user