Nintendo 3DS decomp guide

What this system is like

The 3DS is the newest hot spot for PC ports. Nine of the ten projects we read use static recompilation. A tool reads the game's ARM code and writes C. A runtime then stands in for the console. Four projects simply reused one free pair of tools: 3dsrecomp and Zakuro.

That pair changes the job. With it, Shin Megami Tensei IV reached its title screen on day one. Fire Emblem: Awakening had a release three days after its first commit. Your work is mostly the last mile: missed functions, runtime bugs, PC features and long play tests.

A full decomp is a different story. Games are big C++ programs built with ARM's own compiler, armcc. Several matching projects started in late 2026, some run by AI agents. The furthest, for Monster Hunter 4 Ultimate, had 82% of its functions matched but only 44% of its code bytes. No 3DS game is fully decompiled yet, and none has been ported from a decomp.

Almost all of this runs on Windows. You need your own game, dumped and decrypted on a modded 3DS with GodMode9. The dump and anything made from it never go in your repo.

Two paths

Path A: Get it running on PC

The game's ARM code is turned into C ahead of time and compiled for the PC. A runtime replaces the kernel, services, GPU and sound. On the 3DS you rarely write those yourself: 3dsrecomp and Zakuro already exist. Your job is scope, checks, missed code, runtime bugs and PC features.

1. Scope the game and pick one exact build

   Pick one game, one region and one revision. Dump and decrypt your own card. Look for prior work, because a game may already run on Zakuro. Write it all in SCOPE.md.

   • GodMode9 runs only on a 3DS with custom firmware. Its README sends you to 3ds.hacks.guide or fastboot3DS for that setup.
   • Dump your card on a modded 3DS with GodMode9: [C:] GAMECART, then Dump cart (trimmed), then Decrypt file if needed.
   • Hash the dump in PowerShell: Get-FileHash <GAME>.3ds -Algorithm SHA256.
   • Check COMPATIBILITY.md in the Zakuro repo and the RecompLauncher list for your game.
   • Search GitHub for <GAME> recomp and <GAME> decomp. Note the title ID and region of each hit.
   • Write SCOPE.md: game, region, title ID, SHA-256, goal, technique, first milestone and its check.
   • Make empty files PROGRESS.md and notes/parking-lot.md.
   Prompt for ClaudeCopy

   GOAL: Write a one-page `SCOPE.md` for a static recomp of <GAME> (<REGION>, title ID <TITLE_ID>, SHA-256 <HASH>).
   READ FIRST: `notes/prior-work.md` (my search results), the `Zakuro` `COMPATIBILITY.md`, the RecompLauncher entry if any. Do not open the dump.
   FENCE: Edit only `SCOPE.md` and `notes/prior-work.md`. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `Select-String -Path SCOPE.md -Pattern '^#'`. `SCOPE.md` must have these headings: Goal, Dump and hash, Technique, Prior work, Milestone 1 and its check, Out of scope, Never edit. Done means every heading has real content and every prior-work claim has a URL.
   BUDGET: Stop after 30 minutes or 3 drafts.
   IF BLOCKED: Stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenSCOPE.md has all seven headings filled, and you approved it.

   Proof this works: Shin Megami Tensei IV Recomp, Fire Emblem: Awakening for Windows, https://github.com/watchmakerers/clockwork

2. Set up the tools and the repo

   Install Rust, a C compiler and the two upstream tools. Pin them to exact versions. Lay out a repo that holds only your own code. Add the one check command and CLAUDE.md.

   • Install Rust with the installer from rustup.rs, then run rustup default stable-x86_64-pc-windows-gnu. The MSVC toolchain failed for Shin Megami Tensei IV. The 3dsrecomp port doc says MSVC Rust needs LLVM clang and llvm-ar instead.
   • Install MinGW gcc: winget install BrechtSanders.WinLibs.POSIX.UCRT, or MSYS2 with pacman -S mingw-w64-ucrt-x86_64-gcc.
   • Install the tools at a fixed commit: cargo install --git https://github.com/fearkov/3dsrecomp --rev <COMMIT> --locked --features verify recomp3ds and cargo install --git https://github.com/fearkov/zakuro --rev <COMMIT> --locked zakuro. Cargo puts 3dsrecomp and zakuro in ~/.cargo/bin.
   • Write the commit of each tool into SCOPE.md. Awakening pinned 3dsrecomp at 9db0d8b and Zakuro at 80d78be.
   • Make folders dump/, out/, logs/ and add them to .gitignore. Put your dump outside the repo or in dump/.
   • Write tools/check.ps1. It rebuilds and runs the boot probe from step 5. Run it as powershell -NoProfile -ExecutionPolicy Bypass -File tools/check.ps1, so the script policy cannot block it. Write CLAUDE.md from the list in this guide.
   Prompt for ClaudeCopy

   GOAL: Set up the repo for <GAME> so one command builds the recompiled code and one command runs the check.
   READ FIRST: `SCOPE.md`, the `3dsrecomp` README and `docs/port.md`, the `Zakuro` README.
   FENCE: Edit only `tools/`, `.gitignore`, `CLAUDE.md`, `PROGRESS.md` and `README.md`. Never copy the dump or anything made from it into the repo. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `3dsrecomp` with no arguments, `zakuro --help`, then `git status --ignored`. Done means the first prints its `usage, 3dsrecomp analyze` lines, the second prints its options, the pinned commits are in `SCOPE.md`, and `dump/` and `out/` show as ignored.
   BUDGET: Stop after 45 minutes or 3 failed installs.
   IF BLOCKED: Stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenBoth tools print their usage text in a fresh terminal, their commits are written down, and git status --ignored shows dump/ and out/ ignored.

   Proof this works: Shin Megami Tensei IV Recomp, Fire Emblem: Awakening for Windows, https://github.com/fearkov/3dsrecomp

