home / skills / shotaiuchi / dotclaude / debug-state

debug-state skill

safe

This skill helps diagnose application state issues by inspecting snapshots, transitions, and caches to reveal corruption, inconsistencies, and unexpected

npx playbooks add skill shotaiuchi/dotclaude --skill debug-state

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.0 KB

---
name: debug-state
description: >-
  Application state investigation. Apply when debugging unexpected state,
  variable corruption, stale caches, data inconsistencies, and state
  transition failures.
user-invocable: false
---

# State Inspector Investigation

Investigate application state to identify corruption, inconsistencies, and unexpected mutations.

## Investigation Checklist

### State Snapshot Analysis
- Capture and compare actual state against expected state
- Identify fields with unexpected or invalid values
- Check for partially initialized objects or incomplete state
- Verify invariants and business rules hold at each checkpoint
- Look for default values that should have been overwritten

### State Transitions
- Trace the sequence of state changes leading to the current state
- Verify each transition follows valid state machine rules
- Identify out-of-order transitions that violate preconditions
- Check for missing transitions that leave state in limbo
- Detect duplicate transitions that corrupt accumulated state

### Cache & Memoization
- Check if cached values are stale or inconsistent with source
- Verify cache invalidation triggers fire correctly
- Identify cache key collisions that return wrong data
- Check TTL and expiration logic for off-by-one errors
- Look for cache poisoning from failed or partial updates

### Side Effects
- Identify unintended mutations to shared or global state
- Check for closure captures that hold stale references
- Verify cleanup and teardown restore state properly
- Detect event handlers that modify state unexpectedly
- Look for implicit state changes in getters or property accessors

## Output Format

Report findings with confidence ratings:

| Confidence | Description |
|------------|-------------|
| High | Root cause clearly identified with supporting evidence |
| Medium | Probable cause identified but needs verification |
| Low | Hypothesis formed but insufficient evidence |
| Inconclusive | Unable to determine from available information |

Overview

This skill inspects application state to locate corruption, inconsistencies, and unexpected mutations. It provides a structured investigation flow that captures snapshots, traces transitions, and evaluates caches and side effects. Use it to form evidence-backed hypotheses about root causes and to produce a confidence-rated findings report.

How this skill works

The skill captures state snapshots and compares them against expected invariants to highlight invalid or partially-initialized fields. It traces state transitions and validates state-machine rules, then inspects caching layers, memoization, and unintended side effects. Findings are reported with confidence ratings (High, Medium, Low, Inconclusive) and include suggested verification steps.

When to use it

When variables or objects contain unexpected or invalid values
When state transitions produce incorrect or out-of-order behavior
When caches return stale or inconsistent data
When global/shared state appears mutated unexpectedly
When debugging intermittent data corruption or race conditions

Best practices

Capture deterministic state snapshots at meaningful checkpoints and store them for comparison
Verify business invariants and preconditions at each transition point
Instrument state transition boundaries with timestamps and origin metadata
Validate cache keys, TTLs, and invalidation paths in unit and integration tests
Look for implicit state changes in getters, closures, and event handlers and add explicit tests

Example use cases

Compare runtime state snapshot to the canonical model to identify fields that were never initialized
Trace a failing workflow to find an out-of-order transition that violated preconditions
Diagnose cache poisoning by comparing cache entries with source-of-truth and checking key collisions
Detect unintended mutation from a shared global by locating closure captures or event handlers that modify state
Validate that teardown and cleanup routines fully restore expected state after tests

FAQ

How do I choose checkpoints for snapshots?

Select points before and after major transitions, on entry/exit of critical services, and around external system boundaries to maximize diagnostic value.

What evidence supports a High confidence finding?

High confidence requires reproducible state differences, matching transition traces, or direct logs showing the mutation or cache operation that caused the issue.