From 0d66edb24cc5dd73b590b5ac5bf3895df2e7b4a3 Mon Sep 17 00:00:00 2001 From: jochen Date: Thu, 15 Oct 2026 21:18:15 +0200 Subject: [PATCH 1/2] Make playbooks 01, 02 and 04 one cycle from idea to delivered milestones 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. --- 00-META/process/00-overview.md | 6 +- 00-META/process/01-research.md | 113 ++++++++++++++++++---------- 00-META/process/02-graduation.md | 14 +++- 00-META/process/04-build-handoff.md | 78 +++++++++++++------ 4 files changed, 142 insertions(+), 69 deletions(-) diff --git a/00-META/process/00-overview.md b/00-META/process/00-overview.md index 379725e2..ab91cac0 100644 --- a/00-META/process/00-overview.md +++ b/00-META/process/00-overview.md @@ -50,10 +50,10 @@ the expensive half. | # | Playbook | Trigger | |---|---|---| -| [01](01-research.md) | Research | An idea worth investigating before committing to design | -| [02](02-graduation.md) | Graduation & design change | Research concludes, or a design must change | +| [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 (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 | -| [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 | | [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 | diff --git a/00-META/process/01-research.md b/00-META/process/01-research.md index 6dce26d4..d3a720c4 100644 --- a/00-META/process/01-research.md +++ b/00-META/process/01-research.md @@ -1,66 +1,103 @@ # 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. +**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. +**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: an effort -is written with the knowledge base's verbs, never as a folder here. +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 first.** `knowledge-base.ask` with the question in plain words returns the decision - records and research efforts that bear on it; `knowledge-base.get` with `kind: research` and a number - reads one effort, and `reasoning: true` (or `section` with a document's name) reads its documents. -2. **Take a number.** `knowledge-base.reserve` with `kind: research` and `for`: the effort's title. The - number comes from the issue tracker's counter and is spent whether or not the effort is ever proposed; - one never proposed is withdrawn after a week. Never pick a number by hand. -3. **Propose it.** `knowledge-base.propose` with `kind: research`, the `number` reserve gave, a one-line - `title`, `status: active`, `date` (the day it began), and `sections`: its documents in order, each a - `name` and its markdown `text`. The first is `00-overview.md`: **what** is being investigated, **why**, - and **what it touches**. Name what it touches as `links` of kind `touches` (`"0276"`, `"research 045"`, - `"issue 365"`, or a design's path), not only in prose, and what it names for another reason as `cites`. -4. **Do the research** in further documents of the same effort: notes, option analyses, evidence, draft - designs. Each change is `knowledge-base.propose` again with the effort whole and `why`, one line saying - why this version. Every version is kept; `knowledge-base.history` lists them and gives the difference - between two. +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; 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. -`propose` refuses an effort that breaks a rule that judges one record (an unknown status, a link to -nothing, a retired word of the glossary, a daemon's line), naming every reason at once and writing nothing. -The knowledge base then reviews the proposal itself, through a judgement that sees only the record, the -records it links and the rules; on `changes` the effort stays proposed with the findings, and its author -proposes it again. 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. + 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`. 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. +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. +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: the knowledge base is the only place one - is read, and `records.py` refuses a new path under `01-RESEARCH/`. +- 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. +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. +`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. diff --git a/00-META/process/02-graduation.md b/00-META/process/02-graduation.md index 22a90d6f..61587959 100644 --- a/00-META/process/02-graduation.md +++ b/00-META/process/02-graduation.md @@ -13,11 +13,16 @@ clauses in force for a topic or a record). ## 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 [`mission.md`](../mission.md), [`context.md`](../context.md) and [`effect.md`](../effect.md). If it conflicts, either the effort is wrong or GENESIS is — 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: ```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 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 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 - `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 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. diff --git a/00-META/process/04-build-handoff.md b/00-META/process/04-build-handoff.md index 43e32e3c..f610301d 100644 --- a/00-META/process/04-build-handoff.md +++ b/00-META/process/04-build-handoff.md @@ -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 -1. **Confirm the design is settled.** Its frontmatter reads `status: designed`, and every - claim in it traces to a decision record in the knowledge base (`knowledge-base.get` for each entry of - its `decisions:`). An open question in the text is a - reason to run playbook [01](01-research.md), not to start building around it. -2. **Name the owner.** Set `code:` in the design's frontmatter to the repositories from - [`repos.md`](../repos.md). If the repository does not exist yet, add it to `repos.md` in - the same change. -3. **Check the as-is.** Read the matching `03-DESIGN/00-as-is/` document. What is being - replaced is stated there; if it is not, write it before changing it. Building against an - undocumented as-is is how a shipped behaviour gets lost. -4. **Flip the status.** `status: in-progress`, `updated:` today. -5. **Build in the code repository.** HQ is not a code repository and never carries - implementation. -6. **On completion**, run the "when something ships" section of playbook +1. **Confirm the design is settled.** Its frontmatter reads `status: designed`, and every claim in it traces + to a decision record in the knowledge base (`knowledge-base.get` for each entry of its `decisions:`). An + open question in the text is a reason to go back to playbook [01](01-research.md), not to build around it. +2. **Name the owners.** 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. +3. **Check the as-is.** Read the matching `03-DESIGN/00-as-is/` document. What is being replaced is stated + there; if it is not, write it before changing it. Building against an undocumented as-is is how a shipped + behaviour gets lost. +4. **Break it into milestones.** Write them into the design, in a section *Milestones*: for each, its number, + its one-sentence outcome, the repositories it touches, and what it depends on. Order them so each is + usable as soon as it is delivered, the smallest useful one first. +5. **Open the issues.** For each milestone, `issue-tracker.open` one issue per repository part, its title the + symptom or capability in plain words, its report naming the design, the milestone and the decisions it + 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). ## 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 it — never a sentence saying "later". The design's `code:` names who owns what is built; the issue - names who owns what is not. the knowledge base's rule `deferral` checks the decision record when it is proposed +- What the handoff leaves for later is an issue with an owner, named in the design or the decision that leaves + it — never a sentence saying "later". The design's `code:` names who owns what is built; the issue 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)). -- Never open a pull request unprompted. A permissions list saying it is allowed is not a - request. -- Work in an isolated worktree, never a shared checkout. A failed `cd` in a shared checkout - commits to the wrong branch, and the error scrolls past. +- HQ is not a code repository and never carries implementation. +- How the building is done — worktrees, agents, review, checks, the ready mark and the delivery — is playbook + 07's, not this one's. + +## 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. -- 2.54.0 From 99243ec47efadda30c6495252c260dfba430e197 Mon Sep 17 00:00:00 2001 From: jochen Date: Thu, 15 Oct 2026 21:19:01 +0200 Subject: [PATCH 2/2] Confirm milestones before opening their issues, name issue 845 for the check, keep 01's withdrawal and history lines --- 00-META/process/01-research.md | 6 ++++-- 00-META/process/04-build-handoff.md | 14 ++++++++------ 2 files changed, 12 insertions(+), 8 deletions(-) diff --git a/00-META/process/01-research.md b/00-META/process/01-research.md index d3a720c4..a4118093 100644 --- a/00-META/process/01-research.md +++ b/00-META/process/01-research.md @@ -31,7 +31,8 @@ An idea arrives in one of two forms, and the first step differs: 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; never pick one by hand. + 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 @@ -43,7 +44,8 @@ An idea arrives in one of two forms, and the first step differs: 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`. Until issue 844 is delivered, the knowledge base + 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`: diff --git a/00-META/process/04-build-handoff.md b/00-META/process/04-build-handoff.md index f610301d..40eff9cb 100644 --- a/00-META/process/04-build-handoff.md +++ b/00-META/process/04-build-handoff.md @@ -30,12 +30,12 @@ A design becomes **milestones**, and each milestone becomes **issues**: 4. **Break it into milestones.** Write them into the design, in a section *Milestones*: for each, its number, its one-sentence outcome, the repositories it touches, and what it depends on. Order them so each is usable as soon as it is delivered, the smallest useful one first. -5. **Open the issues.** For each milestone, `issue-tracker.open` one issue per repository part, its title the - symptom or capability in plain words, its report naming the design, the milestone and the decisions it - 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. +5. **Ask the operator to confirm the milestones**, in a short table: number, outcome, repositories, the + parts each repository builds. Change what they change. +6. **Open the issues.** For each confirmed milestone, `issue-tracker.open` one issue per repository part, its + title the symptom or capability in plain words, its report naming the design, the milestone and the + decisions it builds with; link the order with `depends-on`. Write the issue numbers into the milestone's + entry in the design. 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 @@ -55,6 +55,8 @@ A design becomes **milestones**, and each milestone becomes **issues**: ## How it is checked +Read by the lead and the reviewer today; a check in hq's merge-check is tracked by issue 845. + - 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 -- 2.54.0