3. Map the game: coverage, modules and services

   Find out how much code the recompiler finds before you build. List the CRO modules and the services the game uses. This sets your risks. Save it as a ledger file.

   • Run 3dsrecomp analyze <path>\<GAME>.3ds and save the output to logs/analyze.txt.
   • Unpack the code with ctrtool --exefsdir=out/exefs --romfsdir=out/romfs --exheader=out/exheader.bin <GAME>.3ds.
   • Save the file info: ctrtool -i <GAME>.3ds > logs/info.txt. The ExHeader in it lists the services the game may call.
   • List the .cro files in out/romfs/cro/, if there are any.
   • Optional: load the game in Ghidra with a CTR loader, which reads CXI and CRO files. The loader is untested; see the tools list.
   • Write notes/ledger.csv with columns: id, kind (crash, hang, missing call, gfx), address, status, proof.
   Prompt for ClaudeCopy

   GOAL: Write `notes/map.md` and an empty `notes/ledger.csv` for <GAME> from the recompiler's analysis.
   READ FIRST: `logs/analyze.txt`, the file list of `out/romfs/cro/`, `logs/info.txt` (the output of `ctrtool -i`).
   FENCE: Edit only `notes/map.md` and `notes/ledger.csv`. Do not run a build. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `3dsrecomp analyze <GAME>.3ds` again and compare its numbers with the note. Done means `notes/map.md` gives the code coverage percent from `analyze`, the count of CRO modules, and the list of services from the ExHeader, each with the command that produced it.
   BUDGET: Stop after 30 minutes.
   IF BLOCKED: Stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whennotes/map.md holds the coverage percent, the module count and the service list, each with its source command.

   Proof this works: https://github.com/watchmakerers/clockwork/blob/master/docs/PHASE0.md, Shin Megami Tensei IV Recomp, MSR2DS

4. First light: build and boot to the title screen

   Run the recompiler over the whole game and start it in Zakuro. The first build is slow, often 10 to 25 minutes. The goal is one picture: the title screen.

   • Run 3dsrecomp build <GAME>.3ds out/recomp. Save the output to logs/build.txt.
   • Start the game with zakuro <GAME>.3ds --recompiled out/recomp --data test/. --data keeps test saves out of your own.
   • If you want a program of your own, run 3dsrecomp port <GAME>.3ds <DIR>, then cargo build --release inside <DIR>. After you update 3dsrecomp, run cargo update -p zakuro there first.
   • On Windows, a ported program may need a bigger main stack. Dragon Quest VIII asked the linker for 8 MiB.
   • Run a smoke test with no window: zakuro <GAME>.3ds --recompiled out/recomp --data test/ --headless 1800. It runs 1,800 frames, then prints a report.
   • Take a screenshot of the title screen and save it in logs/.
   Prompt for ClaudeCopy

   GOAL: Build <GAME> with `3dsrecomp` and boot it in `Zakuro` to the title screen.
   READ FIRST: `SCOPE.md`, `notes/map.md`, the `3dsrecomp` README.
   FENCE: Edit only `tools/` and `logs/`. Never edit the generated C in `out/recomp/`. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `zakuro <GAME>.3ds --recompiled out/recomp --data test/ --headless 1800`. Done means it prints `Completed after 1800 frames` and no `fatal errors:` line, and a title-screen screenshot is saved in `logs/`.
   BUDGET: Stop after 3 failed builds. A build takes up to 25 minutes, so do not rebuild without a new reason.
   IF BLOCKED: Stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenzakuro <GAME>.3ds --recompiled out/recomp --data test/ --headless 1800 prints Completed after 1800 frames with no fatal errors: line, and a title-screen screenshot from the recompiled build is in logs/.

   Proof this works: Shin Megami Tensei IV Recomp, Fire Emblem Fates Special Edition Recomp, Dragon Quest VIII 3DS Recomp, https://github.com/fearkov/zakuro/blob/main/crates/zakuro/src/cli.rs

5. Build golden runs that need no person

   Make the check run by itself. A boot probe starts the game, presses keys on a timer, saves a picture and stops. Now Claude can test without you at the controller.

   • Write tools/boot_probe.py. It starts the game with a time limit, for example --seconds 15, and saves the log.
   • Give the test its own data folder with --data test/. Never use the folder you play from.
   • Record the keys once: set ZAKURO_RECORD=test/inputs/<RUN>.rec and play to the checkpoint. Replay them with ZAKURO_REPLAY=test/inputs/<RUN>.rec. A replay starts the game clock where the recording did. MSR2DS also found keys more reliable than menu clicks.
   • Save a screenshot at each checkpoint. Name it after the checkpoint, such as logs/golden/01-title.png.
   • Make tools/check.ps1 run every golden run and print PASS or FAIL for each.
   Prompt for ClaudeCopy

   GOAL: Write `tools/boot_probe.py` and three golden runs for <GAME>: title screen, file select, first playable scene.
   READ FIRST: `tools/check.ps1`, `notes/map.md`, the key map in the `Zakuro` README, the output of `zakuro --help`.
   FENCE: Edit only `tools/` and `test/`. Never touch my play folder <PLAY_FOLDER>. Stop only the game process you started, never others by name. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `tools/check.ps1`. Done means it prints PASS for all three runs, twice in a row, and each run saves its screenshot.
   BUDGET: Stop after 90 minutes or 5 failed tries on one run.
   IF BLOCKED: Stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whentools/check.ps1 prints PASS for three golden runs twice in a row, with screenshots saved.

   Proof this works: Luigi's Mansion 2 Recompiled, MSR2DS, Clockwork, https://github.com/fearkov/zakuro

