hq/00-META/process/01-research.md

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 cites ("0276", "research 045", "issue 365", or a design's path), not only in prose.
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 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.