chore: snapshot main sync

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

@@ -0,0 +1,89 @@
+---
+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.