6. Grind: fix missed code and crashes, one at a time

   Play, find a break, and fix that one break. Most breaks are missed functions or a runtime bug. Fix missed functions with hints, never by editing generated C. Send runtime bugs upstream with a trace.

   • After a play session, read the log of addresses that still ran in the interpreter. The next build takes them in.
   • Run 3dsrecomp hints <GAME>.3ds. It prints your game's section for hints.txt from the addresses Zakuro logged.
   • Add that section, or a start you found by hand, to 3dsrecomp's hints.txt. Each section starts with = <title id> <code hash>. Keep it as a patch file in your repo.
   • For a crash in Zakuro, write a short trace of the cause. Shin Megami Tensei IV's report was fixed upstream within hours.
   • Add one row per bug to notes/ledger.csv, and one golden run that shows the fix.
   • Rebuild and run tools/check.ps1 before you mark a row done.
   Prompt for ClaudeCopy

   GOAL: Fix ledger row <ID> in <GAME>: <SYMPTOM> at <ADDRESS or SCENE>.
   READ FIRST: `notes/ledger.csv` row <ID>, `logs/<RUN>.txt`, `CLAUDE.md`, the `3dsrecomp` `docs/overrides.md`.
   FENCE: Edit only `patches/`, `overrides/` and `tools/`. Never edit generated C in `out/`. Never return fake success from a service to get past a hang. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `tools/check.ps1`. Done means the golden run for row <ID> passes, every older golden run still passes, and the cause is written in `notes/bugs/<ID>.md`.
   BUDGET: Stop after 4 failed fixes, or after 60 minutes with no new evidence.
   IF BLOCKED: Stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenThe ledger row has a cause, a fix and a golden run, and the full check passes.

   Proof this works: Fire Emblem: Awakening for Windows, Luigi's Mansion 2 Recompiled, Shin Megami Tensei IV Recomp

7. Add PC features with overrides

   Change the game the safe way. An override is a C function that replaces one game function by address. Widescreen, one-screen layouts and speed options all came this way. Each change gets a switch and a golden run.

   • Write the change in overrides/<feature>.c with RECOMP_OVERRIDE(0x<ADDRESS>). An odd address means a Thumb function.
   • Build with 3dsrecomp build <GAME>.3ds out/recomp --overrides overrides/.
   • For widescreen, Shin Megami Tensei IV searched .code for the float 400/240 (0x3FD55555) and followed it to the perspective setup.
   • If you must patch generated C, anchor the patch on the instruction comment so it fails loudly after a rebuild.
   • Leave the game's speed alone: 60 fps cheats made Shin Megami Tensei IV run twice as fast.
   Prompt for ClaudeCopy

   GOAL: Add <FEATURE> to <GAME> as an override, behind a setting that is off by default.
   READ FIRST: `docs/overrides.md` in `3dsrecomp`, `notes/map.md`, the function at <ADDRESS> in Ghidra.
   FENCE: Edit only `overrides/<FEATURE>.c` and the settings file. Never edit generated C. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `tools/check.ps1`. Done means all golden runs pass with the setting off, a new golden run shows the feature with it on, and the screenshot is saved.
   BUDGET: Stop after 4 failed builds or 90 minutes.
   IF BLOCKED: Stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenThe feature works behind its setting, and every golden run still passes with the setting off.

   Proof this works: Shin Megami Tensei IV Recomp, https://github.com/fearkov/3dsrecomp/blob/main/docs/overrides.md, Dragon Quest VIII 3DS Recomp

8. Harden: regression set, clean build, safe package

   Make sure old fixes stay fixed. Build from a clean clone. Ship only your own code. Users build the game from their own dump.

   • Run 3dsrecomp verify <GAME>.3ds <LIBRARY>. It needs the verify feature from step 2. It compares recompiled functions against Zakuro's interpreter. A build with no folder puts the library in %APPDATA%\3dsrecomp\.
   • Clone the repo into a new folder and run tools/check.ps1 there.
   • Check the dump's hash before any build. Refuse other regions with a clear message.
   • Package the launcher, patches and overrides only. Never ship out/, the dump, saves or shader caches.
   • Collect third-party licences. 3dsrecomp had no licence file, so Awakening noted its MIT Cargo.toml instead.
   Prompt for ClaudeCopy

   GOAL: Prove the <GAME> port builds and passes all checks from a clean clone, and package it with no game data.
   READ FIRST: `CLAUDE.md`, `tools/check.ps1`, `notes/ledger.csv`, the packaging script.
   FENCE: Edit only `tools/package.ps1`, `README.md` and `LICENSES/`. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Clone into <CLEAN_DIR> and run `tools/check.ps1`. Then list the package files. Done means every golden run passes there, `3dsrecomp verify` reports no new mismatches, and no file in the package comes from the game.
   BUDGET: Stop after 60 minutes.
   IF BLOCKED: Stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenA clean clone passes every golden run, and the package holds no file made from the game.

   Proof this works: TriAevum: Echoes of Time, Woohoo! Flight School, https://github.com/fearkov/3dsrecomp

Path B: Full decomp for porting

You write C++ that armcc turns into the game's exact bytes, one function at a time. A judge script compares each function. Then you link the whole code.bin and compare its hash. Several AI-driven projects began in 2026. None is finished, and none has been ported yet.

