# 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 Gitea 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

New PRDs may use a `prd-new-<kebab-title>.md` placeholder name while the
design is being drafted. Before merge, assign the next sequential number
after the highest-numbered PRD on `main`, rename the file to
`NNNN-<kebab-title>.md`, and update the title header. CI blocks merging
while any `prd-new-*.md` placeholder remains. If concurrent PRs select the
same number, the later PR must take the next available number before it
merges. Numbers are never reused; gaps are fine.

Once numbered, the filename 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 prd-new: <short title>    ← replace with the final number before merge

- **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 move off Gitea.