jschoubben
c0b35652d0
papa-hq reads 01 research -> 03 decision -> 02 design. The order is a scar, not a choice: 02-DESIGN existed from its initial commit, and when adr/ was finally promoted on 2026-07-13 it took the next free number rather than its place in the sequence. By then design was too settled to renumber. hal-hq was three commits old, so it is not. adr/ becomes 02-DECISIONS and 02-DESIGN becomes 03-DESIGN, and following the folder numbers now walks the process in the order it happens: research produces a decision, the decision authorises a design. 00-GENESIS becomes 00-META, matching papa's rename from the same restructure. Every path reference rewritten across documents, frontmatter, playbooks and skills. All links resolve; all 58 frontmatter blocks parse and their path fields still point at files that exist.
41 lines
2.0 KiB
Markdown
41 lines
2.0 KiB
Markdown
---
|
|
name: hal-diagnose
|
|
description: Use when investigating an open hal-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`](../../../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
|
|
`hal-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.
|