didericis
ae1531835d
We use Gitea, not an abstract forge. Reword the docs added in this branch: "forge thread" -> "Gitea thread", and the research note's generic "forge" -> "Gitea" / "hosting provider" as context demands, keeping its portability argument coherent. Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
43 lines
1.8 KiB
Markdown
43 lines
1.8 KiB
Markdown
# 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
|
|
Gitea 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.
|