From superpowers-plus
Persists debugging investigation context (hypotheses, evidence, eliminated approaches) across sessions for multi-turn debugging. Start, resume, or hand off investigations.
How this skill is triggered — by the user, by Claude, or both
Slash command
/superpowers-plus:investigation-stateThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
> **Wrong skill?** Debugging → `systematic-debugging`. Getting unstuck → `think-twice`. Requirements analysis → `requirements-validation`.
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>.jsonAuthoritative format: JSON. Markdown export is read-only.
Announce at start: "I'm using the investigation-state skill to track this investigation."
~/.superpowers/investigations/ on first use if it doesn't exist.*.json in ~/.superpowers/investigations/updated > 7 days → prompt: "Resolve, abandon, or resume?"States: active → paused / resolved / abandoned
export manually. Record next steps via update --next-steps.#investigation-<short-id> if needed.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.
investigation-crud.sh create --title "Bug title" --observed "..." --expected "..." --reproduction "..."id and short_idinvestigation-crud.sh add-hypothesis --id UUID --text "..."Each hypothesis: {id, text, evidence: [{source, finding, timestamp}], verdict: null|confirmed|rejected|inconclusive, verdict_reason}
investigation-crud.sh add-hypothesis --id UUID --text "..." → gather evidenceinvestigation-crud.sh add-evidence --id UUID --hypothesis N --source SRC --finding TEXTinvestigation-crud.sh set-verdict --id UUID --hypothesis N --verdict confirmed --reason "..."Evidence sources: freeform strings (db:example-conn, ci:<project>, linear, local:grep, etc.)
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.
investigation-crud.sh handles all persistence automatically:
os.replace)updated timestamp on every write~/.superpowers/investigations/ and .gitignore on first usereferences/schema.mdUUID-based filenames. One active → resume. Multiple active → investigation-crud.sh list --status active, agent picks one.
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 | 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 |
npx claudepluginhub bordenet/superpowers-plus --plugin superpowers-plusGuides creation, editing, and verification of skills for AI coding agents using test-driven development with subagent scenarios. Use when authoring or debugging skills.