⏳ This skill is pending AI review.
Scores will appear once the review pipeline completes.
fission-decompiler-quality
Portable AI skill for improving Fission decompiler quality without benchmark overfit. Use for semantic fixes, NIR/HIR recovery, structuring, type/data recovery, and pseudocode quality work.
Choose how to use this skill
You do not need every option. Choose the path your AI client supports. The stable page stays the same; versioned files are immutable.
1. Native installer
This listing has no registered native installer command. Use the complete package or source fallback below, depending on what your client supports.
Do not guess an installer command or replace an existing version without reviewing the diff.
2. Complete package recommended
Download the ZIP when available. It includes SKILL.md plus the references, security notes and version metadata.
No complete ProSkills package is published for this listing yet.3. Prompt-only
Copy the prompt above when the agent can read the stable page or when you want to adopt the workflow without installing a skill.
Need only the instruction file?
Download SKILL.md only if your client requires a single file. The complete ZIP is safer for a full installation because it preserves the references and release context.
No path installs or executes anything by itself. Your agent still needs access to the project files. Before updating, compare the installed version and review the diff.
// RATINGS
// README
Fission
A Rust-native reverse-engineering workspace. It loads binaries, lifts instruction semantics through Ghidra-style Sleigh specifications, and owns everything after that — its own IR, structuring, type recovery, and rendering.
The long-term target is restoration rather than readability: taking a compiled binary back to a project that builds and runs again, not a listing to read. That target is not reached. Decompiling one binary's 68 functions and compiling them as a single unit currently stops on 20 errors, every one of them a missing or duplicated declaration rather than a wrong statement.
Because the goal is a tree that rebuilds, correctness is checked by execution
rather than by eye: fission-dir evaluates the decompiled body, runs the same
machine code under fission-emulator, and compares. What it cannot prove it
reports as an assumption instead of hiding.
Quick start
Requires Rust 1.85+ and cargo-nextest.
git clone https://github.com/fission-systems/Fission.git
cd Fission
cargo build -p fission-cli --release
./target/release/fission_cli --help
Sleigh specifications and signature data live in utils/, which is committed —
the clone already has them, nothing to download. (Only utils/source/, the
inputs the packed .fpk tables are built from, stays out of git.)
fission_cli info <binary> # format, architecture, provenance
fission_cli list <binary> # discovered functions
fission_cli disasm <binary> --addr 0x1400
fission_cli decomp <binary> --addr 0x1400010a0
fission_cli decomp <binary> --all --json
fission_cli xrefs <binary> --to 0x140002000
For local iteration prefer --profile quick-release. [profile.release] uses
fat LTO and codegen-units = 1, which serializes linking and dominates rebuild
time; quick-release drops both but keeps opt-level = 3 — measured ~2.9x
faster on a one-crate rebuild (44s → 15s) with byte-identical output on the
regression set. Use plain --release for anything feeding a benchmark.
Full command reference: docs/CLI.md.
How it works
Binary bytes
→ fission-loader format, sections, symbols, imports
→ fission-static facts and provenance
→ fission-sleigh decode and raw p-code lift
→ fission-pcode NIR canonical semantics
→ fission-pcode HIR human-readable derivation
→ structuring, cleanup, rendering
→ fission-decompiler result contracts
→ CLI, TUI, GUI
Two output layers with different contracts:
| Layer | Contract |
|---|---|
| NIR | Semantically identical to the machine code. Correctness and parity come first; it is not prettified by losing behaviour. |
| HIR | Readable pseudocode derived from correct semantics. May drop temporaries when that improves readability without hiding what happened. |
Structuring
Fission implements all three published approaches against one substrate and lets them compete per function:
| Approach | Reference | Module |
|---|---|---|
| Rules over a live graph | Ghidra CollapseStructure | collapse_structure.rs |
| Schema match-and-fold | angr Phoenix | collapse_driver.rs |
| Reaching conditions | DREAM | reaching_driver.rs |
The substrate is CollapseGraph: a CFG that shrinks as regions fold, so
each match sees the already-simplified shape. Every reference implementation
folds a live graph; Fission used to analyse a static one with side tables, and
that was the root architectural gap.
Drivers do not pre-empt each other. Each offers a candidate and
structuring_quality decides, comparing raw, normalized, and full post-layout
output — a candidate that looks worse before cleanup routinely wins after it.
That admission rule is known to be optimizing the wrong thing. Forcing all six
drivers onto the near-miss functions yields zero additional exact matches, and
goto count does not track the structural distance benchmarks score. Finding a
signal that does — computable without the source CFG — is open work.
Evaluation
Fission is scored on DecBench, which measures structure (graph edit distance against the source CFG), types (against DWARF), and byte_match (recompile and diff). All three count only exact matches, so a near miss scores the same as a miss.
Two cautions about reading those numbers, both learned here:
- A benchmark that scores CFG shape and declared types cannot see whether the emitted C does what the binary does. Several real defect classes were found by diffing recompiled assembly or by execution differential, and none of them moved a score by more than a row — dropped writes to globals, return addresses passed as trailing arguments, argument registers read across an intervening call.
gotodensity is not a quality metric. Earlier releases reported it as a headline number. The structure metric is purely topological andgotocount is not part of it; optimizing structural accuracy instead raised the count.
Current numbers, how each was reached, and the approaches measured and rejected
are in docs/changelog/ and
docs/EVALUATION.md.
Where to look next
AGENTS.md | Working rules, quality loop, anti-patterns. Read this before changing decompiler behaviour. |
docs/PROJECT_MAP.md | Crate-by-crate ownership map |
docs/CLI.md | Command reference |
docs/QUALITY_METRICS.md | What is measured and how |
docs/EVALUATION.md | Benchmark lanes and evidence rules |
docs/architecture/DYNAMIC_ANALYSIS.md | Emulator, TTD, symbolic execution, taint, concolic exploration |
docs/architecture/ | Pipeline architecture, diagrams, Ghidra parity audit |
docs/adr/ | Architecture decision records |
docs/changelog/ | Release notes, newest first |
docs/proposals/ | Designs in flight, including rejected ones and why |
docs/contributing/FIELD_GUIDE_AND_PLAYBOOKS.md | Per-area playbooks, review question bank, handoff template |
docs/contributing/TROUBLESHOOTING.md | Common local failures, and the glossary |
Ownership is strict: a semantic problem in the final pseudocode gets fixed
where the behaviour is owned, never in the renderer. Vendor trees under
vendor/ are references for reading only — no production path may depend on
them at build or runtime.
Testing
cargo nextest run --workspace # full suite
cargo nextest run -p fission-pcode # one crate
cargo build --workspace --all-targets # compile everything
fission-dir carries the execution differential; run it after any change that
claims to preserve semantics. Aggregate metrics must not hide row-level
regressions — a changed pseudocode file is not automatically an improvement,
and a passing synthetic test is necessary but not sufficient for a quality
claim. The reasoning is in AGENTS.md.
Security
Fission analyses untrusted binaries. Sample handling rules are in
docs/MALWARE_SAMPLE_POLICY.md. Rep
// HOW IT'S BUILT
// FILES
2 files shipped with this skill. Inline text is the catalog copy. The upstream link is the source repository.
SKILL.md5.0 KBupstream ↗
--- name: "fission-decompiler-quality" description: "Portable AI skill for improving Fission decompiler quality without benchmark overfit. Use for semantic fixes, NIR/HIR recovery, structuring, type/data recovery, and pseudocode quality work." --- # Fission Decompiler Quality Skill Use this skill when improving Fission's Rust-native decompiler pipeline. The goal is better semantic correctness and readable C-like pseudocode without row-specific, benchmark-specific, or AI-prompt overfit. ## Priority Order 1. Improve x86/x86-64 source-semantic correctness and readable pseudocode quality. 2. Fix type/data abstraction: pointers, arrays, structs, fields, calling convention, parameters, locals. 3. Improve hard control-flow recovery: if/else, switch, loops, break/continue, irreducible cases. 4. Preserve SLEIGH/p-code lift correctness; do not add manual SLEIGH mappings or legacy fallback debt. 5. Improve name/FID recovery only after the semantic owner is clear. 6. Expand architecture/file-format breadth after x86/x86-64 quality is stable. ## Architecture Contract `fission-pcode` owns shipped decompiler semantics, but it is not a dumping ground for every fix. Treat it as: - **Substrate:** IR/HIR types, p-code/NIR contracts, telemetry, action pipeline, shared CFG facts, def-use facts, type constraints, calling-convention facts, and alias facts. - **Owner layers:** builder/materialize, normalize, type/data recovery, structuring, and render/printer. - **Future split candidates:** `fission-nir-analysis`, `fission-nir-normalize`, `fission-structuring`. Before adding code, translate the observed failure into an owner-native invariant. Prefer reusable dataflow, def-use, type-constraint, calling-convention, CFG, or alias analysis over another narrow pass/helper. Forbidden production shortcuts: - Function-name, address, binary-path, corpus-row, or compiler-tuple branches. - Printer/UI/dashboard-only semantic fixes. - Structuring code that repairs expression semantics. - Normalize code that recovers builder-owned stack/parameter facts. - Builder code that calls normalize, structuring promotion, or render policy as a shortcut. - Ghidra output-style mimicry when a clearer equivalent preserves correctness. - Runtime/build dependency on `vendor/` reference code or C++ bindings. ## Improvement Workflow 1. Record the baseline: motivating row/sample, current output, semantic case count, failure category, and smallest p-code/NIR/HIR/CFG evidence. 2. Prove the owner: SLEIGH/raw p-code, builder/materialize, normalize, type/data recovery, structuring, printer, or benchmark/automation. 3. State the invariant using ABI/ISA, p-code semantics, CFG/dominance/postdominance, def-use, type constraints, calling convention, or alias facts. 4. Check whether the invariant belongs in shared substrate analysis before adding a pass/helper. 5. Extend the existing owner/pass by default. Add new owners only with explicit proof that no existing owner covers the invariant. 6. Add targeted invariant coverage, including negative cases when broadening acceptance. 7. Validate with focused tests, crate-level tests/checks, focused benchmark row, and smoke/automation no-regression evidence. 8. Report quality truthfully: distinguish mechanical code changes, telemetry-only changes, benchmark harness changes, and actual semantic improvement. ## AI Prompt Firewall When asking another AI model for help, provide only structural information: - structural failure pattern, - owner evidence, - invariant candidates, - forbidden shortcuts, - validation matrix. Redact benchmark function names, concrete addresses, binary paths, corpus row ids, and compiler tuples. Ghidra may be used as a cleanroom reference for algorithms and invariants, not as an output-style target. Use `docs/templates/AI_DECOMPILER_REVIEW_PROMPT.md` for cross-model review and `docs/templates/DECOMPILER_CHANGE_PROPOSAL.md` before production semantic changes. ## Validation Commands Run the smallest relevant checks first, then broaden: ```bash cargo nextest run -p fission-pcode --filter <targeted_test> cargo nextest run -p fission-pcode cargo check -p fission-pcode cargo check -p fission-decompiler python3 scripts/test/no_benchmark_fixture_refs_in_crates.py python3 scripts/audit/benchmark_smell_scan.py --root . --mode fast --fail-on high python3 scripts/audit/ai_prompt_leak_scan.py --root . python3 scripts/audit/nir_boundary_scan.py --root . ``` For semantic claims, also rerun the focused source-semantic benchmark row with stale decompilation and behavior caches disabled. Compare behavior status, case progress, stderr/stdout, pseudocode size, and feature gaps, not just aggregate scores. ## Review Rejection Rules Reject a proposed fix if it: - improves only a dashboard/metric without moving semantic evidence, - adds a sample-specific guard, - creates a new narrow pass where shared analysis would fit, - increases owner-to-owner dependency debt without justification, - claims success from one targeted test only, - copies reference implementation code instead of cleanroom reasoning.README.mdupstream ↗
Contents are not inlined in the catalog. Open the upstream file.
Plain-text copy, no login: /skill-bundles/fission-systems-fission.md