diff --git a/AGENTS.md b/AGENTS.md index 5b08b62..a329191 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -30,7 +30,7 @@ the container lifecycle and the copying of skills and env vars into it. "Intended design". - `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/research/` — research notes (see `docs/research/README.md`). - `docs/decisions/` — decision records (ADR-lite). ## Conventions diff --git a/docs/research/README.md b/docs/research/README.md new file mode 100644 index 0000000..aaa6968 --- /dev/null +++ b/docs/research/README.md @@ -0,0 +1,42 @@ +# Research notes + +Investigations into a question or a design space — landscape surveys, +tradeoff analyses, "should we do X or Y," assessments of an approach +before (or instead of) committing it to a PRD. A research note is where +the *thinking* lives; a PRD is where a decided feature lives, and a +decision record is where a settled choice lives (see +[`../README.md`](../README.md) for picking between them). + +Notes are opinionated. They reach a conclusion rather than dumping a +neutral survey — the point is to move a decision forward and leave a +durable record of why it went the way it did. + +## Naming + +`kebab-case-topic.md`, named by subject and **not** numbered (unlike +PRDs and decision records). Pick a name that says what was +investigated: `bash-vs-python-vs-go.md`, `pipelock-assessment.md`, +`issue-tracking-vs-in-repo-decision-history.md`. + +## Shape (freeform) + +There's no fixed template — use whatever structure fits the question. +In practice most notes share a loose shape: + +- **Open with the question** — a sentence or two on what's being + investigated and why it came up. +- **Lead with the verdict** — a `## Summary` near the top stating the + conclusion, so a reader gets the answer without reading the whole + thing. +- **Then the analysis** — whatever the argument needs: comparison + tables, per-option sections, failure-mode walkthroughs, the axes that + actually matter. +- **End with a recommendation** when the note exists to drive a + decision. + +Keep the reasoning self-contained and grounded: cite sources, link +files and PRDs, and prefer concrete evidence from this repo over +generic claims — a note should stand on its own without a chat log or a +forge thread. When a note's recommendation gets acted on, capture the +resulting decision in a PRD or a decision record; the note stays as the +"why we looked into it," not the system of record for the choice.