Diagnose

A discipline for hard bugs. Skip phases only when explicitly justified, and only with the user's consent. Pattern adapted from mattpocock/skills (skills/engineering/diagnosing-bugs/SKILL.md, upstream commit f3fc563); HQ-specific cross-references and report shape added.

When /diagnose vs /investigate

Trigger	Skill
Bug reproduces reliably; root cause unknown	/investigate (Iron Law: no fix before root cause)
Bug is intermittent / flaky / env-specific / "sometimes wrong"	/diagnose (this)
Performance regression with no signal	/diagnose
Tests pass locally, fail in CI	/diagnose (loop must run in failing env)
Code is fine, design is the problem	/architect

If /diagnose produces a clean repro and the cause is still unknown, hand off to /investigate.

Step 0 — Resolve company context

Same pattern as /investigate and /brainstorm:

1. Honour explicit [company] argument
2. Fall back to workspace/threads/handoff.json .company
3. Fall back to cwd inference via companies/manifest.yaml
4. Last resort: ask via AskUserQuestion

Load GLOSSARY-style domain glossary if the target repo has one (<repo>/GLOSSARY.md). Check ADRs in the area being touched (<repo>/docs/adr/).

Redact

This skill has you show commands, outputs and captured artifacts. Redact every secret first: write <REDACTED> in its place. Build loops against env vars (inject them with hq run or hq secrets exec), so the credential stays in the environment rather than in what you show. Captured artifacts carry auth headers: quote only the lines that carry the signal.

If the redacted output is not enough to diagnose the bug, say so and ask the user.

Phase 1 — Build a feedback loop

This is the skill. Everything else is mechanical. With a fast, deterministic, agent-runnable pass/fail signal, bisection / hypothesis-testing / instrumentation all just consume that signal. Without one, no amount of staring at code will save you.

Spend disproportionate effort here. Be aggressive. Be creative. Refuse to give up.

10 ways to construct one — try in roughly this order

#	Strategy	When it works
1	Failing test at whatever seam reaches the bug — unit, integration, e2e	Bug is in code you control with existing test infra
2	Curl / HTTP script against a running dev server	Bug is in an HTTP path
3	CLI invocation with fixture input, diffing stdout vs known-good snapshot	Bug is in a CLI / script
4	Headless browser (Playwright / Puppeteer) — drives UI, asserts on DOM/console/network	Bug is in browser behavior
5	Replay a captured trace — save a real network req / payload / event log to disk; replay through the code path in isolation	Bug requires production-shaped data
6	Throwaway harness — minimal subset of system (one service, mocked deps) exercising the bug code path with a single function call	Bug requires multiple services to manifest
7	Property / fuzz loop — run 1000 random inputs; look for the failure mode	Bug is "sometimes wrong output"
8	Bisection harness — automate "boot at state X, check, repeat" so git bisect run works	Bug appeared between two known states
9	Differential loop — same input through old-version vs new-version (or two configs); diff outputs	Bug is a regression with a known-good state
10	HITL bash script — last resort. If a human must click, drive them with a structured loop script so output still feeds back to you	All else fails

Build the right loop, the bug is 90% fixed.

Iterate on the loop itself

Treat the loop as a product. Once you have a loop, ask:

• Faster? (Cache setup, skip unrelated init, narrow test scope)
• Sharper signal? (Assert on the specific symptom, not "didn't crash")
• More deterministic? (Pin time, seed RNG, isolate filesystem, freeze network)

A 30-second flaky loop is barely better than no loop. A 2-second deterministic loop is a debugging superpower.

Non-deterministic bugs

Goal is not a clean repro but a higher reproduction rate. Loop the trigger 100×, parallelise, add stress, narrow timing windows, inject sleeps. A 50%-flake bug is debuggable; 1% is not — keep raising the rate until it's debuggable.

When you genuinely cannot build a loop

Stop and say so explicitly. List what you tried. Ask the user via AskUserQuestion for one of:

• Access to whatever environment reproduces it
• A redacted captured artifact (HAR file, log dump, core dump, screen recording with timestamps)
• Permission to add temporary production instrumentation

Do not proceed to hypothesise without a loop.

Completion criterion — a tight loop that goes red

Phase 1 is done when the loop is tight and red-capable: you can name one command — a script path, a test invocation, a curl — that you have already run at least once (show the invocation and its output, redacted), and that is:

