106 lines
6.4 KiB
Markdown
106 lines
6.4 KiB
Markdown
# 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.
|