jochen
d245df7dea
The operator approved Phase 5. Decides what the design left open: the build seat runs the merge check, the facts live in the artifact store, the merge gate composes the mesh as it is and with the change and judges only what the change adds, a replay lives where its incident is, and the controller's tests run a bus of their own at the mesh's release. A core issue now resolves only with a replay or a stated reason, checked by cycle.py.
3.6 KiB
Playbook 03 — Issues
Trigger. Something is wrong at the level of the mesh's design or governance — a rule that turns out to be unenforced, a stated behaviour that does not happen, a silent failure the design permits.
Who runs it. Anyone may open an issue. No localisation is required to report one.
What belongs here, and what does not
Belongs in 04-ISSUES |
Belongs in the knowledge base |
|---|---|
| The design permits a failure to be silent | How to fix one occurrence of it |
| A documented rule is enforced by nothing | A command that works around it |
| A stated invariant is false in practice | A node-specific quirk |
| The owning component is unknown and finding it needs the whole mesh in view | Symptom → fix, once the answer is known |
The knowledge base already holds the operational record and is indexed on symptoms. This folder is not a second copy of it. An issue here is a question HQ must answer, not an incident someone must clear.
Steps
-
Take the next free number — across
mainand every open pull request, notmainalone. Work sits on unmerged branches for days, so two people both readingmainallocate the same number; it happened twice in one hour between two machines, and the second collision reachedmainwith every check passing (issue 155).cycle.pynow refuses two records sharing a number, which catches a collision but does not prevent one. Create04-ISSUES/NNN-short-name/00-report.md:--- status: open opened: YYYY-MM-DD located-in: [] # owning repo(s)/module(s), filled by diagnosis fixed-by: # PR or commit reference, filled at resolution amended-design: # design doc path, when the root cause was a design gap ---Then the symptom as observed, in plain terms, with the evidence that it happened.
-
Investigate in
01-diagnosis.mdin the same folder — the trail, dated, including what was ruled out. Movestatus:todiagnosing, thenlocatedonce the owner is known. -
Resolve. Set
status: resolved, fillfixed-by:, and if the root cause was a design gap, run playbook 02 and fillamended-design:. A core issue — itslocated-innames the controller, the node-engine, the node tools, the SDK, or the catalogue's bus, forge or build agent — resolves withreplay:, the id of its replay in mesh-lab's replays register, proved to fail on the commit before the fix and pass on it, or withreplay-none:saying why none is possible (ADR 0237;cycle.pychecks it).
Rules
- Closed issues are never deleted — they are the mesh's symptom-to-component memory.
fixed-by:names something that will still exist: a commit or a pull request, never a branch. A branch is deleted when it merges, so a branch name there is a pointer that resolves to nothing by the time anybody follows it.- A fix that turns out to have broken something else is written back into the record that asked for it, pointing at the new issue. Somebody arriving at a record to learn why the code is the way it is must not have to already know there was a sequel.
- Renumbering a collision happens once, in the branch that lands last. Renumbering a branch whose author is still pushing only moves the race.
- An issue whose answer is a general lesson should also be written to the knowledge base, so the next person searching a symptom finds it. Both, not either.
status: wontfixis legitimate and requires a sentence saying why.