docs(research): add README describing research notes
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 <noreply@anthropic.com>
This commit is contained in:
@@ -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.
|
||||
Reference in New Issue
Block a user