From 044a8a3122c03de76b8f5e4a64992bbd4202cb4e Mon Sep 17 00:00:00 2001 From: didericis Date: Thu, 28 May 2026 22:26:09 -0400 Subject: [PATCH] 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 --- AGENTS.md | 7 ++--- docs/INDEX.md | 1 - docs/prds/README.md | 63 +++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 67 insertions(+), 4 deletions(-) delete mode 100644 docs/INDEX.md create mode 100644 docs/prds/README.md diff --git a/AGENTS.md b/AGENTS.md index 564a99d..5b08b62 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -28,9 +28,10 @@ the container lifecycle and the copying of skills and env vars into it. - `bot-bottle.json` — legacy manifest of named agents (env / skills / prompt per agent), consumed by `cli.py`. See "Manifest" under "Intended design". -- `docs/INDEX.md` — pointer to the research notes. -- `docs/prds/` — product requirement docs. -- `docs/research/` — research notes (empty for now, kept tracked via `.gitkeep`). +- `docs/README.md` — docs overview; when to write which document. +- `docs/prds/` — product requirement docs (see `docs/prds/README.md` for format). +- `docs/research/` — research notes. +- `docs/decisions/` — decision records (ADR-lite). ## Conventions diff --git a/docs/INDEX.md b/docs/INDEX.md deleted file mode 100644 index 5cab3dc..0000000 --- a/docs/INDEX.md +++ /dev/null @@ -1 +0,0 @@ -Research notes live in `research/`. Product requirement docs live in `prds/`. Decision records (ADR-lite) live in `decisions/`. diff --git a/docs/prds/README.md b/docs/prds/README.md new file mode 100644 index 0000000..bd8ec7f --- /dev/null +++ b/docs/prds/README.md @@ -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: + +- **Status:** Draft +- **Author:** +- **Created:** YYYY-MM-DD +- **Issue:** # # 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.