jschoubben
c0b35652d0
papa-hq reads 01 research -> 03 decision -> 02 design. The order is a scar, not a choice: 02-DESIGN existed from its initial commit, and when adr/ was finally promoted on 2026-07-13 it took the next free number rather than its place in the sequence. By then design was too settled to renumber. hal-hq was three commits old, so it is not. adr/ becomes 02-DECISIONS and 02-DESIGN becomes 03-DESIGN, and following the folder numbers now walks the process in the order it happens: research produces a decision, the decision authorises a design. 00-GENESIS becomes 00-META, matching papa's rename from the same restructure. Every path reference rewritten across documents, frontmatter, playbooks and skills. All links resolve; all 58 frontmatter blocks parse and their path fields still point at files that exist.
49 lines
1.9 KiB
Markdown
49 lines
1.9 KiB
Markdown
# 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.
|
|
|
|
## Steps
|
|
|
|
1. Take the next free number: highest `01-RESEARCH/NNN-*` plus one, zero-padded to three
|
|
digits. Never skip or reuse a number.
|
|
2. Create `01-RESEARCH/NNN-descriptive-name/` and a `00-overview.md` in it carrying:
|
|
|
|
```yaml
|
|
---
|
|
status: active
|
|
initiated: YYYY-MM-DD
|
|
touches: [] # areas, subsystems or as-is design docs the effort bears on
|
|
---
|
|
```
|
|
|
|
Then a short prose summary: **what** is being investigated, **why**, and **what it
|
|
touches**.
|
|
3. Do the research in further documents in the same folder — notes, option analyses, evidence,
|
|
draft designs. Anything goes. Keep the summary in `00-overview.md` current as the effort changes
|
|
shape.
|
|
|
|
## 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 lives in `00-overview.md`'s frontmatter, and the prose must not restate it.
|
|
- Do not set `became:` while the effort is open — playbook 02 sets it at closure.
|
|
- Do not write into `03-DESIGN` from an open effort.
|
|
|
|
## Closing
|
|
|
|
An effort never just stops. It closes through playbook [02](02-graduation.md) as `graduated`
|
|
or `abandoned`, always with `became:` pointing at what it turned into. Nothing is deleted —
|
|
what was rejected, and why, is the more expensive half to rediscover.
|