jschoubben
2a61c57258
Research 053's identity part took six versions and about two hours: options that broke the mesh's own rules were offered and argued back, a version was proposed after every answer, and reviews returned findings a pre-check would have caught. A lab run was planned where an in-process test answered.
129 lines
8.5 KiB
Markdown
129 lines
8.5 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.
|
|
- **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): the mesh owns the truth, few and deliberate outside
|
|
dependencies; the rules in [`how-we-build.md`](../how-we-build.md); and the operator's standing word
|
|
that everything between modules goes over the bus) is dropped, or offered only with the rule it breaks
|
|
named. A recommendation the operator has to argue back costs a round and 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.
|
|
- **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, or is one of the build's
|
|
acceptance tests (step 6); each figure is given as measured (a range, not a rounded claim); no word on a
|
|
glossary *Not:* line.
|
|
- **Try on the cheapest bed 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. The lab's beds (about 12 to 16
|
|
minutes a fresh run) are for the mesh's own code; before that code exists, a lab run tests nothing an
|
|
in-process test does not, and its bed test is written as the build's acceptance test instead. 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, 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. 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.
|