debug-state_skill

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