1. Scope: pick the game, build and compiler

   Choose one game and one exact code.bin. Look for an existing decomp first. Find which armcc build made the game. Decide between byte matching and a looser structure check.

   • Search GitHub for <GAME> decomp. Look at zeldaret/oot3d, 7akeem0/albw-decomp-ai, Tsukimi-Labs/Solstice and RedShyGuy/acnl-decomp to see the options.
   • Read the SDK strings in the plain region of the dump. They name the SDK version.
   • Test small functions on decomp.me, platform n3ds, against armcc 4.0, 4.1 and 5.04 builds.
   • Decide: byte matching with armcc, or structure checking with GCC like the ACNL project.
   • Write SCOPE.md with the code.bin SHA-1, the compiler build, default flags and the first milestone.
   Prompt for ClaudeCopy

   GOAL: Write `SCOPE.md` for a matching decomp of <GAME> (<REGION>, `code.bin` SHA-1 <HASH>).
   READ FIRST: `notes/prior-work.md`, my decomp.me tests in `notes/compiler-tests.md`, the README of `7akeem0/albw-decomp-ai`.
   FENCE: Edit only `SCOPE.md` and `notes/`. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `Select-String -Path SCOPE.md -Pattern 'armcc|https://'` and paste the hits. `SCOPE.md` names the compiler build and default flags with proof, the match rule (byte or structure), the library code to skip, and milestone 1 with its check. Done means each claim has a URL or a test file.
   BUDGET: Stop after 45 minutes.
   IF BLOCKED: Stop. If no compiler build fits, say so plainly and list the builds you tried.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenSCOPE.md names one compiler build with test proof, and you approved it.

   Proof this works: https://github.com/7akeem0/albw-decomp-ai, https://github.com/zeldaret/oot3d, https://github.com/RedShyGuy/acnl-decomp

