novox/hq
8
0
Fork 0
Code Issues Pull Requests 2 Releases Wiki Activity

Make playbooks 01, 02 and 04 one cycle from idea to delivered milestones

Browse Source 
The operator found 04 odd on 2026-10-15: it went from a settled design straight to building,
with no work breakdown, and contradicted playbook 07 on pull requests. 01 now starts from the
operator's idea with setup questions, findings and a direction the operator confirms; 02
graduates that direction into one record per reversible choice and hands the design on; 04
breaks it into milestones usable on their own, one issue per repository part, each milestone
one feature step of 07. 01 notes the knowledge base's insight-only rule for an active effort
until issue 844 is delivered.
This commit is contained in:
jschoubben
2026-10-15 21:18:15 +02:00
parent 5ff97ec3aa
commit 0d66edb24c
4 changed files with 142 additions and 69 deletions
Download Patch File Download Diff File Expand all files Collapse all files
00-META/process/00-overview.md
+3 -3
View File
@@ -50,10 +50,10 @@ the expensive half.
| # | Playbook | Trigger | | # | Playbook | Trigger |
|---|---|---| |---|---|---|
| [01](01-research.md) | Research | An idea worth investigating before committing to design | | [01](01-research.md) | Research | An idea from the operator, or one worth investigating before committing to design: setup questions, findings, a direction the operator confirms |
| [02](02-graduation.md) | Graduation & design change | Research concludes, or a design must change | | [02](02-graduation.md) | Graduation & design change | Research concludes (its direction confirmed), or a design must change: decision records, the to-be design |
| [03](03-issues.md) | Issues | Something is wrong — often with the owner unknown | | [03](03-issues.md) | Issues | Something is wrong — often with the owner unknown |
| [04](04-build-handoff.md) | Build handoff | A design is ready to be built | | [04](04-build-handoff.md) | Work breakdown and handoff | A design is ready to be built: milestones usable on their own, issues per repository, each milestone one feature step |
| [05](05-constitution-sync.md) | Constitution sync | `how-we-build.md` changed a rule the mesh enforces | | [05](05-constitution-sync.md) | Constitution sync | `how-we-build.md` changed a rule the mesh enforces |
| [06](06-writing-a-module.md) | Writing a module | Something that runs today must run on the mesh | | [06](06-writing-a-module.md) | Writing a module | Something that runs today must run on the mesh |
| [07](07-feature-branches.md) | Features | Work that changes code across issues or repositories: prepared context, local development, one review, one check, one delivery | | [07](07-feature-branches.md) | Features | Work that changes code across issues or repositories: prepared context, local development, one review, one check, one delivery |
00-META/process/01-research.md
+75 -38
View File
@@ -1,66 +1,103 @@
# Playbook 01 — Research # Playbook 01 — Research
**Trigger.** An idea, technology or approach worth investigating before it is committed to **Trigger.** An idea the operator expresses, or an idea, technology or approach worth investigating before
design. Also: an as-is document that raises a question nobody can answer. 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. **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 **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: an effort through the mesh MCP server from any node and any folder (ADR 0290). This repository holds none.
is written with the knowledge base's verbs, never as a folder here.
## 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 ## Steps
1. **Read what is known first.** `knowledge-base.ask` with the question in plain words returns the decision 1. **Read what is known.** `knowledge-base.ask` with the idea in plain words returns the decision records and
records and research efforts that bear on it; `knowledge-base.get` with `kind: research` and a number research efforts that bear on it; `knowledge-base.get` reads one (`reasoning: true`, or `section`, for its
reads one effort, and `reasoning: true` (or `section` with a document's name) reads its documents. documents). Read the issue tracker for open issues in the same area (`issue-tracker.list`).
2. **Take a number.** `knowledge-base.reserve` with `kind: research` and `for`: the effort's title. The 2. **Ask the operator to set it up.** A few questions, one at a time, each answerable with a choice and
number comes from the issue tracker's counter and is spent whether or not the effort is ever proposed; carrying a recommendation: what comes first, what is out of scope, which options must be tried, what
one never proposed is withdrawn after a week. Never pick a number by hand. done looks like. Three to five questions is usual; the answers are the effort's first findings.
3. **Propose it.** `knowledge-base.propose` with `kind: research`, the `number` reserve gave, a one-line 3. **Take a number.** `knowledge-base.reserve` with `kind: research` and `for`: the effort's title. The number
`title`, `status: active`, `date` (the day it began), and `sections`: its documents in order, each a is spent whether or not the effort is ever proposed; never pick one by hand.
`name` and its markdown `text`. The first is `00-overview.md`: **what** is being investigated, **why**, 4. **Propose it.** `knowledge-base.propose` with `kind: research`, the `number`, a one-line `title`,
and **what it touches**. Name what it touches as `links` of kind `touches` (`"0276"`, `"research 045"`, `status: active`, `date` (the day it began), and `sections`, each a `name` and its markdown `text`:
`"issue 365"`, or a design's path), not only in prose, and what it names for another reason as `cites`. - `00-overview.md`: the idea in the operator's words, what exists, the operator's answers (dated), and the
4. **Do the research** in further documents of the same effort: notes, option analyses, evidence, draft words the effort uses that the glossary lacks, each defined in one line;
designs. Each change is `knowledge-base.propose` again with the effort whole and `why`, one line saying - `01-questions.md`: the questions to answer, the first ones first;
why this version. Every version is kept; `knowledge-base.history` lists them and gives the difference - `02-method.md`: what will be tried and measured, and on what.
between two.
`propose` refuses an effort that breaks a rule that judges one record (an unknown status, a link to Name what it touches as `links` of kind `touches` (`"0276"`, `"research 045"`, `"issue 365"`, or a
nothing, a retired word of the glossary, a daemon's line), naming every reason at once and writing nothing. design's path), and what it names for another reason as `cites`.
The knowledge base then reviews the proposal itself, through a judgement that sees only the record, the 5. **Do the research.** Try, measure and read, smallest question first. Each finding goes into
records it links and the rules; on `changes` the effort stays proposed with the findings, and its author `04-findings.md`: what was tried, what it showed (with numbers), what it means. Each change of the effort
proposes it again. An effort that needs the operator's word is proposed with `needs-operator: true` and is `knowledge-base.propose` again, whole, with `why`. Until issue 844 is delivered, the knowledge base
waits for the operator's Approve on a channel that proves who answered. 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 ## What makes research worth reading
State evidence, not assertion. *"Zero of 124 modules declare `brain` as a dependency"* State evidence, not assertion. *"Zero of 124 modules declare `brain` as a dependency"* outranks *"the
outranks *"the dependency rule is not followed"*. An effort that measured nothing has not dependency rule is not followed"*. An effort that measured nothing has not finished.
finished.
Research describes real observations but never identifies the mesh it observed. The shape of a Research describes real observations but never identifies the mesh it observed. The shape of a finding
finding survives anonymisation intact — *a node publicly named but behind a household NAT* survives anonymisation intact — *a node publicly named but behind a household NAT* carries the whole
carries the whole lesson without naming anything. 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
- Do not put status in prose. It is the effort's `status`, and the prose must not restate it. - 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 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 into `03-DESIGN` from an open effort.
- Do not write an effort, or a copy of one, into this repository: the knowledge base is the only place one - Do not write an effort, or a copy of one, into this repository: `records.py` refuses a new path under
is read, and `records.py` refuses a new path under `01-RESEARCH/`. `01-RESEARCH/`.
## Closing ## Closing
An effort never just stops. It closes through playbook [02](02-graduation.md) as `graduated` An effort never just stops. It closes through playbook [02](02-graduation.md) as `graduated` or
or `abandoned`, always with a `became` link to what it turned into. Nothing is deleted — `abandoned`, always with a `became` link to what it turned into. Nothing is deleted — what was rejected,
what was rejected, and why, is the more expensive half to rediscover. and why, is the more expensive half to rediscover.
## How it is checked ## How it is checked
The rules on an effort are the knowledge base's: `propose` refuses one that breaks a rule that judges one 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 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 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. `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.
00-META/process/02-graduation.md
+11 -3
View File
@@ -13,11 +13,16 @@ clauses in force for a topic or a record).
## Graduating research ## Graduating research
The effort's `05-direction.md`, confirmed by the operator (playbook [01](01-research.md), step 6), is what
graduates. The lead writes the records and the design on the larger model; it is one sitting, bounded at
about an hour, and said to the operator if it runs past.
1. **Check it against GENESIS.** An effort graduates only if its conclusion is traceable to 1. **Check it against GENESIS.** An effort graduates only if its conclusion is traceable to
[`mission.md`](../mission.md), [`context.md`](../context.md) and [`mission.md`](../mission.md), [`context.md`](../context.md) and
[`effect.md`](../effect.md). If it conflicts, either the effort is wrong or GENESIS is — [`effect.md`](../effect.md). If it conflicts, either the effort is wrong or GENESIS is —
say which, in writing, before proceeding. say which, in writing, before proceeding.
2. **Record the decision** (below, *Writing a decision record*). 2. **Record the decisions** (below, *Writing a decision record*): one record per choice that could be
reversed on its own, not one record for the whole effort.
3. **Write the design.** Create the document under `03-DESIGN/01-to-be/` with frontmatter: 3. **Write the design.** Create the document under `03-DESIGN/01-to-be/` with frontmatter:
```yaml ```yaml
@@ -31,7 +36,9 @@ clauses in force for a topic or a record).
--- ---
``` ```
4. **Close the effort.** `knowledge-base.propose` the effort again, whole, with `status: graduated` and a 4. **Hand it to the work breakdown.** The design goes on through playbook [04](04-build-handoff.md):
milestones, issues, and each milestone built as one feature step (playbook [07](07-feature-branches.md)).
5. **Close the effort.** `knowledge-base.propose` the effort again, whole, with `status: graduated` and a
`became` link to the decision record (`"NNNN"`) and to the design document (its path). An effort that `became` link to the decision record (`"NNNN"`) and to the design document (its path). An effort that
stops without a decision is proposed with `status: abandoned` and a `became` link to what replaced it. stops without a decision is proposed with `status: abandoned` and a `became` link to what replaced it.
@@ -66,7 +73,8 @@ clauses in force for a topic or a record).
superseded record cited alone, an unknown topic, a retired word of the glossary, a daemon's line, a superseded record cited alone, an unknown topic, a retired word of the glossary, a daemon's line, a
deferral no issue tracks. The knowledge base then reviews the proposal itself, through a judgement that deferral no issue tracks. The knowledge base then reviews the proposal itself, through a judgement that
sees only the record, the records it links and the rules, and answers `approve` or `changes`. On sees only the record, the records it links and the rules, and answers `approve` or `changes`. On
`changes` the record stays proposed with the findings: revise it by proposing it again, whole, with `why`. `changes` the record stays proposed with the findings: revise it by proposing it again, whole, with `why`;
at most three rounds, then the findings go to the operator with a recommendation.
On `approve` it is accepted, or, when it says `needs-operator`, it waits for the operator's Approve on a On `approve` it is accepted, or, when it says `needs-operator`, it waits for the operator's Approve on a
channel that proves who answered. Nothing proposed is in force. `knowledge-base.get` shows a record's channel that proves who answered. Nothing proposed is in force. `knowledge-base.get` shows a record's
reviews and the operator's ask when it waits for one. reviews and the operator's ask when it waits for one.
00-META/process/04-build-handoff.md
+53 -25
View File
@@ -1,35 +1,63 @@
# Playbook 04 — Build handoff # Playbook 04 — Work breakdown and handoff
**Trigger.** A to-be design is settled and work is about to start in a code repository. **Trigger.** A to-be design is settled (playbook [02](02-graduation.md)) and its building is about to start.
**Who runs it.** Whoever starts the build. **Who runs it.** The lead who will run the feature, on the larger model. It is one sitting, bounded at about
an hour, and said to the operator if it runs past.
## What it produces
A design becomes **milestones**, and each milestone becomes **issues**:
- **A milestone is usable on its own.** Once its delivery plan is done, the operator or the mesh can do
something new, said in one sentence ("a Claude Code session is mirrored into a thread on the bus").
A milestone that changes nothing anyone can use is not a milestone; fold it into the next.
- **A milestone is one feature step** of playbook [07](07-feature-branches.md): prepared, developed in one to
two hours, reviewed, checked and delivered as one. A milestone larger than that is split.
- **An issue is one repository's part of a milestone,** sized so a fixing agent finishes it inside the
milestone's development time. Issues that must land in order are linked `depends-on`.
## Steps ## Steps
1. **Confirm the design is settled.** Its frontmatter reads `status: designed`, and every 1. **Confirm the design is settled.** Its frontmatter reads `status: designed`, and every claim in it traces
claim in it traces to a decision record in the knowledge base (`knowledge-base.get` for each entry of to a decision record in the knowledge base (`knowledge-base.get` for each entry of its `decisions:`). An
its `decisions:`). An open question in the text is a open question in the text is a reason to go back to playbook [01](01-research.md), not to build around it.
reason to run playbook [01](01-research.md), not to start building around it. 2. **Name the owners.** Set `code:` in the design's frontmatter to the repositories from
2. **Name the owner.** Set `code:` in the design's frontmatter to the repositories from [`repos.md`](../repos.md). A repository that does not exist yet is added to `repos.md` in the same change.
[`repos.md`](../repos.md). If the repository does not exist yet, add it to `repos.md` in 3. **Check the as-is.** Read the matching `03-DESIGN/00-as-is/` document. What is being replaced is stated
the same change. there; if it is not, write it before changing it. Building against an undocumented as-is is how a shipped
3. **Check the as-is.** Read the matching `03-DESIGN/00-as-is/` document. What is being behaviour gets lost.
replaced is stated there; if it is not, write it before changing it. Building against an 4. **Break it into milestones.** Write them into the design, in a section *Milestones*: for each, its number,
undocumented as-is is how a shipped behaviour gets lost. its one-sentence outcome, the repositories it touches, and what it depends on. Order them so each is
4. **Flip the status.** `status: in-progress`, `updated:` today. usable as soon as it is delivered, the smallest useful one first.
5. **Build in the code repository.** HQ is not a code repository and never carries 5. **Open the issues.** For each milestone, `issue-tracker.open` one issue per repository part, its title the
implementation. symptom or capability in plain words, its report naming the design, the milestone and the decisions it
6. **On completion**, run the "when something ships" section of playbook builds with; link the order with `depends-on`. Write the issue numbers into the milestone's entry in the
design.
6. **Ask the operator to confirm the milestones**, in a short table: number, outcome, repositories, issues.
Change what they change.
7. **Flip the status.** `status: in-progress`, `updated:` today; the design change goes through playbook
[08](08-small-fixes.md) (one hq pull request).
8. **Hand each milestone to playbook 07, one at a time.** The milestone is the feature step; its issues are the
step's issues; the next milestone starts when the previous one's delivery plan is done.
9. **On completion of the last milestone**, run the "when something ships" section of playbook
[02](02-graduation.md). [02](02-graduation.md).
## Rules ## Rules
- Every merge is a human checkpoint, without exception. - What the handoff leaves for later is an issue with an owner, named in the design or the decision that leaves
- What the handoff leaves for later is an issue with an owner, named in the design or the decision that it — never a sentence saying "later". The design's `code:` names who owns what is built; the issue names who
leaves it — never a sentence saying "later". The design's `code:` names who owns what is built; the issue owns what is not. The knowledge base's rule `deferral` checks the decision record when it is proposed
names who owns what is not. the knowledge base's rule `deferral` checks the decision record when it is proposed
([issue 354](../../04-ISSUES/354-a-decided-rename-was-never-scheduled-and-the-operator-believed-it-live/00-report.md)). ([issue 354](../../04-ISSUES/354-a-decided-rename-was-never-scheduled-and-the-operator-believed-it-live/00-report.md)).
- Never open a pull request unprompted. A permissions list saying it is allowed is not a - HQ is not a code repository and never carries implementation.
request. - How the building is done — worktrees, agents, review, checks, the ready mark and the delivery — is playbook
- Work in an isolated worktree, never a shared checkout. A failed `cd` in a shared checkout 07's, not this one's.
commits to the wrong branch, and the error scrolls past.
## How it is checked
- A design in `status: in-progress` has a *Milestones* section, each milestone with its outcome and its
issues; an in-progress design without one is the smell of building without a breakdown.
- Every issue a milestone names exists in the tracker (`issue-tracker.get`), and an issue in `fixing` names
its milestone in its report.
- A milestone whose issues are all `resolved` has had its delivery plan done; its outcome sentence is proven on
the mesh before the next milestone starts.