90 lines
5.3 KiB
Markdown
90 lines
5.3 KiB
Markdown
---
|
|
name: boo-investigating-failures
|
|
description: >
|
|
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.
|
|
metadata:
|
|
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.
|
|
<!-- standing-rules:pi:start -->
|
|
- **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.
|
|
<!-- standing-rules:pi:end -->
|
|
<!-- standing-rules:core:start -->
|
|
- **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.
|
|
<!-- standing-rules:core:end -->
|
|
- **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.
|