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

# Playbook 01 — Research

**Trigger.** An idea the operator expresses, or 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. A symptom (a
bug, something broken) is not research: it follows playbook [03](03-issues.md).

**Who runs it.** Anyone; in an agent session, the session that heard the idea leads it.

**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.

## The cycle it starts

```
idea ─► research (01) ─► decisions and design (02) ─► work breakdown in milestones (04)
     ─► each milestone built and delivered as one feature step (07) ─► what is reported afterwards (03, 08)
```

An idea arrives in one of two forms, and the first step differs:

- **A new idea**, where only the mesh's own context matters: read what the knowledge base holds on it.
- **An idea for an existing application**: read that application's to-be and as-is designs, its decision
  records and its open issues first; the effort `touches` them.

## Steps

1. **Read what is known.** `knowledge-base.ask` with the idea in plain words returns the decision records and
   research efforts that bear on it; `knowledge-base.get` reads one (`reasoning: true`, or `section`, for its
   documents). Read the issue tracker for open issues in the same area (`issue-tracker.list`).
2. **Ask the operator to set it up.** A few questions, one at a time, each answerable with a choice and
   carrying a recommendation: what comes first, what is out of scope, which options must be tried, what
   done looks like. Three to five questions is usual; the answers are the effort's first findings.
   - **Check every option against the mesh's own rules before offering it.** An option that breaks one
     (the core values in [`mission.md`](../mission.md), among them *the mesh owns the truth* and
     *sovereignty: external dependencies are deliberate and few*; the rules in
     [`how-we-build.md`](../how-we-build.md); and everything between modules over the bus, research 036) is
     dropped, or offered only with the rule it breaks named. A recommendation the operator has to argue back
     costs a version.
   - **Explain each question with a concrete picture** in the operator's words: what they would see, do or
     lose under each option. No internal names (a record number, a verb, a word the glossary lacks) without
     what it is beside it.
3. **Take a number.** `knowledge-base.reserve` with `kind: research` and `for`: the effort's title. The number
   is spent whether or not the effort is ever proposed; one never proposed is withdrawn after a week. Never
   pick one by hand.
4. **Propose it.** `knowledge-base.propose` with `kind: research`, the `number`, a one-line `title`,
   `status: active`, `date` (the day it began), and `sections`, each a `name` and its markdown `text`:
   - `00-overview.md`: the idea in the operator's words, what exists, the operator's answers (dated), and the
     words the effort uses that the glossary lacks, each defined in one line;
   - `01-questions.md`: the questions to answer, the first ones first;
   - `02-method.md`: what will be tried and measured, and on what.

   Name what it touches as `links` of kind `touches` (`"0276"`, `"research 045"`, `"issue 365"`, or a
   design's path), and what it names for another reason as `cites`.
5. **Do the research.** Try, measure and read, smallest question first. Each finding goes into
   `04-findings.md`: what was tried, what it showed (with numbers), what it means. Each change of the effort
   is `knowledge-base.propose` again, whole, with `why`; every version is kept, and `knowledge-base.history`
   lists them and gives the difference between two. Until issue 844 is delivered, the knowledge base
   takes a new version of an accepted, active effort only as a progressive insight: give `insight`, saying
   what the effort held before the new finding, and mark the finding in the text with its date.
   - **Propose a version per settled set, not per answer.** While the operator answers a run of questions,
     or while experiments run, keep the answers and findings in the session's save point and propose once
     when the set is settled. Each version is reviewed and resent whole, so a version per answer multiplies
     the reviews.
   - **Pre-check before proposing**, against what the review sends back most: every record, issue or design
     the text names is in `links`; work put off names the issue that tracks it (an acceptance test is not
     put-off work: it is what the build proves, step 6); each figure is given as measured (a range, not a
     rounded claim); no word on a glossary *Not:* line.
   - **Try at the cheapest level that answers the question.** A program's own behaviour (a library, a
     server, a protocol) is tried in process, on the machine's loopback, in minutes. Lab runs (about 12 to
     16 minutes fresh) are for the mesh's own code; before that code exists, a lab run tests nothing an
     in-process test does not, and its lab scenario is written as the build's acceptance test instead.
6. **Settle the direction with the operator.** When the questions are answered, write `05-direction.md`:
   the proposed decisions in a few lines each, the options rejected and why, and the build's acceptance
   tests: what the build must prove before it is done, carried by its milestones (playbook
   [04](04-build-handoff.md)). Nothing else is left open: each question closes by a test, by a decision the
   effort records with its reason (a small design limit is the lead's), or by the operator. Ask the
   operator to confirm or change the direction, one point at a time, then propose it once. Then the effort
   graduates through playbook [02](02-graduation.md).

## Bounds and models

| Step | Bound | Model |
|---|---|---|
| reading and the setup questions (1, 2) | 30 minutes | the session's own, larger |
| proposing (3, 4) | 15 minutes | larger |
| each experiment or reading task (5) | 30 minutes | smaller, one agent at a time unless the operator allows more |
| the direction (6) | 30 minutes | larger |

A step past its bound is said to the operator at once, with what is being done about it. The lead reports
as playbook 07 does: every ten minutes and at once when something is found, stops or needs the operator,
with the allowance used.

## 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.

`propose` refuses an effort that breaks a rule that judges one record (an unknown status, a link to
nothing, a retired word, a daemon's line), naming every reason at once and writing nothing. The knowledge
base then reviews the proposal itself; on `changes` the effort stays proposed with the findings and its
author proposes it again, at most three times before the findings go to the operator with a
recommendation. 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.

## 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: `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. The habits of steps 2, 5 and 6 (options checked
against the rules, one version per settled set, the cheapest level, nothing left open) are the lead's, read by
the reviewer; of the pre-check, `propose` refuses a link to nothing and a retired word, and the review returns
a record named but not linked, an untracked deferral and a figure not as measured. That this repository holds
no effort is `records.py`'s `no-records` check, on every pull request. An active effort with no new version
for seven days is the smell of research left behind: its lead closes or continues it.