---
name: scorpio-bug-investigate
description: Investigate a reported bug, identify likely root cause with evidence, and produce a handoff for scorpio-task-plan.
---

# Bug Analyze Investigation

Use this skill after `scorpio-bug-intake` or when a complete bug report already exists.

## Required Inputs
Read:
1. `{docs.planning}/BUG-REPORT.md` (or `BUG-REPORT-*.md`)
2. Relevant project context (`docs/PROJECT-CONTEXT.md`, architecture docs)
3. Relevant code paths and tests tied to reproduction steps

If the bug report is missing, stop and report the missing prerequisite.

## Goals
1. Reproduce or confidently reason about the failure path.
2. Isolate the most likely root cause(s) with evidence.
3. Define a minimal, safe fix approach.
4. Prepare a structured task handoff for `scorpio-task-plan`.

## Required Outputs
Write:
- `{docs.planning}/BUG-INVESTIGATION.md`
- `{docs.planning}/TASK-PLAN-HANDOFF.json`

## Investigation Report Format
`{docs.planning}/BUG-INVESTIGATION.md` should include:
- Problem summary
- Reproduction validation
- Evidence (logs, code paths, failing assertions)
- Root cause analysis
- Fix strategy options and tradeoffs
- Recommended fix plan
- Risks and regression hotspots
- Validation plan (tests/manual checks)

## Handoff Contract
Create `{docs.planning}/TASK-PLAN-HANDOFF.json` with at least:
- `version`
- `source_skill` = `scorpio-bug-investigate`
- `scope` = `bug`
- `title`
- `problem_statement`
- `constraints`
- `acceptance_targets`
- `dependencies`
- `references`
- `proposed_slices`

Use valid JSON only.

## Guardrails
- Do not implement the fix in this skill unless explicitly requested.
- Prefer evidence-backed conclusions; call out confidence level.
- If root cause is uncertain, provide top hypotheses and a shortest-path validation plan.