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.
41 lines
1.9 KiB
Markdown
41 lines
1.9 KiB
Markdown
---
|
|
name: hq-diagnose
|
|
description: 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`](../../../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
|
|
|
|
1. Read `00-report.md`. Move `status:` to `diagnosing`.
|
|
2. Investigate. Write `01-diagnosis.md` in 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.
|
|
3. When the owner is known, set `status: located` and fill `located-in:` with repositories or
|
|
modules from [`00-META/repos.md`](../../../00-META/repos.md).
|
|
4. On resolution: `status: resolved`, fill `fixed-by:`. If the root cause was a design gap, run
|
|
`hq-graduate` for the amendment and fill `amended-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.
|
|
- `wontfix` is legitimate and requires a sentence saying why.
|