jschoubben
93a1231e00
Skills take the hq- prefix: they are HQ process workflows, not mesh workflows, and HQ is company-scoped now. hq-new-research, hq-graduate, hq-new-issue, hq-diagnose, hq-amend-design, hq-handoff, hq-sync-constitution, hq-status. Forward-looking prose becomes Novox Mesh or simply the mesh — the root README, AGENTS.md, the 00-META README, the mission's module example, and one to-be document that addressed 'someone working on HAL'. Three categories deliberately keep HAL, per ADR 0027: The monorepo is still called hal on the forge. repos.md, every code: field and every located-in: field name a repository that exists under that name, and renaming them in prose would make them false. The as-is layer and the research that measured it describe the system that runs, and that system is called HAL. 124 modules, 9 daemons, a dead containerised node — those are observations, not intentions. Records 0001-0026 are immutable. A record says what was decided when it was decided, and no record is edited for a name. Also repoints ADR 0022's link at the renamed skill — a path fix, which the immutability rule permits, not a change of meaning.
1.9 KiB
name, description
| name | description |
|---|---|
| hq-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". |
hq-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, runhq-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.