bug
Find the root cause of a reported error or failure. Use when the user wants a diagnosis; read-only, does not fix.
SKILL.mdhome-manager/ai-tools/ai-prompts/commands/bug/SKILL.md
GitHubDiagnose a reported failure without fixing it. Files and memories are read-only.
Establish the subject
Load investigation-patterns; add fact-check only for external contracts. Read task-matching memories, not an unrelated index sweep.
Before explaining source behavior, identify what actually ran: loaded module or binary path, daemon/build identity, and relevant timestamp or hash. Compare it with the current source/build, including caches, install prefixes, and containers. If they differ, stop and report the mismatch. A burst of failures after a small change is reason to inspect the harness before blaming the code.
Separate the observed symptom site from the proposed cause. Logs establish what occurred; source establishes what can occur. Classify syntax, runtime, logic, or configuration failure, and record the before/during/after timeline and whether the symptom is deterministic or conditional.
Trace
- Read the failing path, its dependencies/imports, effective configuration, and relevant recent diff. Follow registration before assigning a call site a production role. Prefer a generator over stale generated documentation.
- Keep small investigations local. Delegate independent mechanism/hypothesis analysis, recurrence searches, or timeline/dependency tracing only when substantial. Every assignment is read-only.
- Check external contracts against vendored source or version-matched official documentation. A remembered API contract is not evidence.
- Reproduce with the smallest relevant probe. Distinguish a subject failure from a broken reproduction or unresolved setup. A failure before the target starts says nothing about its behavior; a changed error is not itself progress.
- Narrow for at most three iterations. If the boundary remains unstable, repeat an identical probe once, state what was ruled out and the remaining directions, and stop.
Conclude
Connect symptom → mechanism → cause, with a citation and evidence tier for every link. An unsupported link remains a hypothesis. Call it a root cause only when observed reproduction, logs, or an end-to-end source trace establishes the chain.
Search the identified mechanism's recurrence scope and name every matching location; state exclusions. Resolve conflicting reports through the underlying evidence, not votes.
Return output_contract with:
- Subject: artifact identity, source match, and harness-side versus code-side evidence.
- Diagnosis: immediate cause, underlying cause, triggering conditions, and affected callers or other sites.
- Fix scope bracket: smallest sufficient change, largest justified change, constraints, and under-fix/over-fix risks.
- Recommended next action, without applying it, and the exact commands/results supporting the diagnosis.
- Remaining hypotheses and missing observations.