• Red-capable — it drives the actual bug code path and asserts the user's exact symptom, so it can go red on this bug and green once fixed. Not "runs without erroring" — it must be able to catch this specific bug.
• Deterministic — same verdict every run (flaky bugs: a pinned, high reproduction rate, per above).
• Fast — seconds, not minutes.
• Agent-runnable — you can run it unattended; a human in the loop only via the structured HITL loop script (strategy #10).

If you catch yourself reading code to build a theory before this command exists, stop — jumping straight to a hypothesis is the exact failure this skill prevents. No red-capable command, no Phase 2.

Do not proceed to Phase 2 until you have a loop you believe in.

Phase 2 — Reproduce + minimise

Run the loop. Watch the bug appear.

Confirm via checklist:

• Loop produces the failure mode the user described — not a different failure that happens to be nearby. Wrong bug = wrong fix.
• Failure is reproducible across multiple runs (or, for non-deterministic bugs, at a high enough rate to debug against).
• You have captured the exact symptom (error message, wrong output, timing) so later phases can verify the fix actually addresses it.

Minimise

Once it's red, shrink the repro to the smallest scenario that still goes red. Cut inputs, callers, config, and data one at a time, re-running the loop after each cut, until every remaining element is load-bearing — removing any one of them turns the loop green. This shrinks the hypothesis space in Phase 3 (fewer moving parts left to suspect) and the minimised repro becomes the clean regression test in Phase 5.

Do not proceed until you reproduce and minimise the bug.

Phase 3 — Hypothesise

Generate 3–5 ranked, falsifiable hypotheses before testing any. Single-hypothesis generation anchors on the first plausible idea.

Each hypothesis must be falsifiable. Required format:

"If <X> is the cause, then <changing Y> will make the bug disappear / <changing Z> will make it worse."

If you cannot state the prediction, the hypothesis is a vibe — discard or sharpen it.

Show the ranked list to the user before testing via AskUserQuestion (multiSelect: true to let them flag which they want skipped or pre-empted). Domain knowledge often re-ranks instantly ("we just deployed a change to #3"), or the user has already ruled some out. Cheap checkpoint, big time saver. Don't block on it — proceed with your ranking if the user is AFK.

Phase 4 — Instrument

Each probe must map to a specific prediction from Phase 3. Change one variable at a time.

Tool preference order:

1. Debugger / REPL inspection if env supports it. One breakpoint beats ten logs.
2. Targeted logs at boundaries that distinguish hypotheses.
3. Never "log everything and grep".

Tag every debug log with a unique prefix, e.g. [DEBUG-a4f2]. Cleanup at end becomes a single grep. Untagged logs survive past cleanup; tagged logs die.

Performance branch. For perf regressions, logs are usually wrong. Establish a baseline measurement (timing harness, performance.now(), profiler, query plan), then bisect. Measure first, fix second.

Phase 5 — Fix + regression test

Write the regression test before the fix — but only if there is a correct seam for it.

A correct seam exercises the real bug pattern as it occurs at the call site. If the only available seam is too shallow (single-caller test when the bug needs multiple callers; unit test that can't replicate the chain that triggered it), a regression test there gives false confidence.

If no correct seam exists, that itself is the finding. Note it. The codebase architecture is preventing the bug from being locked down. Flag this for Phase 6 hand-off to /architect.

If a correct seam exists:

1. Turn the minimised repro into a failing test at that seam.
2. Watch it fail. If you forced the red by mutating code or a fixture, diff against a pristine copy to prove the mutation landed before you trust it.
3. Apply the fix.
4. Watch it pass.
5. Re-run the Phase 1 feedback loop against the original (un-minimised) scenario.

This is HQ Core Principle #8 ("Bugfixes require tests") — non-negotiable.

Phase 6 — Cleanup + post-mortem

Required before declaring done:

• Original repro no longer reproduces (re-run Phase 1 loop)
• Regression test passes (or absence of seam is documented + flagged)
• All [DEBUG-…] instrumentation removed (grep the prefix; git diff clean of tagged probes)
• Throwaway prototypes deleted (or moved to a clearly-marked debug location)
• The hypothesis that turned out correct is stated in the commit / PR message — so the next debugger learns

Then ask: what would have prevented this bug? If the answer involves architectural change (no good test seam, tangled callers, hidden coupling) hand off to /architect with the specifics. Make the recommendation after the fix is in, not before — you have more information now than when you started.

Output: diagnostic report

Save to workspace/reports/{slug}-diagnose.md. Sections:

# Diagnose: <title>

**Symptom:** <user-described>
**Repro rate before:** <X%> | **after loop:** <Y%>
**Loop strategy used:** <#1–10>
**Loop file path:** <path>
**Time-to-loop:** <minutes>

## Hypotheses (ranked)
1. ✅/❌ <hypothesis> — prediction: <Y>; result: <observed>
2. …

## Winning hypothesis
<one paragraph>

## Fix
<file:line refs>

## Regression test
<file:line> — or "no correct seam; flagged for /architect"

## Post-mortem
- What would have prevented this:
- Architectural smells noted:
- /architect handoff: yes/no

Cross-references

• HQ /investigate — root-cause-first companion. Use when bug reproduces reliably.
• HQ /tdd — Phase 5 regression test feeds into full red-green-refactor coverage.
• HQ /architect — Phase 6 hand-off when the absent test seam or tangled callers is the real story.
• HQ Core Principles 7 (never skip failing tests) and 8 (bugfixes require tests).
• HQ /learn — capture failure-mode patterns at end of session for cross-tenant reuse.
• Pattern source: mattpocock/skills (skills/engineering/diagnosing-bugs/SKILL.md), upstream commit f3fc563.