# 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. 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. 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, what is left open. Ask the operator to confirm or change it, one point at a time. 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. 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.