# fission-decompiler-quality

Adopt this skill: https://proskills.md/skills/other/fission-systems-fission

Page: https://proskills.md/skills/other/fission-systems-fission
This document is the public skill bundle for that page. It contains SKILL.md and every helper file the catalog carries. No login is required.

## File: SKILL.md
size: 5094
upstream: https://github.com/fission-systems/fission/blob/HEAD/SKILL.md

````text
---
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.
````

## File: README.md
upstream: https://github.com/fission-systems/fission/blob/HEAD/README.md

````text
<div align="center">

<img src="https://raw.githubusercontent.com/fission-systems/Fission/main/image/fission-logo.svg" alt="Fission - reverse engineering workspace" width="760" />

[![CI](https://github.com/fission-systems/Fission/actions/workflows/ci.yml/badge.svg)](https://github.com/fission-systems/Fission/actions/workflows/ci.yml)
[![Rust](https://img.shields.io/badge/Rust-1.85%2B-orange.svg)](https://www.rust-lang.org/)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue.svg)](https://www.apache.org/licenses/LICENSE-2.0)

</div>

---

# 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`](https://nexte.st/).

```bash
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.)

```bash
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`](docs/CLI.md).

## How it works

```text
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](https://decbench.com), 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.
- **`goto` density is not a quality metric.** Earlier releases reported it as a
  headline number. The structure metric is purely topological and `goto` count
  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/`](docs/changelog/) and
[`docs/EVALUATION.md`](docs/EVALUATION.md).

## Where to look next

| | |
|---|---|
| [`AGENTS.md`](AGENTS.md) | Working rules, quality loop, anti-patterns. Read this before changing decompiler behaviour. |
| [`docs/PROJECT_MAP.md`](docs/PROJECT_MAP.md) | Crate-by-crate ownership map |
| [`docs/CLI.md`](docs/CLI.md) | Command reference |
| [`docs/QUALITY_METRICS.md`](docs/QUALITY_METRICS.md) | What is measured and how |
| [`docs/EVALUATION.md`](docs/EVALUATION.md) | Benchmark lanes and evidence rules |
| [`docs/architecture/DYNAMIC_ANALYSIS.md`](docs/architecture/DYNAMIC_ANALYSIS.md) | Emulator, TTD, symbolic execution, taint, concolic exploration |
| [`docs/architecture/`](docs/architecture/) | Pipeline architecture, diagrams, Ghidra parity audit |
| [`docs/adr/`](docs/adr/) | Architecture decision records |
| [`docs/changelog/`](docs/changelog/) | Release notes, newest first |
| [`docs/proposals/`](docs/proposals/) | Designs in flight, including rejected ones and why |
| [`docs/contributing/FIELD_GUIDE_AND_PLAYBOOKS.md`](docs/contributing/FIELD_GUIDE_AND_PLAYBOOKS.md) | Per-area playbooks, review question bank, handoff template |
| [`docs/contributing/TROUBLESHOOTING.md`](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

```bash
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`](AGENTS.md#decompiler-quality-loop).

## Security

Fission analyses untrusted binaries. Sample handling rules are in
[`docs/MALWARE_SAMPLE_POLICY.md`](docs/MALWARE_SAMPLE_POLICY.md). Rep
````
