From 5e3b836404906de4e64920d909f94ce89ca36f98 Mon Sep 17 00:00:00 2001 From: jochen Date: Fri, 6 Nov 2026 20:51:00 +0100 Subject: [PATCH 1/2] Playbooks 01 and 02: one record per question an effort answers; design choices live in the design Research 085 graduated into eleven records where it answered two questions: the rule 'one record per choice that could be reversed on its own' made every design choice a record of its own. Claude-Session: https://claude.ai/code/session_01NcbgfFSnn24M3GcqttoU7i --- 00-META/process/01-research.md | 5 +++-- 00-META/process/02-graduation.md | 16 +++++++++++++--- 00-META/process/playbooks.html | 2 +- 3 files changed, 17 insertions(+), 6 deletions(-) diff --git a/00-META/process/01-research.md b/00-META/process/01-research.md index 3af4751e..c4c19f5a 100644 --- a/00-META/process/01-research.md +++ b/00-META/process/01-research.md @@ -83,8 +83,9 @@ An idea arrives in one of two forms, and the first step differs: decisions in those words. Asked when the idea is set up, too: an option that lands a concept in the wrong domain is offered with that cost named, like one that breaks a rule. 7. **Settle the direction with the operator.** When the questions are answered, write the section **Direction**: - 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 + the question the effort answers, the options weighed and the one proposed (a second only for a second + question of its own; playbook [02](02-graduation.md), step 2), the design choices that follow from it in a + line each, 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 review it by architectural domain (below) and diff --git a/00-META/process/02-graduation.md b/00-META/process/02-graduation.md index 46098a6b..20f63a3c 100644 --- a/00-META/process/02-graduation.md +++ b/00-META/process/02-graduation.md @@ -21,8 +21,17 @@ about an hour, and said to the operator if it runs past. [`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 decisions** (below, *Writing a decision record*): one record per choice that could be - reversed on its own, not one record for the whole effort. +2. **Record the decisions** (below, *Writing a decision record*): one record per question the effort + answers, holding that question, the options weighed and the one chosen. Most efforts answer one question + and graduate into one record; a second record is written only for a second question of its own, such as + how the change can be checked or delivered at all (the operator, 2026-11-06: research 085 graduated into + eleven records where it answered two questions). The choices made while working out the design that + follows (a field, a tool, an event, a bound, the order of steps) are the design's: written in the design + with their reasons, under the record they follow from, never as records of their own. A clause of an + earlier record the decision changes is a `changes` link from the record, with one line saying in what. + How it is checked: the lead names, in the graduation's report to the operator, the question each record + answers; an effort graduating into more than two records is said to the operator with why, before the + records are proposed. - **Write them together, not one after another.** Reserve every number first, then propose each record as soon as it is written, without waiting for the review of the one before; the reviews run side by side, and the operator's asks for the records that need them arrive together. A record that @@ -139,7 +148,8 @@ by a progressive insight. ## Amending an existing design -A design changes only through a decision. +A design changes only through a decision. A choice within what a decision decides (a field, a tool, an event, +a bound) is the design's own, written in it with its reason; it needs no record of its own. 1. Write the decision record (above). If it reverses an earlier one, it `supersedes` it. 2. Edit the to-be design document, add the record to its `decisions:` as `"ADR NNNN"`, and set `updated:` diff --git a/00-META/process/playbooks.html b/00-META/process/playbooks.html index fa4a3e22..249d69b2 100644 --- a/00-META/process/playbooks.html +++ b/00-META/process/playbooks.html @@ -424,7 +424,7 @@ const P = [ {n:"02",name:"Graduation & design change",kind:"idea",c:"--dec", trig:"A research effort concludes, or an existing design must change.", who:"The lead, on the larger model; the decision is recorded before the design moves.", - steps:["Check the conclusion against mission, context and effect.","Reserve a number per decision.","Propose one record per choice that can be reversed on its own.","Pre-check, then propose siblings together.","On changes: revise whole; after three rounds fix findings yourself.","A finding that would change what was decided: ask the operator.","needs-operator: wait for the operator's Approve.","Amend the design, or create a to-be design with status designed.","Add the decisions, updated:, and the effort's glossary words.","Review the design by architectural domain before it is merged.","Hand the design to the breakdown (04).","Close the effort: graduated with became links, or abandoned.","When it ships: write the as-is, set the to-be implemented."], + steps:["Check the conclusion against mission, context and effect.","Reserve a number per question the effort answers.","Propose one record per question: its options and the one chosen; design choices go in the design.","Pre-check, then propose siblings together.","On changes: revise whole; after three rounds fix findings yourself.","A finding that would change what was decided: ask the operator.","needs-operator: wait for the operator's Approve.","Amend the design, or create a to-be design with status designed.","Add the decisions, updated:, and the effort's glossary words.","Review the design by architectural domain before it is merged.","Hand the design to the breakdown (04).","Close the effort: graduated with became links, or abandoned.","When it ships: write the as-is, set the to-be implemented."], prod:"Decision records; a to-be design with frontmatter; glossary entries; later the as-is.", next:"04",bounds:"One sitting of about an hour", prev:["A decision rewritten silently","A deferral nothing tracks","A design amended without a decision"], -- 2.54.0 From c1cf0149b6d933f8d8f0e68ad089d01925d6060e Mon Sep 17 00:00:00 2001 From: jochen Date: Fri, 6 Nov 2026 20:52:38 +0100 Subject: [PATCH 2/2] Design writer and hq-graduate follow the new step 2; the playbook names no record by number Claude-Session: https://claude.ai/code/session_01NcbgfFSnn24M3GcqttoU7i --- .claude/agents/hq-design-writer.md | 8 +++++--- .claude/skills/hq-graduate/SKILL.md | 3 ++- 00-META/process/02-graduation.md | 2 +- 3 files changed, 8 insertions(+), 5 deletions(-) diff --git a/.claude/agents/hq-design-writer.md b/.claude/agents/hq-design-writer.md index 669a85ef..ae8686ac 100644 --- a/.claude/agents/hq-design-writer.md +++ b/.claude/agents/hq-design-writer.md @@ -14,7 +14,9 @@ there and never push. (`knowledge-base.get` with `reasoning`, and `links`), and `knowledge-base.ask` for the area in plain words: a record you did not expect may already decide a point. Read each design whole before changing it, hq's glossary (`00-META/glossary.md`) and playbook 02's steps for amending a to-be design. A clause the records do not -decide is not written into a design as if they did: say it to the caller as an open point. +decide is not written into a design as if they did. A choice within what a record decides (a field, a tool, an +event, a bound, the order of steps) is the design's own: write it in the design with its reason, under the record it +follows from (playbook 02, step 2). Only a question outside every record's question is an open point for the caller. **It reads the mesh and writes nothing there.** It calls only verbs that read (`knowledge-base.get`, `ask`, `links`, `holds`; `issue-tracker.list`, `get`); never `knowledge-base.reserve` or `propose`, nor any `issue-tracker` verb that writes (`open`, `move`, `note`, `link`). What a record or an issue must carry goes to the caller in its report. @@ -31,5 +33,5 @@ names, never node names, addresses or paths. A new word goes into the glossary w what it refuses. Commit in the imperative, about why. Report to the caller in under 30 lines: the branch and its head, each file changed with the findings it now -carries, what the tests said, and every point you left open because no record decides it, with your -recommendation. Glossary words only; a guess is said as one. +carries, what the tests said, the design's own choices you wrote, one line each, and every question you left open because it falls outside +every record's question, with your recommendation. Glossary words only; a guess is said as one. diff --git a/.claude/skills/hq-graduate/SKILL.md b/.claude/skills/hq-graduate/SKILL.md index f0db597f..52ce9bb4 100644 --- a/.claude/skills/hq-graduate/SKILL.md +++ b/.claude/skills/hq-graduate/SKILL.md @@ -32,7 +32,8 @@ written into this repository. ## Amending an existing design -A design changes only through a decision. Propose the record first; if it reverses an earlier one, +A design changes only through a decision; a choice within what a decision decides (a field, a tool, an event, a +bound) is the design's own, written in it with its reason. Propose the record first; if it reverses an earlier one, it `supersedes` it (or `changes` the clauses it replaces) — **never edit the earlier record's text**; a correction of fact is a progressive insight (`propose` the accepted record with `insight`). Then edit the design, add `"ADR NNNN"` to its `decisions:`, and set `updated:`. diff --git a/00-META/process/02-graduation.md b/00-META/process/02-graduation.md index 20f63a3c..2d1b6231 100644 --- a/00-META/process/02-graduation.md +++ b/00-META/process/02-graduation.md @@ -24,7 +24,7 @@ about an hour, and said to the operator if it runs past. 2. **Record the decisions** (below, *Writing a decision record*): one record per question the effort answers, holding that question, the options weighed and the one chosen. Most efforts answer one question and graduate into one record; a second record is written only for a second question of its own, such as - how the change can be checked or delivered at all (the operator, 2026-11-06: research 085 graduated into + how the change can be checked or delivered at all (the operator, 2026-11-06: an effort graduated into eleven records where it answered two questions). The choices made while working out the design that follows (a field, a tool, an event, a bound, the order of steps) are the design's: written in the design with their reasons, under the record they follow from, never as records of their own. A clause of an -- 2.54.0