jschoubben
87f4f29cc6
ADR 0027 — the product is Novox Mesh, shortened to mesh internally. HAL was never chosen: it arrived with the dotfiles repository this grew out of, it is borrowed, and it is borrowed from the canonical untrustworthy machine intelligence, which is an odd flag for infrastructure trusted with credentials. Timing is the substance of the decision, not an aside — the skeleton is not built, so renaming costs a search and replace now and a migration later. Nox is an identity of Novox, and specifically the agent of the MESH rather than of a node. Nodes keep their own identities. Nox addresses them, and a human mostly talks to Nox — which makes it the concrete form of the mission's vision: state an intent, and the mesh works out which node holds the thing. It holds no private channel. The gap this opens is recorded: ADR 0012 binds every agent to a home node, and a mesh-scoped agent has none, so the model needs extending. ADR 0028 — HQ is company-scoped, novox/hq, with the mesh as its first product. Checked rather than assumed: the company organisation already holds live projects that the mesh builds and deploys, so they are tenants rather than peers, and the mesh is the ground they stand on. There is also company work outside the mesh already, which strengthens the case and means the eventual split is closer than "some day" — so each document's scope is fixed now, in a table, making that split mechanical instead of archaeological. The folders are deliberately not restructured yet. The skeleton takes the new vocabulary: mesh-host, mesh-substrate, mesh-control, mesh-surfaces, mesh-catalog. Substrate drops to four services now that identity is a hosted workload rather than a dependency. Research 009 opens the migration, with the reframing that lowers its risk: replace the control plane, do not move the workloads. Their data never moves, so it is re-declared rather than adopted — which keeps adoption out of scope, as the lab design requires. Self-hosting is the last phase, or a failed cutover takes away the means to fix it.
1.9 KiB
1.9 KiB
name, description
| name | description |
|---|---|
| hal-diagnose | Use when investigating an open HQ issue — finding which component owns a symptom, and why. Triggers on "diagnose issue N", "where does this live", "who owns this bug", "why does this happen". |
hal-diagnose
Investigates an open issue to the point where its owner is known. Authoritative playbook:
00-META/process/03-issues.md.
Before forming a hypothesis
Search the operational memory for the literal symptom text. Not after a hypothesis fails — before forming one. The knowledge base is indexed on symptoms, and the entry needed is usually titled after the error being stared at.
This fires hardest on familiar ground, where a confident trail feels like progress. Two entries have been rediscovered from scratch over several hours in one session because the search was skipped. Both were already written down.
If the search returns nothing and the problem is then solved, write the finding back. An empty result is not "nothing to learn" — it is the reason the next person repeats the work.
Steps
- Read
00-report.md. Movestatus:todiagnosing. - Investigate. Write
01-diagnosis.mdin the same folder: the trail, dated, including what was ruled out and how. Archaeology — which commit, which pull request, which date a behaviour changed — is the most valuable content here. - When the owner is known, set
status: locatedand filllocated-in:with repositories or modules from00-META/repos.md. - On resolution:
status: resolved, fillfixed-by:. If the root cause was a design gap, runhal-graduatefor the amendment and fillamended-design:.
Rules
- State evidence, not assertion. A date and a reference outrank a conclusion.
- Record what was ruled out. The next person needs to know where not to look.
- Closed issues are never deleted.
wontfixis legitimate and requires a sentence saying why.