boocode/data/skills/booskills/boo-investigating-failures/SKILL.md

name, description, metadata

name	description	metadata
boo-investigating-failures	Diagnoses a runtime failure, bug, regression, or unexpected behavior and produces a root-cause finding with a proposed fix, validated adversarially. Use when something is broken, erroring, flaky, or behaving wrong, including "why is this failing," "this worked yesterday," stack traces, and log excerpts. Do NOT use for reviewing proposed changes; use boo-reviewing-code. Do NOT use for general codebase questions; use boo-mapping-project-context.	version 1.0

Investigating Failures

Size

Classify small/medium/large from number of symptoms, subsystems involved, and whether the failure spans integration boundaries. Default: small (single symptom, single layer). Announce with one-line justification. Accept $size override.

Process

1. Reproduce or characterize the failure first. Record the exact command, observed vs expected output, and any logs or stack traces.
2. If the boocontext MCP tools are available, run boocontext_explore with the failure description to locate relevant code citations cheaply (routes, schemas, components, libs, middleware, events, hot files). Then run boocontext_callgraph on the failing function/symbol to get callers and callees. Pass these citations to the investigators. Skip when the tools are absent; the investigators work from direct reads.
3. Dispatch evidence-based-investigator to gather concrete evidence (E# items with file:line).
4. If the symptom suggests concurrency issues (races, deadlocks, async errors), dispatch concurrency-analyst.
5. If the symptom suggests logic divergence or data flow issues, dispatch behavioral-analyst.
6. Based on the evidence, form a root-cause statement and propose a fix as a described change (never applied).
7. Dispatch adversarial-validator against the evidence summary and proposed fix. Produce V# validation findings.
8. Produce the final report. Do not apply the fix.

What NOT to do

• Do not apply the fix yourself. The fix goes to boo-implementing-changes or a direct dispatch.
• Do not conclude root cause from a single web source. Web claims need corroboration.
• A passing test is not evidence the bug is absent. Tests prove only the paths they cover.

Gotchas

• Evidence rule: codebase citations (file:line) stand alone. Web claims need corroboration or a single-source flag. No evidence means defer with reopen trigger.
• Sizing: default is small. Escalate only on concrete signals - symptom count, subsystem span, integration involvement.

• Subagent visibility: when the Paseo MCP tools (mcp__paseo__*) are available, spawn each agent persona as an attached Paseo subagent with create_agent (detached: false, notifyOnFinish: true; for an opencode provider also pass settings.modeId: "build" and settings.features.auto_accept: true) so every persona appears in the operator's Paseo agent track. Resolve each persona's provider/model from the active preset's agents map in ~/.paseo/orchestration-preferences.json; supervise on the finish notification (never poll) and read each result with get_agent_activity.
• Subagent fallback: when the Paseo MCP tools are not available, use the platform's native subagent dispatch. On a platform with no subagent dispatch at all (for example Pi), read each agents/<name>.md persona and apply its lens in sequential passes.
• Subagent concurrency: honor the active preset's concurrency value in ~/.paseo/orchestration-preferences.json. When it is 1 (local heavy-weight presets, around 27b/35b or larger on a single llama-swap server), dispatch subagents STRICTLY ONE AT A TIME: launch one, wait for its finish notification and read its result, then launch the next. This overrides any parallel fan-out. Absent or higher concurrency means parallel fan-out is fine.

• No commit: never commit, push, or stage changes; never git add -A. Prove any edits with git diff --stat.
• No em dashes: never use em dashes (U+2014) in output or files you write.

• Recon before write: gather evidence before forming conclusions.
• boocontext is optional: the MCP tools are not on every machine or harness. Probe, use when present, fall back to direct reads when absent. A boocontext_* tool returning UNSAFE or empty means fall back, not stop.

Output format

# Investigation: <failure description>

## Reproduction
<exact command, observed vs expected>

## Evidence

**E1: <title>**
- **Source:** `file:line`
- **Finding:** <verbatim snippet>
- **Relevance:** <connection to issue>

## Root Cause
<statement>

## Proposed Fix
<described change, not applied>

## Validation Findings

**V1: <title>**
- **Strategy:** Challenge the Evidence | Challenge the Fix | Challenge the Assumptions
- **Result:** Confirmed | Refuted | Partially Refuted
- **Impact:** <what needs to change>

## Claims I did not verify
- <anything assumed or not checked>

Failure modes

• Irreproducible failure: symptoms cannot be reliably triggered. Report what is known, note the limitation, and stop.
• Ambiguous symptoms: multiple possible root causes, no evidence to disambiguate. List all hypotheses with evidence for each.
• No codebase access: cannot read the code. Report and stop.