diff --git a/.claude/skills/hq-new-research/SKILL.md b/.claude/skills/hq-new-research/SKILL.md index ed6917e8..bd1e0119 100644 --- a/.claude/skills/hq-new-research/SKILL.md +++ b/.claude/skills/hq-new-research/SKILL.md @@ -21,7 +21,7 @@ All through the mesh MCP server (`mesh_describe` gives each verb's arguments). number is spent; never pick one by hand. 3. **Propose the effort.** `mesh_call knowledge-base.propose` with `kind: research`, the reserved `number`, `title`, `status: active`, `date` (today), `sections` (the documents in order, each `name` and `text`; - the first `00-overview.md`: **what** is investigated, **why**, and **what it touches**), and `links` + each named by a plain title, never as a file; the first, **Overview**: **what** is investigated, **why**, and **what it touches**), and `links` of kind `touches` for every record, effort, issue or design it touches (`cites` for one it only names). 4. **Do the research** in further documents of the same effort. Each change is `propose` again with the effort whole and `why`. A refusal names every rule broken: fix them all and propose again. On review diff --git a/00-META/process/01-research.md b/00-META/process/01-research.md index cb0a31fc..caaf8e0e 100644 --- a/00-META/process/01-research.md +++ b/00-META/process/01-research.md @@ -99,8 +99,8 @@ before a design is merged (playbook [02](02-graduation.md)), it is reviewed agai - **security**: who may call each new verb, how its grants are scoped, which credentials go or remain, what can be replaced or forged, and what enters from outside the mesh; - **seams**: where each piece of state lives on the bus, which seat, verb or event joins two parts, and any - link that is not NATS-native. Each piece of state is kept in the bus storage form that fits it (a state, a - stream, an object bucket); a form the manifest lacks is added to mesh-sdk, and the review names that change + link that is not NATS-native. Each piece of state is kept in the bus storage form that fits it (a key-value + bucket, a stream, an object store); a form the manifest lacks is added to mesh-sdk, and the review names that change and its cost (a mesh-sdk change rebuilds every module) to the operator, never folds it in silently (the operator, 2026-11-02); - **running qualities**: build capacity, speed, storage growth, and what happens while a part, the bus or the diff --git a/00-META/process/02-graduation.md b/00-META/process/02-graduation.md index 6856816c..2fef2705 100644 --- a/00-META/process/02-graduation.md +++ b/00-META/process/02-graduation.md @@ -131,7 +131,8 @@ A design changes only through a decision. 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:` - to today. + to today. Review it by aspect before it is merged (playbook [01](01-research.md#review-by-aspect)), and + rewrite its *Reviewed by aspect* section. 3. If the amendment came from an issue, give the issue the document path in the issue tracker: `amended-design` on its `issue-tracker.move` to `resolved`, or `issue-tracker.link` with kind `design` before then — never in the report's frontmatter @@ -166,7 +167,8 @@ record (its module's table test holds one case per rule), and the four rules tha changes, an accepted record extending a superseded one) run after every acceptance and raise a condition when one fails. In this repository, the records test checks that a design's `decisions:` entries and every "ADR NNNN" in the text are well formed, and that no record is written here; the index test checks the reading -order's six topics, which the knowledge base reads. The three habits of graduating step 2 (side by side, clauses +order's six topics, which the knowledge base reads. A design's *Reviewed by aspect* section is read by the +reviewer of its pull request; nothing refuses a design without it yet. The three habits of graduating step 2 (side by side, clauses from the direction, the pre-check) are the lead's, read by the reviewer; `propose` refuses a link to nothing, a deferral no issue tracks and a retired word, and the review returns a record named but not linked. The rounds are read in `knowledge-base.get` (its reviews, one per version): a question to the operator about a diff --git a/00-META/process/playbooks.html b/00-META/process/playbooks.html index cf127d93..f6d5df85 100644 --- a/00-META/process/playbooks.html +++ b/00-META/process/playbooks.html @@ -416,15 +416,15 @@ const P = [ {n:"01",name:"Research",kind:"idea",c:"--idea", trig:"An idea worth investigating before it is committed to design. A symptom is not research.", who:"The session that heard the idea leads.", - steps:["Read what is known: ask, get, the tracker's list.","Ask 3 to 5 setup questions, one at a time, each with a recommendation.","Check every option against the mission and how-we-build first.","Reserve a number (kind research), never pick one by hand.","Propose the effort: Overview, Questions, Method, sections named by title, no file references.","Research; findings in the section Findings, one version per settled set.","Try at the cheapest level that answers the question.","Write the Domains: modules, seats, glossary words added or retired.","Write the Direction: decisions, rejected options, acceptance tests.","Ask the operator to confirm the direction, one point at a time.","Review the direction by aspect: security, seams, running qualities, health, events, testing, upgrade, tools.","If the review asks changes: propose again, at most three times."], + steps:["Read what is known: ask, get, the tracker's list.","Ask 3 to 5 setup questions, one at a time, each with a recommendation.","Check every option against the mission and how-we-build first.","Reserve a number (kind research), never pick one by hand.","Propose the effort: Overview, Questions, Method, sections named by title, no file references.","Research; findings in the section Findings, one version per settled set.","Try at the cheapest level that answers the question.","Write the Domains: modules, seats, glossary words added or retired.","Write the Direction: decisions, rejected options, acceptance tests.","Ask the operator to confirm the direction, one point at a time.","Review the direction by aspect: security, seams, running qualities, health, events and logs, testing, upgrade, tools.","If the review asks changes: propose again, at most three times."], prod:"A research effort in the knowledge base, status active, every version kept. Nothing in hq.", - next:"02",bounds:"Setup 30 min · proposing 15 min · each experiment 30 min · direction 30 min · report every 10 min", + next:"02",bounds:"Setup 30 min · proposing 15 min · each experiment 30 min · direction 30 min · review by aspect 20 min · report every 10 min", prev:["Research that measured nothing","A recommendation the operator must argue back","Efforts copied into hq"], check:"propose refuses rule breaks; the knowledge base reviews; the records test on every PR."}, {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.","Review the design by aspect before it is merged.","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.","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 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 aspect 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"],