skills.rest
bordenet
bordenetCOMMUNITY
Explore all skills by this author →
GitHub

investigation-state

Persist debugging context in schema-validated JSON with atomic writes.

8|1|Updated Jan 24, 2026
Search Tags:#debugging#investigation#cli#persistence#evidence#state-management#hypotheses
One-click install
npx skills add https://github.com/bordenet/superpowers-plus --skill investigation-state
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: investigation-state
Source: https://github.com/bordenet/superpowers-plus/tree/main/skills/engineering/investigation-state
Command: npx skills add https://github.com/bordenet/superpowers-plus --skill investigation-state

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Preserve multi-session debugging context so hypotheses, evidence, eliminated approaches, and next steps are not lost between agent turns, system restarts, or handoffs, reducing duplicated work and missed clues during root-cause investigation.

Core Features & Use Cases

  • Durable JSON store: Authoritative investigations are saved as UUID-named JSON files under the user's ~/.superpowers/investigations/ directory and updated atomically.
  • CLI-first workflow: A single recommended tool (investigation-crud.sh) provides create, list, show, export, hypothesis/evidence management, lifecycle commands, and schema validation to avoid manual edits.
  • Hypothesis & evidence tracking: Record hypotheses with structured evidence entries, verdicts, eliminated approaches, next steps, and related tickets or TODOs for clean handoffs and continuity.
  • Lifecycle management & safety: Enforced states (active/paused/resolved/abandoned), stale-investigation checks, concurrent-investigation guidance, and markdown export for readable handoffs.
  • Use case: Start a long-running reproduction and debugging session, persist all findings and checks, resume after interruption, or hand the investigation to another agent without losing context.

Quick Start

Start a new investigation and record the first hypothesis by running the investigation-crud.sh create command with a title, observed behavior, and reproduction steps.

Frequently Asked Questions about investigation-state

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I persist debugging context across multiple sessions?▼

To persist debugging context across multiple sessions, you can use a CLI tool to save hypotheses, evidence, and next steps as schema-validated JSON files. This ensures investigation state survives restarts and context loss.

What is the best way to manage debugging hypotheses and evidence for handoffs?▼

Managing debugging hypotheses and evidence for handoffs is best handled by recording structured entries in an authoritative JSON store. You can then export the investigation state to markdown for a readable, clean handoff to another agent.

How do I checkpoint a debugging investigation before a session ends?▼

To checkpoint a debugging investigation before a session ends, use CLI lifecycle commands to pause or update the investigation state. The state is saved atomically to a UUID-named JSON file, preventing data loss during sudden interruptions.

Can I clone a debugging investigation for parallel work?▼

Yes, you can clone a debugging investigation for parallel work. The workflow supports creating multiple investigation states with UUID-based filenames, allowing you to track distinct hypotheses and evidence branches concurrently.

Does this debugging state management approach enforce investigation lifecycle states?▼

Yes, this debugging state management approach enforces lifecycle states including active, paused, resolved, and abandoned. It also performs stale-investigation checks and provides concurrent-investigation guidance to maintain safety.

How do I avoid manual JSON edits when tracking debugging state?▼

To avoid manual JSON edits when tracking debugging state, use the provided CLI CRUD tool. It manages create, list, show, and export operations while performing schema validation to ensure data integrity.

Related Skills

Explore More Software Engineering Skills→
smarmen86smarmen86

unfreeze

Deletes the freeze state file to restore write access across project directories.

Community
Basic
smallnestsmallnest
190

markitdown

Convert PDFs, Word, Excel, HTML, and images with OCR into Markdown.

Community
Advanced
jeanlucianojeanluciano
20

Debugging Issues

Diagnose software bugs through systematic reproduction, isolation, and hypothesis testing.

Community
Advanced
daffy0208daffy0208
34

Knowledge Base Manager

Design and maintain knowledge bases with RAG, graph, and hybrid architectures.

Community
Advanced