67 lines
4.0 KiB
Markdown
67 lines
4.0 KiB
Markdown
# Playbook 01 — Research
|
|
|
|
**Trigger.** An idea, technology or approach worth investigating before it is committed to
|
|
design. Also: an as-is document that raises a question nobody can answer.
|
|
|
|
**Who runs it.** Anyone.
|
|
|
|
**Where it lives.** A research effort lives whole in the knowledge base, the seat `knowledge-base`, reached
|
|
through the mesh MCP server from any node and any folder (ADR 0290). This repository holds none: an effort
|
|
is written with the knowledge base's verbs, never as a folder here.
|
|
|
|
## Steps
|
|
|
|
1. **Read what is known first.** `knowledge-base.ask` with the question in plain words returns the decision
|
|
records and research efforts that bear on it; `knowledge-base.get` with `kind: research` and a number
|
|
reads one effort, and `reasoning: true` (or `section` with a document's name) reads its documents.
|
|
2. **Take a number.** `knowledge-base.reserve` with `kind: research` and `for`: the effort's title. The
|
|
number comes from the issue tracker's counter and is spent whether or not the effort is ever proposed;
|
|
one never proposed is withdrawn after a week. Never pick a number by hand.
|
|
3. **Propose it.** `knowledge-base.propose` with `kind: research`, the `number` reserve gave, a one-line
|
|
`title`, `status: active`, `date` (the day it began), and `sections`: its documents in order, each a
|
|
`name` and its markdown `text`. The first is `00-overview.md`: **what** is being investigated, **why**,
|
|
and **what it touches**. Name what it touches as `links` of kind `touches` (`"0276"`, `"research 045"`,
|
|
`"issue 365"`, or a design's path), not only in prose, and what it names for another reason as `cites`.
|
|
4. **Do the research** in further documents of the same effort: notes, option analyses, evidence, draft
|
|
designs. Each change is `knowledge-base.propose` again with the effort whole and `why`, one line saying
|
|
why this version. Every version is kept; `knowledge-base.history` lists them and gives the difference
|
|
between two.
|
|
|
|
`propose` refuses an effort that breaks a rule that judges one record (an unknown status, a link to
|
|
nothing, a retired word of the glossary, a daemon's line), naming every reason at once and writing nothing.
|
|
The knowledge base then reviews the proposal itself, through a judgement that sees only the record, the
|
|
records it links and the rules; on `changes` the effort stays proposed with the findings, and its author
|
|
proposes it again. An effort that needs the operator's word is proposed with `needs-operator: true` and
|
|
waits for the operator's Approve on a channel that proves who answered.
|
|
|
|
## What makes research worth reading
|
|
|
|
State evidence, not assertion. *"Zero of 124 modules declare `brain` as a dependency"*
|
|
outranks *"the dependency rule is not followed"*. An effort that measured nothing has not
|
|
finished.
|
|
|
|
Research describes real observations but never identifies the mesh it observed. The shape of a
|
|
finding survives anonymisation intact — *a node publicly named but behind a household NAT*
|
|
carries the whole lesson without naming anything.
|
|
|
|
## Do not
|
|
|
|
- Do not put status in prose. It is the effort's `status`, and the prose must not restate it.
|
|
- Do not give a `became` link while the effort is open — playbook 02 gives it at closure.
|
|
- Do not write into `03-DESIGN` from an open effort.
|
|
- Do not write an effort, or a copy of one, into this repository: the knowledge base is the only place one
|
|
is read, and `records.py` refuses a new path under `01-RESEARCH/`.
|
|
|
|
## Closing
|
|
|
|
An effort never just stops. It closes through playbook [02](02-graduation.md) as `graduated`
|
|
or `abandoned`, always with a `became` link to what it turned into. Nothing is deleted —
|
|
what was rejected, and why, is the more expensive half to rediscover.
|
|
|
|
## How it is checked
|
|
|
|
The rules on an effort are the knowledge base's: `propose` refuses one that breaks a rule that judges one
|
|
record (the module's table test holds one case per rule), and the rules that judge the whole record set run
|
|
after every acceptance and raise a condition when one fails. That this repository holds no effort is
|
|
`records.py`'s `no-records` check, on every pull request.
|