| name | patchir-inspect |
| description | This skill should be used when the user asks to verify, debug, or generate regression tests for the patchir-decomp structuring pipeline. Operates in two modes: --debug verifies that the default structuring pipeline produces functionally equivalent C output compared to the goto-based baseline (produced via the hidden --emit-flat-baseline flag) and performs JSON ground-truth audit. --test-gen extracts P-Code from a binary via Ghidra headless and generates a LIT test with FileCheck patterns.
Trigger the skill when the user asks to "debug patchir output", "analyze decompilation issues", "find structuring bugs", "compare structuring output", "diff structured vs goto", "check structuring quality", "analyze structuring pass", "find structuring issues", "test structuring on JSON", "verify structuring correctness", "test patchir-decomp on JSON", "debug a fixture", "find missing statements", "audit patchir-decomp", "check ClangAST emission", "find emission bugs", "generate test", "create LIT test from binary", "generate regression test", or invokes "/patchir-inspect [--debug|--test-gen] <args>".
|
patchir-inspect: Structuring Verification & Test Generation Tool
Two modes for the patchir-decomp pipeline:
--debug: verify the default structuring pipeline produces
functionally equivalent C output compared to the goto-based baseline
(emitted via the hidden --emit-flat-baseline flag), and audit both
outputs against the input P-Code JSON for emission bugs.--test-gen: extract P-Code from a binary function via Ghidra
headless and generate a complete LIT test with FileCheck patterns.
Arguments
--debug <fixture.json> # equivalence checks (default)
--debug --batch # run on ALL fixtures in test/patchir-decomp/
--test-gen --binary <path> --function <name> # generate LIT test from binary
When no mode flag is present, default to --debug.
Mode Dispatch
Each mode runs inside its own isolated general-purpose subagent via the
Task tool. This keeps the main context clean — raw decomp outputs, batch
tables, and Docker logs never reach the parent conversation.
--debug → spawn the Debug Agent (Task prompt defined below)--test-gen → spawn the Test-Gen Agent (Task prompt defined below)
After the subagent returns, relay its verdict and any findings back to
the user. Do not re-run the checks in the parent context.
Debug Agent
When dispatched, spawn a general-purpose subagent using the Task tool
with the prompt template below. Substitute <FIXTURE> with the target
JSON (or the literal string --batch when batch mode is requested).
You are running the patchir-inspect debug-mode workflow against <FIXTURE>.
Project root: <cwd>
Binary: builds/*/tools/patchir-decomp/*/patchir-decomp
Strip script: test/scripts/strip-json-comments.sh
Reference methodology: .claude/skills/patchir-inspect/references/structuring-diff-checks.md
Workflow:
1. For each input fixture (one file or every JSON in test/patchir-decomp/
when --batch), strip // comments with the strip script and run
patchir-decomp twice — once with --emit-flat-baseline (goto baseline)
and once without it (default structured output). Capture stderr.
2. Run the Step 2 functional equivalence checks on both .c outputs:
- 2.5 Condition preservation (if/while/switch counts, &&/|| merge
triage)
- 2.6 Duplicate and cross-scope overwrite detection
- 2.7 Structuring-introduced dead code
- 2.8 Fallthrough into goto-only labels
Full check definitions are in references/structuring-diff-checks.md.
3. Run the Step 3 JSON ground-truth audit on the input P-Code JSON
vs both C outputs: CALL coverage, CBRANCH/condition, STORE/
assignment, RETURN, globals, per-block reachability, duplicate
assignment. Flag definitions are in the reference file.
4. For --batch, emit the summary table with columns Fixture, Status,
G(goto), G(struct), Elim%, Conds, Fall, JSON, Flags. Aggregate
stats: total, pass, flag, skip, fully-structured count, goto
elimination %, condition losses, fallthrough count.
5. Classify findings:
- Critical: CALL_LOST, missing switch cases, crash, lost conditions,
Fall>0, 2.6b cross-scope overwrite
- Bug: DUP_ASSIGN, lost assignments, structuring-introduced dead code
- Flag: COND_DEFICIT, STORE_DEFICIT, BLOCK_LOST
- Warning: remaining gotos, dead labels, redundant breaks
6. End with a single VERDICT line:
- VERDICT: PASS — no Critical/Bug, no unresolved Flags
- VERDICT: FLAG — Flags present, need triage
- VERDICT: FAIL — Critical or Bug present
Report concisely. For --batch, include the full table but limit per-
fixture triage narrative to fixtures flagged as non-PASS. For a single
fixture, include any Critical/Bug findings with file:line references.
Test-Gen Agent
When dispatched, spawn a general-purpose subagent using the Task tool
with the prompt template below. Substitute <BINARY> and <FUNCTION>
with the user-provided values.
You are running the patchir-inspect test-gen workflow for function
"<FUNCTION>" from binary "<BINARY>".
Project root: <cwd>
Decomp binary: builds/*/tools/patchir-decomp/*/patchir-decomp
Ghidra wrapper: scripts/ghidra/decompile-headless.sh
Docker build: scripts/ghidra/build-headless-docker.sh
Call-check generator: scripts/gen-call-checks.py
Workflow:
1. Ensure the Ghidra Docker image exists:
docker image inspect trailofbits/patchestry-decompilation:latest
If missing, run scripts/ghidra/build-headless-docker.sh and report
"Building Ghidra headless Docker image (one-time setup)...". Stop
on build failure and report stderr.
2. Extract P-Code JSON:
bash scripts/ghidra/decompile-headless.sh \
--input <BINARY> \
--function <FUNCTION> \
--output /tmp/patchdbg_testgen/<FUNCTION>.json
Stop on extraction failure and report stderr.
3. Generate baseline outputs from the extracted JSON:
<decomp> -input <extracted> \
-emit-cir -emit-llvm -print-tu -output <baseline>
4. Build FileCheck patterns from the baseline:
- Function signature: grep `cir.func @<FUNCTION>(` from the .cir
output and emit it as the FN check line.
- Call targets: run
python3 scripts/gen-call-checks.py <extracted.json>
to produce `// CALL-CHECK-DAG: cir.call @<target>(` lines.
5. Assemble test/patchir-decomp/<FUNCTION>.json with this header,
followed by the raw extracted JSON as-is:
// RUN: bash %strip-json-comments %s > %t.json
// RUN: %patchir-decomp -input %t.json -emit-cir -emit-llvm -print-tu -output %t >> /dev/null 2>&1
// RUN: %file-check -vv -check-prefix=FN %s --input-file %t.cir
// FN: cir.func @<FUNCTION>(
// RUN: %gen-call-checks %t.json > %t.call.checks
// RUN: %file-check -check-prefix=CALL-CHECK %t.call.checks --input-file %t.cir
Follow the pattern in existing fixtures like bloodview__parse_cli.json
and bool_ops.json.
6. Validate the generated test:
lit builds/default/test/patchir-decomp/<FUNCTION>.json \
-D BUILD_TYPE=Debug -v
On LIT failure, report the output and leave the file in place.
7. Report:
Generated: test/patchir-decomp/<FUNCTION>.json
Source: <BINARY> :: <FUNCTION>
Blocks: N basic blocks, M operations
Checks: FN (signature), CALL-CHECK (K call targets)
LIT: PASS
Additional Resources
Reference Files
references/structuring-diff-checks.md — full methodology for
checks 2.1–2.10 and 3.1–3.7, flag definitions, triage rules, concrete
bug examplesreferences/usage-plan.md — development workflow recipes for
pre-commit gating, regression checking, and test generation
