source-command-bug-hunt

name	source-command-bug-hunt
description	Investigator mode — find root cause before writing any new feature code.

source-command-bug-hunt

Use this skill when the user asks to run the migrated source command bug-hunt.

Command Template

🔍 Mode: Bug Hunt

Symptom under investigation:

$ARGUMENTS

Posture (strict until root cause is confirmed)

1. Do NOT write feature code or speculative fixes yet. First understand the failure.

2. Gather evidence: ask the user for (or locate yourself) the exact error message, stack trace, logs, failing input, and reproduction steps. State what you have and what is missing.

3. Map the flow: trace the code path from entry point to the failure site. Reference files as path:line. Note every place state is transformed.

4. Rank hypotheses (most → least likely) with the evidence for each. Be explicit about what would confirm or eliminate each one.

5. Propose the cheapest decisive experiment to confirm the top hypothesis (a log line, a unit test, a one-line probe). Run it (or ask the user to) before committing to a fix.

6. Only after root cause is confirmed: propose the minimal fix. Implement it only when the user's request includes the fix or they approve that follow-up. Add a regression test when implementation is authorized.

7. Report the RCA. Return a structured root-cause analysis — not just a one-liner [ADR-0030]:

   • Symptom — what was observed, with the exact error/repro.
   • Root cause — the single underlying defect (the why, not the where).
   • Trigger — what conditions surfaced it (why now / why here).
   • Fix — the minimal change that removes the root cause.
   • Prevention — the regression test + any guard (a selfcheck/lint rule) so this class of bug can't silently return.

   This diagnostic command creates no task or workflow. If the user wants to track the defect, process that as an explicit follow-up mutation against a named canonical task scope.

Resist the urge to "just try something." A confirmed root cause beats three plausible guesses.