factory/vibe/PRD

vibe > PRD

Product Requirement Documents

Status: 🟢 Active Last Updated: 2026-06-23 Related: vibe/ADR · vibe/Investigations

vibe/PRD/ holds the Product Requirement Documents that drive larger pieces of work in the lab. A PRD captures what we want and why it matters; the matching ADRs capture how we decided to build it, and investigations capture what we learned along the way.

Convention

• One subfolder per PRD, kebab-case (e.g. safe-prod-like-environment/).
• Each subfolder MUST contain:
  • README.md — the PRD hub: problem, goals/non-goals, requirements, success criteria, and a QA strategy.
  • STATUS.md — the implementation tracker. Update it whenever something ships (a PR merges, a brick lands, a milestone closes). It is the living view of "where are we" against the PRD.
• A big PRD uses tree-docs: the README.md stays a hub and detail lives in leaf pages (each with its own breadcrumb and bidirectional cross-links). A tree-sized PRD MUST detail an explicit QA strategy — how the delivered work will be verified, and what "done and safe" means.
• PRs cross-link to the PRD, and the PRD's STATUS.md cross-links back to the PRs/ADRs/investigations that realised each part. Links are bidirectional.
• No-tombstone rule applies: the PRD reads as currently true. Progress lives in STATUS.md (which is a tracker and may legitimately list shipped items), not as "previously / now" edits scattered through the hub.

Index

PRD	Hub	Status
Safe, production-like environment	safe-prod-like-environment/README.md	🟡 In design

Rules to contribute

1. Create a kebab-case subfolder named for the PRD.
2. Add README.md (the hub) and STATUS.md (the tracker). Both carry a breadcrumb first line and the leaf header blockquote (Status / Last Updated / Related).
3. In the hub, state the problem, goals and non-goals, requirements, success criteria, and the QA strategy. If the PRD is large, split detail into leaf pages and keep the README as a navigable hub.
4. Keep STATUS.md current: every time a piece ships, record it there and link the PR/ADR that delivered it.
5. Add a row to the Index table above.
6. Ensure every PR that implements part of the PRD links to the PRD, and that STATUS.md links back. Bidirectional links are mandatory.