/state-diff

name: state-diff
description: Compare two state snapshots to identify register and memory changes between two points in time
allowed-tools: Bash, Read

state-diff

Compare two debuggee state snapshots and produce a detailed change analysis — which registers changed, which memory regions were modified, and what the changes mean.

Instructions

Follow these steps exactly:

1. Identify snapshots

List the available snapshots:

dir "${CLAUDE_PLUGIN_ROOT}\snapshots"

If there are fewer than two snapshots, tell the user they need at least two snapshots (captured via `/state-snapshot`) and stop.

If the user specified two snapshot paths, use those directly. Otherwise, present the available snapshots and ask the user to pick the **before** (earlier) and **after** (later) snapshots.

2. Run the diff script

Execute the diff engine:

python "${CLAUDE_PLUGIN_ROOT}\skills\state-diff\state_diff.py" --before <before_snapshot_dir> --after <after_snapshot_dir>

The script writes `diff_report.json` into the after-snapshot directory by default. If the user specified a custom output path, pass `--output <path>`.

3. Read the report

Use `Read` to load the generated `diff_report.json`.

4. Analyze and reason

Interpret the diff report for the user:

• **Register changes**: Explain what each changed register suggests. For example:
• RIP/EIP advanced → instructions were executed
• RSP/ESP changed → stack grew or shrank (function calls, local variables)
• RAX/EAX changed → likely a return value or computation result
• Flag changes → comparison or arithmetic results

• **Memory changes**: Explain what modified regions likely represent:
• Stack region modifications → local variables written, function arguments pushed
• Heap regions → dynamic allocations or object mutations
• Image/module regions → self-modifying code or relocations
• Look at the actual byte patterns for clues (string data, pointers, counters)

• **Synthesize a narrative**: Combine register and memory observations into a coherent explanation of what the program did between the two snapshots. For example: "The program called function X, which allocated Y bytes on the stack and wrote a string to a heap buffer."

Present the analysis in a clear, structured format with the raw evidence (hex values, addresses) supporting each conclusion.