2. Set up the judge and calibrate it

   The judge compiles one source and compares it with the game's bytes. Set it up on Windows, since armcc is a Windows program. Then prove the judge can fail. A judge that always says MATCH is worse than none.

   • Put the armcc build at toolchain/armcc/<VERSION>/<BUILD>/bin/armcc.exe. That is where matching-decomp-tools looks. ALBW uses tools/armcc/4.1/b1049/bin/armcc.exe.
   • Install Python 3.10 or newer, then run pip install capstone.
   • Add Tsukimi-Labs/matching-decomp-tools as tools/, or write a small fn.py like ALBW's. Copy tools/project.example.toml to project.toml and fill in the versions, compiler and flags.
   • Put your own exheader.bin, exefs/code.bin and romfs/*.cro in orig/<VERSION>/, ignored by git.
   • Calibrate: check a tiny known function and expect RESULT: MATCH. Change one constant and expect DIFFER.
   Prompt for ClaudeCopy

   GOAL: Set up the matching judge for <GAME> and prove it can both pass and fail.
   READ FIRST: `SCOPE.md`, `tools/README.md`, `tools/CLAUDE.md` and `tools/project.example.toml` of `matching-decomp-tools`.
   FENCE: Edit only `project.toml`, `project.local.toml`, `.gitignore` and `notes/calibration.md`. Never commit the compiler or any game file. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `python -I tools/match.py check notes/calib/ok.cpp <ADDR>` and then on `notes/calib/broken.cpp`. Done means the first prints `RESULT: MATCH` and the second prints `DIFFER`, both pasted in `notes/calibration.md`.
   BUDGET: Stop after 45 minutes or 3 failed compiler runs.
   IF BLOCKED: Stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenThe judge prints MATCH for a known-good source and DIFFER for a broken one.

   Proof this works: https://github.com/Tsukimi-Labs/matching-decomp-tools, https://github.com/7akeem0/albw-decomp-ai, https://github.com/macabeus/asmlift/blob/main/.claude/commands/dogfood-klonoa.md

3. Map the binary: function table, classes and libraries

   List every function with its start, size and mode (ARM or Thumb). Mark library code so nobody matches it by hand. Read class names from the game's RTTI, which is C++ type data the compiler keeps.

   • Open the game in a Ghidra project. functable.py reads it through python -I tools/local/ghidra_server.py serve, which needs a Python with pyghidra.
   • Run python -I tools/refresh.py --table. It runs functable.py, rtti.py and ctors.py, then the other table steps. Fix hidden starts with tailstarts.py --apply and unreached.py --apply.
   • Read classify.py's output: it names each function's class, slot and library.
   • Mark sdk, nw, middleware and armlib rows as library code. Solstice decompiles only game code.
   • Put starts Ghidra misses in config/<VERSION>/extra_starts.txt. ALBW also kept a not_starts.txt.
   Prompt for ClaudeCopy

   GOAL: Build the function ledger for <GAME>: every function with start, end, mode, class and library.
   READ FIRST: `orig/<VERSION>/`, the output of `python -I tools/functable.py --census`, the tool docs in `tools/README.md`.
   FENCE: Edit only `config/<VERSION>/` and `notes/map.md`. Do not write any C source. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `python -I tools/progress.py`. Done means it reads the table with no errors, and `notes/map.md` gives counts by library and the share of Thumb code.
   BUDGET: Stop after 2 hours or 3 failed table builds.
   IF BLOCKED: Stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenfunctions.csv covers the whole binary, and progress.py reads it without errors.

   Proof this works: https://github.com/Tsukimi-Labs/Solstice, https://github.com/7akeem0/albw-decomp-ai, https://github.com/AlgebraManiacABC/3DS-Decomp-Pipeline

4. First light: match one small function end to end

   Prove the loop on one tiny function. Write the C++, run the judge, and commit only on MATCH. Now you know the compiler, flags and headers work together.

   • Pick a function under 64 bytes from the ledger.
   • Read it with python -I tools/match.py show <ADDR> 40.
   • Write it in src/main/<namespace>/<File>.cpp with a //! <ADDR> <symbol> line above it.
   • Run python -I tools/match.py check <file> <ADDR> --sym <symbol>.
   • Commit only when it prints RESULT: MATCH.
   Prompt for ClaudeCopy

   GOAL: Match function <ADDR> (<SIZE> bytes) of <GAME> in `src/main/<PATH>.cpp`.
   READ FIRST: `AGENTS.md`, `python -I tools/match.py show <ADDR> 40`, its row in `config/<VERSION>/functions.csv`, its class header.
   FENCE: Edit only `src/main/<PATH>.cpp`. Never write in a `generated/` folder. No weak declarations, `__schedule_barrier`, inline asm or dummy locals. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `python -I tools/match.py check src/main/<PATH>.cpp <ADDR> --sym <SYMBOL>`. Done means it prints `RESULT: MATCH`.
   BUDGET: Stop after 8 checks with no progress. Leave the best source with a comment on what differs.
   IF BLOCKED: Stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenOne function prints RESULT: MATCH and is committed.

   Proof this works: https://github.com/Tsukimi-Labs/Solstice/blob/master/AGENTS.md, https://github.com/7akeem0/albw-decomp-ai

5. Take the free wins before spending tokens

   Tools can write some functions with no AI at all. Small functions, empty destructors and twins come first. A twin is a function with the same code as one you already matched.

   • Run python -I tools/refresh.py --derive. It writes tiny functions, destructors and twins into generated/ folders.
   • Run twins.py --apply after every batch. Solstice and ALBW both gained whole families this way.
   • Pick the next hand-written function from the top of build/<VERSION>/twins.txt. One match there unlocks a family.
   • Batch compile many files in one call. ALBW found it about 20 times faster.
   Prompt for ClaudeCopy

   GOAL: Run the machine-only stages for <GAME> and report how many functions they matched.
   READ FIRST: `CLAUDE.md`, `tools/README.md`.
   FENCE: Run only `refresh.py`, `twins.py`, `progress.py` and `honest.py`. Edit nothing by hand. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `python -I tools/progress.py` before and after. Done means you paste both counts and `honest.py` reports no new tricks.
   BUDGET: Stop after 60 minutes.
   IF BLOCKED: Stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenprogress.py shows the new count, and honest.py is clean.

   Proof this works: https://github.com/Tsukimi-Labs/matching-decomp-tools, https://github.com/7akeem0/albw-decomp-ai/blob/master/docs/LESSONS.md

6. Grind: many workers, one batch of functions each

   Now hand out functions in small batches. Each worker gets a packet and runs only the judge. Size sets the batch: many tiny ones, or one big one. Every merge reruns the judge on the merged branch.

   • Make packets with python -I tools/local/packets.py --name <BATCH>. A packet gives each function's address, its declaration, its --sym name and the members it uses.
   • Give each worker its own git worktree, for example claude -w batch-<N>. A new worktree lacks ignored folders like orig/ and toolchain/, so list them in .worktreeinclude or the worktree.symlinkDirectories setting.
   • Functions of 17 to 256 bytes go 10 to 15 per worker. Functions of 257 to 1,024 bytes go 1 to 3. Bigger ones go 1 per worker.
   • Stop each function after 8 checks without progress. Record what was tried.
   • After merging, run progress.py, twins.py --apply and honest.py on the main branch.
   Prompt for ClaudeCopy

   GOAL: Match the functions in packet <PACKET_FILE> of <GAME>.
   READ FIRST: `AGENTS.md` (all of it), the packet, the class headers it names.
   FENCE: Edit only the source files the packet names. Run `tools/match.py` and nothing else. Never edit a header that starts with `// generated by tools/headers.py`; report header fixes instead. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: For each function run `python -I tools/match.py check <file> <where> --sym <symbol>`. Done means each function is reported as MATCH or open, one line each.
   BUDGET: Stop each function after 8 checks with no progress. Stop the batch after 90 minutes.
   IF BLOCKED: Stop. Report the function, the best diff and what you tried. Do not reach for a trick.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: One line per function: `<where> <status> <file>`, then any header problems you found.

   Done whenEvery packet function is MATCH or open with notes, and the merged branch passes progress.py and honest.py.

   Proof this works: https://github.com/Tsukimi-Labs/Solstice/blob/master/CLAUDE.md, https://github.com/7akeem0/albw-decomp-ai, https://bytematch.dev/mhvuze/mh4u-decomp, https://code.claude.com/docs/en/worktrees.md

7. Crack the hard tail with shared headers

   The last third is hard on 3DS games. ALBW found the main blocker: small inline helpers from the game's headers. Fix a helper once in a shared header, and many functions match. Per-function flags matter too.

   • Collect the open functions that share a helper, such as a constructor or a setter.
   • Write the helper once in include/, and check it against every function that uses it. Remove a header's // generated by tools/headers.py line first, or the tool rewrites it.
   • Try per-function flags. About 850 ALBW functions needed --apcs=/fpic, which stops tail calls.
   • Turn hack matches into honest ones. ALBW removed about 76 needless barriers or dummy locals.
   • Write each compiler rule you prove into notes/compiler-quirks.md, never per-function notes.
   Prompt for ClaudeCopy

   GOAL: Find the inline helper behind open functions <LIST> of <GAME> and write it once in a shared header.
   READ FIRST: `docs/LESSONS.md` of ALBW, `notes/compiler-quirks.md`, the open functions' best sources and diffs.
   FENCE: Edit only `include/<HEADER>.h` and the listed sources. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `python -I tools/match.py check` on every listed function and `python -I tools/honest.py`. Done means more functions match than before and none that matched now fails.
   BUDGET: Stop after 2 hours or 15 header tries.
   IF BLOCKED: Stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenThe header change raises the match count and breaks no earlier match.

   Proof this works: https://github.com/7akeem0/albw-decomp-ai/blob/master/docs/LESSONS.md, https://github.com/Tsukimi-Labs/Solstice

8. Harden: link the whole binary and audit relocations

   A function-level match is evidence, not the verdict. Link everything and compare the whole code.bin hash. Audit relocations too, because a call to the wrong function can still look matched.

   • With 3DS-Decomp-Pipeline, run python main.py <DIR> --skip-split --recreate-binaries. It links, rebuilds the binary and checks its SHA-256.
   • Or follow zeldaret/oot3d: cmake -B build -S . -G "Unix Makefiles", then cmake --build build -t check, which prints build/code.bin: OK.
   • Run a relocation identity audit. ALBW removed 419 false matches this way.
   • Make an objdiff report with python -I tools/objexport.py --report. Sites like decomp.dev and bytematch.dev show progress from these reports.
   Prompt for ClaudeCopy

   GOAL: Link <GAME> from matched sources plus the split originals and compare the full `code.bin` hash.
   READ FIRST: `CLAUDE.md`, the pipeline README, `notes/calibration.md`.
   FENCE: Edit only the build config and `notes/`. Never edit expected hashes or the judge. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `python main.py <DIR> --skip-split --recreate-binaries`, or `cmake --build build -t check` in an OoT3D-style repo. Done means the rebuilt `code.bin` has the original SHA-256, and the relocation audit lists zero wrong targets.
   BUDGET: Stop after 2 hours.
   IF BLOCKED: Stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenThe rebuilt code.bin hash equals the original, and the relocation audit is clean.

   Proof this works: https://github.com/zeldaret/oot3d, https://github.com/AlgebraManiacABC/3DS-Decomp-Pipeline, https://github.com/7akeem0/albw-decomp-ai

9. Port: run the decomp on a PC

   Nobody has done this for a 3DS game yet. Plan it as a new runtime under the decomp. The runtime replaces the nn SDK calls, the GPU and the sound with PC parts. The recomp runtimes show what that takes.

   • Compile the matched source with a PC compiler. Fix 64-bit pointer problems one class at a time.
   • Put the SDK calls behind one interface. Use Zakuro or the Clockwork runtime as a model for kernel, services, PICA200 and DSP.
   • Note that TriAevum built a source-native route for Ocarina of Time 3D, then removed it on 2026-10-03.
   • Reuse your Path A golden runs as the check for the port.
   Prompt for ClaudeCopy

   GOAL: Write a port plan for <GAME> from the decomp to Windows, with one first milestone.
   READ FIRST: `SCOPE.md`, `notes/map.md`, the `Zakuro` and `Clockwork` READMEs, `docs/port.md` of `3dsrecomp`.
   FENCE: Edit only `notes/port-plan.md`. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
   CHECK: Run `python -I tools/progress.py` and put its totals at the top of the plan. Done means the plan lists every SDK area to replace, names what each Path A golden run will prove, and states plainly what is not known yet.
   BUDGET: Stop after 60 minutes.
   IF BLOCKED: Stop. If the decomp is too incomplete to port, say so with the numbers from `progress.py`.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenThe port plan is approved, and its first milestone passes a Path A golden run on the PC build.

   Proof this works: TriAevum: Echoes of Time, https://github.com/watchmakerers/clockwork, https://github.com/fearkov/zakuro

Tools you need

Skills and add-ons

Read any skill before you install it. A skill is a set of instructions that Claude will follow. See Tools and Skills for the full list and safety notes.

Claude setup for this system

For Path A, one card is one crash, one hang, one missed function or one bad scene. Each card names the golden run that shows it. A PC feature is its own card with its own setting. For Path B, one card is one packet: up to 15 tiny functions, or one big one. A script picks the next packet from the ledger and the twins list, not Claude.

Which model and effort for each job

The model and effort names come from one shared table, so they stay the same on every guide. See Claude Setup for the reasons.

How many sessions at once

Lines for this project's CLAUDE.md

- Read `SCOPE.md` and `PROGRESS.md` at the start of every session.
- The one check is `powershell -NoProfile -ExecutionPolicy Bypass -File tools/check.ps1` (Path A) or `python -I tools/match.py check` (Path B). Do not report DONE until it passes; paste its output.
- Never edit generated C in `out/` or any `generated/` folder. Fix it with `hints.txt`, an override or a patch, then rebuild.
- Nothing made from the game goes into git: the dump, generated C, `librecomp.a`, saves, shader caches, texture or frame dumps.
- `run/` is my play folder. Tests run from `test/` only. Never stop game processes by name; stop only the one you started.
- A service you do not know must stop with a named error. Never return fake success to get past a hang.
- Matched means the judge prints `RESULT: MATCH`. Never claim a match from reading a diff.
- No weak declarations, `__schedule_barrier`, inline asm, or dummy or volatile locals to force a match. An honest miss beats a hack.
- `honest_allow.txt`, flag sets and expected hashes are mine. Propose changes; do not edit them.
- In a worktree, use absolute paths in every command.
- Never build with more than `-j <N>`. MSR2DS set 8, because its PC reset under all-core builds.
- When you fix a real bug, write `notes/bugs/<ID>.md` with symptom, cause, fix and the golden run that proves it.
- Do not send pull requests to `3dsrecomp` or `Zakuro` without my review; they discard code that is entirely vibecoded. Commit or push only when I ask.

Keep the context small

• Give Claude an address and a file path, not pasted disassembly. Let it run match.py show or ask Ghidra itself.
• Keep build logs in files. Ask for the last 50 lines or a grep, never the whole 25-minute log.
• Hand each worker AGENTS.md and its packet only. Solstice found that a decompiler's C in the packet did not help.
• Start a fresh session for each ledger row or packet. State lives in notes/ledger.csv and PROGRESS.md.
• Keep CLAUDE.md short. Put proven compiler rules in notes/compiler-quirks.md and point to it.

More prompts for this system

Each step above has its own prompt. These extra prompts cover the rest of the work. Fill in the parts in <ANGLE_BRACKETS>.

GOAL: Tell me if <GAME> (<REGION>, title ID <TITLE_ID>, SHA-256 <HASH>) can be recompiled with `3dsrecomp` and `Zakuro`, and whether a decomp exists.
READ FIRST: `notes/prior-work.md`, the `Zakuro` `COMPATIBILITY.md`, RecompLauncher, GitHub results for `<GAME> recomp` and `<GAME> decomp`.
FENCE: Edit only `SCOPE.md` (draft) and `notes/prior-work.md`. Do not open or copy the dump. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Run `Select-String -Path SCOPE.md -Pattern 'https://'` and paste the hits. Done means `SCOPE.md` names one technique, lists prior work with URLs, gives the region and title ID, and lists the three biggest risks (CRO modules, data-pointer functions, region lock).
BUDGET: Stop after 40 minutes.
IF BLOCKED: Stop. Say what you could not find. Do not guess facts.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the URLs. 3) Files changed. 4) What is left. 5) New parking-lot items.

GOAL: Write `config/<VERSION>/functions.csv` for <GAME>: start, end, mode, class, library for every function in `code.bin` and each `.cro`.
READ FIRST: `orig/<VERSION>/`, the output of `python -I tools/functable.py --census`, the RTTI tools' output.
FENCE: Edit only `config/<VERSION>/` and `notes/map.md`. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Run `python -I tools/progress.py`. Done means it loads the table with no errors and `notes/map.md` gives counts by library and by mode.
BUDGET: Stop after 2 hours.
IF BLOCKED: Stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

GOAL: Find and fix the cause of ledger row <ID> (<SYMPTOM>) in <GAME>.
READ FIRST: `notes/ledger.csv` row <ID>, `logs/<RUN>.txt`, `CLAUDE.md`.
FENCE: Edit only `patches/`, `overrides/` and `notes/bugs/<ID>.md`. Never edit generated C. Never fake a service reply. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Run `tools/check.ps1`. Done means the row's golden run passes and all older runs still pass.
BUDGET: Stop after 4 failed fixes or 60 minutes with no new evidence.
IF BLOCKED: Stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

GOAL: Match function <WHERE> of <GAME>.
READ FIRST: `AGENTS.md`, `python -I tools/match.py show <WHERE> 40`, the function's class header.
FENCE: Edit only `<SOURCE_FILE>`. Run `tools/match.py` and nothing else. No banned tricks. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Run `python -I tools/match.py check <SOURCE_FILE> <WHERE> --sym <SYMBOL>`. Done means `RESULT: MATCH`.
BUDGET: Stop after 8 checks with no progress.
IF BLOCKED: Stop. Leave the best source with a comment saying what differs and what you tried.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: One line: `<WHERE> <MATCH or open> <file>`, then any header problem you found.

GOAL: Hand out the next <N> packets for <GAME> to <N> workers, one worktree each.
READ FIRST: `CLAUDE.md`, `build/<VERSION>/twins.txt`, the output of `python -I tools/progress.py`.
FENCE: Edit only `notes/dispatch-<DATE>.md`. Workers edit only the files in their packet. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: On the merged branch, run `python -I tools/progress.py`, `python -I tools/twins.py --apply`, then `python -I tools/honest.py`. Done means each worker reported, the merged branch passes `progress.py` and `honest.py`, and `twins.py --apply` ran after the merge.
BUDGET: Stop the round after 2 hours. Merge only what passed.
IF BLOCKED: Stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

GOAL: Find the cause of <SYMPTOM> in <SCENE> of <GAME>. Do not fix it yet.
READ FIRST: `logs/<RUN>.txt`, the same scene recorded in Azahar at <RECORDING>, `notes/bugs/` for similar past bugs.
FENCE: Edit only `notes/bugs/<ID>.md` and throwaway probe builds in `scratch/`. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Run the probe or golden run the note names, and paste its output. It must show the symptom now. Done means the note names one cause, with a log line, a trace or a frame compare that proves it, and one test that would show the fix works.
BUDGET: Stop after 90 minutes or 5 dead ends. Write each dead end in the note.
IF BLOCKED: Stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

GOAL: Check that the work in commits <RANGE> of <GAME> is real.
READ FIRST: `CLAUDE.md`, `git log <RANGE>`, `git diff <RANGE>`.
FENCE: Edit only `notes/verify-<DATE>.md`. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Rerun `tools/check.ps1` or `python -I tools/progress.py` and `python -I tools/honest.py` yourself. Done means you list any edited generated C, fake service returns, edited hashes, weak or barrier tricks, stubs, or files outside the fence.
BUDGET: Stop after 60 minutes.
IF BLOCKED: Stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

GOAL: Write a status report for <GAME> from the ledgers only.
READ FIRST: `PROGRESS.md`, `notes/ledger.csv`, `python -I tools/progress.py` output, `notes/parking-lot.md`.
FENCE: Edit only `notes/status-<DATE>.md`. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Run `python -I tools/progress.py` (Path B) or `tools/check.ps1` (Path A) and use only its numbers. Done means every number has its source file, and the report fits on one screen: done, open, blocked, next three cards.
BUDGET: Stop after 20 minutes.
IF BLOCKED: Stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

GOAL: Write down what the next session needs to carry on with <GAME>.
READ FIRST: `PROGRESS.md`, `git log -10`, `notes/ledger.csv`.
FENCE: Edit only `PROGRESS.md` and `notes/handoff.md`. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Run `git status --short` and `git log -1 --oneline`, and paste both. Done means every changed file is listed and `notes/handoff.md` says what works, what is in progress, the exact next command, the open questions, and the pinned tool commits.
BUDGET: Stop after 15 minutes.
IF BLOCKED: Stop. Do not work around it. Tell me what blocked you, what you tried, and what you need from me.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

GOAL: Tell me plainly if <TASK> on <GAME> can be done with the tools we have.
READ FIRST: `notes/bugs/<ID>.md` or the function's notes, `notes/compiler-quirks.md`.
FENCE: Edit only `notes/blocked-<ID>.md`. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Run the failing check once more and paste its output. Done means the note says CAN, CANNOT or UNKNOWN, gives the evidence, and lists at most three options with their cost.
BUDGET: Stop after 30 minutes.
IF BLOCKED: Say BLOCKED and list what you need from me.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

GOAL: Ask me before you leave the fence for <TASK>.
READ FIRST: `SCOPE.md`, `notes/parking-lot.md`.
FENCE: Edit only `notes/scope-request-<DATE>.md`. Change no code. Everything else is read-only. Do not add features, refactors, tools or cleanups I did not ask for.
CHECK: Run `git status --short`. Done means it shows only the new note, and the note says what you want to change, why, which files, the risk, and how we would check it.
BUDGET: Stop after 15 minutes.
IF BLOCKED: Stop and wait for my yes or no.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

Keep Claude on task

These are the detours Claude tends to take on this system, and the rule that stops each one. The full method is on Stay on Task.

Problems other projects hit

How long it takes

What makes it faster or slower

• Whether 3dsrecomp and Zakuro already run your game. If they do, you start at the title screen on day one.
• How much code hides behind data pointers and CRO modules. Each missed function needs a hint.
• How much PC work you want: one-screen layout, widescreen and HUD changes took most of the time in DekUI and Dragon Quest VIII.
• Game size for Path B: 26,000 to 61,000 functions in the 3DS decomps we found.
• Access to the exact armcc build. Without it, byte matching is not possible.
• Whether you build golden runs early. Without them, every check needs you at the controller.

The facts behind these numbers

Projects reviewed (10)

We took the top-starred project for each of the 10 games RecompLauncher lists for the 3DS. Two second projects for the same games were left out. None is a matching decomp, so Path B uses the 3DS decomps we found on GitHub, listed under sources.

What each project teaches

What we could not check

• The time ranges are estimates. No project reports hours per week, and private work before each first commit is unknown.
• No 3DS game has a finished matching decomp, and none has been ported from a decomp. The Path B port step is a plan, not a proven road.
• How a hobbyist can get a legal copy of armcc is not settled. ALBW asks for your own licensed copy. matching-decomp-tools uses decomp.me's public armcc.zip; we did not check its licence terms.
• The install steps for ghidra-ctr-loader are not in its README, and it was last updated in January 2024. It has no release; whether it builds against Ghidra 12 is unknown. We did not test it.
• We did not run 3dsrecomp, Zakuro or ctrtool ourselves. Commands come from their READMEs, their source code (src/main.rs, cli.rs, lib.rs) and the project cards.
• The Solstice tool names packets.py, functable.py and the RTTI tools come from its docs. We did not run them.
• GhidraMCP asks for Ghidra 12.1.4, so the guide says to use that version with it. We did not test it with 12.2.
• Whether AI was used on Shin Megami Tensei IV Recomp, Luigi's Mansion 2 and the MH4U decomp is not stated in their repos.
• The 60 fps speed-up rule applies to the games tested by the Zakuro author and by Shin Megami Tensei IV. Other games may differ.
• We could not read 3dbrew with our web tool, so we read its raw wiki text instead.
• Zakuro's --headless report and its ZAKURO_RECORD and ZAKURO_REPLAY switches come from its source code. No reviewed project shows them in use.
• decomp.me answered 403 to our scripted check, so its 3DS compiler list was read from its GitHub source instead.
• The Solstice packet sizes come from its CLAUDE.md, measured on its own project. Other games may need other sizes.

Sources

• 3dsrecomp README
• 3dsrecomp overrides doc
• 3dsrecomp port doc
• Zakuro README
• Clockwork README
• 3dbrew: NCCH
• 3dbrew: NCSD
• 3dbrew: ExeFS
• 3dbrew: CRO0
• 3dbrew: Hardware
• ctrtool README (Project_CTR)
• GodMode9 README
• Azahar README
• decomp.me 3DS platform
• decomp.me compiler list
• A Link Between Worlds decomp README
• A Link Between Worlds decomp lessons
• Solstice CLAUDE.md
• Solstice AGENTS.md
• matching-decomp-tools README
• zeldaret/oot3d README
• Monster Hunter 4 Ultimate decomp progress
• Animal Crossing: New Leaf decomp README
• 3DS-Decomp-Pipeline README
• objdiff README
• Ghidra README
• ghidra-ctr-loader README
• GhidraMCP README
• MSYS2 home page
• Zig downloads
• Capstone on PyPI
• Unicorn on PyPI
• 3dsrecomp command line (src/main.rs)
• Zakuro command line (cli.rs)
• Zakuro compatibility list
• matching-decomp-tools CLAUDE.md
• decomp.me compilers release (armcc.zip)
• A Link Between Worlds decomp AGENTS.md
• Solstice progress history
• Ghidra 12.1.4 release
• 3DS custom firmware guide (linked by GodMode9)
• Claude Code worktrees