investigation-state

Investigation State

Wrong skill? Debugging → systematic-debugging. Getting unstuck → think-twice. Requirements analysis → requirements-validation.

Purpose: Persist debugging investigation context across sessions so no hypothesis, evidence, or eliminated approach is lost. Storage: ~/.superpowers/investigations/<uuid>.json Authoritative format: JSON. Markdown export is read-only.

Announce at start: "I'm using the investigation-state skill to track this investigation."

Companion Skills

• systematic-debugging: Step-by-step bug investigation
• adversarial-search: Confirmation bias prevention during investigation
• think-twice: When investigation hits a wall
• failure-autopsy: Post-mortem analysis

When to Use

• Starting a new multi-turn debugging session
• Resuming a previous investigation after context loss
• Handing off an investigation to another agent or session
• Checking what has already been tried ("what have we tried?")
• Saving a checkpoint before ending a session

Core Principles

1. JSON is authoritative. Markdown is a read-only export for handoff.
2. Create ~/.superpowers/investigations/ on first use if it doesn't exist.

Session Start: Stale Investigation Check

1. List *.json in ~/.superpowers/investigations/
2. Files with updated > 7 days → prompt: "Resolve, abandon, or resume?"
3. Active within 7 days → resume (one) or list for selection (multiple)

Investigation Lifecycle

States: active → paused / resolved / abandoned

• → PAUSED: Session ending or blocked. Run export manually. Record next steps via update --next-steps.
• → RESOLVED: Root cause confirmed. Create fix TODO tagged #investigation-<short-id> if needed.
• → ABANDONED: No longer relevant. Record reason.
• PAUSED → ACTIVE: Load JSON, display summary, continue from next steps.

---

Tooling

Use investigation-crud.sh for ALL investigation operations. It handles directory creation, atomic writes, UUID generation, advisory locking, backup, and schema validation.

# Core operations
investigation-crud.sh create --title "Bug title" [--observed OBS] [--expected EXP] [--reproduction REP]
investigation-crud.sh list [--status active] [--stale]
investigation-crud.sh show --id UUID
investigation-crud.sh export --id UUID

# Hypothesis tracking
investigation-crud.sh add-hypothesis --id UUID --text "Hypothesis text"
investigation-crud.sh add-evidence --id UUID --hypothesis N --source SRC --finding TEXT
investigation-crud.sh set-verdict --id UUID --hypothesis N --verdict confirmed|rejected|inconclusive [--reason TEXT]

# Lifecycle
investigation-crud.sh add-eliminated --id UUID --approach "What was tried" --reason "Why it failed"
investigation-crud.sh set-status --id UUID --status paused|resolved|abandoned [--resolution-type fix-needed] [--summary TEXT]
investigation-crud.sh update --id UUID [--next-steps "step1|step2"] [--current-theory N] [--add-ticket TST-123]

Anti-pattern: Do NOT write investigation JSON manually with heredocs, jq, or inline Python. Use investigation-crud.sh.

Starting a New Investigation

1. investigation-crud.sh create --title "Bug title" --observed "..." --expected "..." --reproduction "..."
2. Note the returned id and short_id
3. Form first hypothesis: investigation-crud.sh add-hypothesis --id UUID --text "..."
4. Begin evidence gathering

---

Hypothesis Tracking

Each hypothesis: {id, text, evidence: [{source, finding, timestamp}], verdict: null|confirmed|rejected|inconclusive, verdict_reason}

1. investigation-crud.sh add-hypothesis --id UUID --text "..." → gather evidence
2. investigation-crud.sh add-evidence --id UUID --hypothesis N --source SRC --finding TEXT
3. investigation-crud.sh set-verdict --id UUID --hypothesis N --verdict confirmed --reason "..."
4. If > 10 hypotheses: prompt for consolidation (likely scope creep)

Evidence sources: freeform strings (db:example-conn, ci:<project>, linear, local:grep, etc.)

---

Eliminated Approaches

Track approaches that were tried and failed (distinct from hypotheses):

investigation-crud.sh add-eliminated --id UUID --approach "Restarted the API service" --reason "Data still stale after restart"

This prevents future agents from retrying failed approaches.

---

Persistence

investigation-crud.sh handles all persistence automatically:

• Atomic writes (temp file + os.replace)
• Auto-updates updated timestamp on every write
• Creates ~/.superpowers/investigations/ and .gitignore on first use
• Schema: see references/schema.md

---

Concurrent Investigations

UUID-based filenames. One active → resume. Multiple active → investigation-crud.sh list --status active, agent picks one.

Markdown Export

Generate on demand for pause/handoff:

investigation-crud.sh export --id UUID

Rules: verdict: null → ACTIVE. currentTheory → ← CURRENT THEORY suffix. Generated on demand only, not auto-synced.

---

Failure Modes

Failure	Fix
Forgot to update JSON after verdict	Always write JSON immediately after each hypothesis verdict
Retried an eliminated approach	Check eliminated array before trying any approach
Lost investigation on session end	Pause with set-status --status paused, then export before ending
JSON corruption from interrupted write	Atomic write pattern (temp + mv) prevents this
Investigation scope creep (>10 hypotheses)	Prompt for consolidation — likely multiple bugs