From 82f0b22caac79eafc859b5301cbfc21844fd8bb9 Mon Sep 17 00:00:00 2001 From: didericis Date: Thu, 28 May 2026 22:30:46 -0400 Subject: [PATCH] docs(research): add README describing research notes MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document what research notes are (opinionated investigations of a question/design space), their unnumbered kebab-case naming, and their loose verdict-first shape — explicitly freeform, not a template. Point the AGENTS.md research line at it. Co-Authored-By: Claude Opus 4.8 --- AGENTS.md | 2 +- docs/research/README.md | 42 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 43 insertions(+), 1 deletion(-) create mode 100644 docs/research/README.md 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.