Sega 32X decomp guide

What this system is like

The 32X plugs into the top of a Genesis. It adds two Hitachi SH-2 chips, a frame buffer and new sound. The Genesis 68000 and Z80 still run too. So one game uses four processors of three kinds.

Path A has public source for one game. Chaotix Recompiled turned Knuckles' Chaotix into native C++. It reached a playable release five days after its first public commit. Its handbook says Claude co-wrote 228 of its 264 commits. A second Chaotix recomp reached a finished level in its first week. There is no shared 32X recompiler, so you build your own, as both Chaotix projects did.

Path B has never been finished for any 32X game. Byte-exact disassemblies were made for Virtua Racing Deluxe and for parts of Knuckles' Chaotix. The Virtua Racing one later changed the game on purpose, so it no longer matches. A Doom rebuild in C stalled in 2024. So Path B here is new ground, and this guide says where it is guesswork.

Most Path A work runs on Windows with MSYS2 or Visual Studio. Some Path B tools want Linux, so keep WSL ready. Expect weeks for Path A and the better part of a year for Path B.

Two paths

Path A: Get it running on PC

First you write simple interpreters for the 68000, SH-2 and Z80. They are the answer key. Then a recompiler turns the game's code into C++ ahead of time. Code it misses falls back to the interpreter. You run both side by side every frame. Any difference points at one bad instruction or one hardware rule.

1. Pick the game and write the scope

   You pin the exact ROM by hash. A different revision is a different program. Then you read both headers and look for prior work. A disassembly can save you weeks of mapping.

   • In WSL, hash your own dump: sha1sum <ABSOLUTE_PATH_TO_ROM>.
   • Read both headers with Python: python3 -c "d=open('<ABSOLUTE_PATH_TO_ROM>','rb').read();print(len(d),d[0x100:0x110],d[0x150:0x180],d[0x1F0:0x1F3],d[0x3C0:0x3D0],[hex(int.from_bytes(d[o:o+4],'big')) for o in range(0x3D4,0x3F0,4)])".
   • Check that $100 says SEGA 32X. The seven numbers are the SH-2 copy source, destination, size, both start addresses and both vector bases.
   • Search RecompLauncher and GitHub for your game. Check sonicretro/chaotix, matiaszanolli/sega-vr-disasm and nukeykt/Doom32x-RE if your game is one of those three.
   • Write SCOPE.md: game, region, SHA-1, size, header fields, goal, technique, first milestone and its check, and what is out of scope.
   Prompt for ClaudeCopy

   GOAL: Draft SCOPE.md for a 32X static recomp of <GAME> (<REGION>).
   READ FIRST: bytes $100-$1FF and $3C0-$3EF of `<ABSOLUTE_PATH_TO_ROM>` (read only), https://plutiedev.com/rom-header, https://github.com/viciious/32XDK/blob/main/docs/32x-hardware-manual.md (section 5.1 Boot ROM)
   FENCE: Create only `SCOPE.md` and `notes/prior-work.md`. Do not copy or move the ROM. Do not write code.
   CHECK: Run `sha1sum <ABSOLUTE_PATH_TO_ROM>` and paste it. Done means SCOPE.md has the SHA-1, size, `SEGA 32X` system field, title, region, the seven user header values in hex, prior work with links, the first milestone and its check, and an out-of-scope list.
   BUDGET: Stop after 30 minutes of searching for prior work.
   IF BLOCKED: Stop. Do not guess a revision or a hash. Tell me what is missing.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the hash and header values. 3) Files changed. 4) Prior work found, with links. 5) New parking-lot items.

   Done whenSCOPE.md names the ROM by SHA-1 and size, lists the user header values and prior work, and you approved it.

   Proof this works: Chaotix Recompiled (rejects any ROM but one SHA-1), s32xfan/virtuaracing (pins one SHA-256 and revision), https://github.com/viciious/32XDK/blob/main/docs/32x-hardware-manual.md

2. Set up the repo, the build and the one check

   You lay out a repo like Chaotix Recompiled's. The ROM and the generated code stay out of git. One command builds and runs every test. CI builds without the ROM, so it can only check the interpreter and unit tests.

   • Install MSYS2 from msys2.org. In the MinGW64 shell run pacman -S mingw-w64-x86_64-{gcc,cmake,ninja,sdl3,sdl3-ttf} git python.
   • Make folders like Chaotix's: src/cpu, src/runtime, tools/recompiler, tools/rom_analyzer, coverage, generated, tests/golden.
   • Add *.32x, *.bin, generated/ and build/ to .gitignore before the ROM is near the repo.
   • Pass the ROM as a CMake setting, as Chaotix does with CHAOTIX_ROM: cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Release -DGAME_ROM=<ABSOLUTE_PATH_TO_ROM>.
   • In the MSYS2 shell, give the ROM path in Windows form. Chaotix's README says to use cygpath -m <ROM_PATH>.
   • Make the one check: cmake --build build && (cd build && ctest --output-on-failure).
   • Add a CI job that fails if a large file or anything under generated/ is tracked. Chaotix caps files at 512 KB.
   Prompt for ClaudeCopy

   GOAL: Set up the <GAME> recomp repo with a CMake build and one check command.
   READ FIRST: SCOPE.md, the README and CMakeLists.txt of https://github.com/YuutaTsubasa/ChaotixRecompiled (layout and Build section only)
   FENCE: Edit only files in this repo. Do not write CPU or game code yet. Do not add features.
   CHECK: Run `cmake -S . -B build -G Ninja -DGAME_ROM=<ABSOLUTE_PATH_TO_ROM>` then `cmake --build build && (cd build && ctest --output-on-failure)`. Done means it builds an empty program, ctest runs one placeholder test, and `git status` shows no ROM and nothing under `generated/`.
   BUDGET: Stop after 3 failed builds of the same error.
   IF BLOCKED: Stop. Paste the exact error. Do not switch compilers or install tools without asking.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the build tail and ctest output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenThe one check command builds and runs ctest, and git status shows no ROM and no generated code.

   Proof this works: Chaotix Recompiled (CMake, Ninja, MSYS2, ROM-free CI), https://www.msys2.org/

3. Build the answer key: three small interpreters

   Before you recompile anything, you need something to compare against. Chaotix wrote its own 68000, SH-2 and Z80 interpreters first. Each instruction's meaning lives in one shared header. The interpreter and the generated code both use it, so they cannot drift apart.

   • Put SH-2 instruction meanings in src/cpu/sh2_ops.h and 68000 ones in src/cpu/m68k_ops.h. Or link Musashi for the 68000, as knuckles-chaotix-recomp did.
   • In WSL, install a reference disassembler: sudo apt install binutils-sh-elf binutils-m68k-linux-gnu.
   • Check your SH-2 decoder against sh-elf-objdump on all 65,536 possible instruction words. knuckles-chaotix-recomp found 53,752 valid ones that all agreed.
   • Write unit tests from the CPU manuals. Chaotix started with 33.
   • Fake the boot in code. Copy the bytes the user header names into SDRAM. Set both SH-2 start addresses. Write M_OK and S_OK to the COMM ports.
   Prompt for ClaudeCopy

   GOAL: Write the SH-2 reference interpreter for <GAME> with its decoder checked against sh-elf-objdump.
   READ FIRST: SCOPE.md, https://github.com/viciious/32XDK/blob/main/docs/sh1-sh2-cpu-core-architecture.md, the 'How correctness is established' section of https://github.com/Flinnz/knuckles-chaotix-recomp
   FENCE: Edit only `src/cpu/sh2_*`, `tests/cpu/` and `tools/validate_sh2.py`. Do not touch the 68000 or runtime code.
   CHECK: Run `python3 tools/validate_sh2.py` in WSL and `cmake --build build && (cd build && ctest --output-on-failure)`. Done means every one of the 65,536 words decodes the same as `sh-elf-objdump`, and all SH-2 unit tests pass.
   BUDGET: Stop after 4 hours, or 3 failed tries on the same instruction.
   IF BLOCKED: Stop. List the opcodes that disagree with both outputs.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the validator summary and ctest output. 3) Files changed. 4) Instructions not yet covered by a test. 5) New parking-lot items.

   Done whenThe SH-2 decoder agrees with sh-elf-objdump on all 65,536 words, and the interpreter boots the game to its first 32X picture.

   Proof this works: Chaotix Recompiled (shared semantics headers, 33 CPU unit tests, boot done in code), knuckles-chaotix-recomp (decoder checked against sh-elf-objdump)

4. Map the code for both CPU types

   The recompiler must know where code is. You start from the 68000 reset vector and the two SH-2 start addresses. You follow calls, branches and jump tables. Then you record which addresses really run during play, to catch code reached through pointers.

   • Write an analyzer that walks code from every known entry point and decodes jump tables. Chaotix calls this rom_analyzer.
   • Map SH-2 code at its SDRAM address, not its ROM offset. sega-vr-disasm notes SH-2 $0600xxxx came from ROM offset $20000 plus xxxx in its game.
   • Prove the map by round trip: reassemble your listing and compare it with the ROM. knuckles-chaotix-recomp got all 3,145,728 bytes back.
   • Record coverage from play sessions into coverage/*.cov. These files hold addresses only, never ROM bytes.
   • Cross-check doubtful spots in Ghidra. Import the ROM as raw binary with language SuperH:BE:32:SH-2 at base $02000000.
   • Write notes/functions.csv with CPU, address, size, proof and a status column.
   Prompt for ClaudeCopy

   GOAL: Build the first code map of <GAME> for the 68000 and both SH-2s.
   READ FIRST: SCOPE.md (user header values), https://github.com/matiaszanolli/sega-vr-disasm/blob/master/CLAUDE.md (ROM Address Mapping), notes/prior-work.md
   FENCE: Edit only `tools/rom_analyzer/`, `notes/functions.csv` and `coverage/`. Do not write the recompiler yet. Never write ROM bytes into the repo.
   CHECK: Run `<ANALYZER_EXE> --rom <ABSOLUTE_PATH_TO_ROM> --out out/map` then `python3 tools/roundtrip.py`. Done means the round trip rebuilds the mapped spans byte for byte, and every row in functions.csv names its proof (entry point, jump table or coverage hit).
   BUDGET: Stop after 3 hours, or 3 failed round trips on the same span.
   IF BLOCKED: Stop. List the address ranges you could not classify.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: round-trip output and function counts per CPU. 3) Files changed. 4) Unclassified ranges. 5) New parking-lot items.

   Done whennotes/functions.csv lists every routine for both CPU types with its proof, and the round trip rebuilds the mapped bytes exactly.

   Proof this works: Chaotix Recompiled (rom_analyzer, coverage/*.cov), knuckles-chaotix-recomp (247 SH-2 and 4,491 68000 functions, whole-cartridge round trip), sega-vr-disasm (ROM-to-CPU address rules)

5. First light: recompile and boot in lockstep

   Now the recompiler turns each block into C++, with the original instruction as a comment. Anything it cannot handle drops to the interpreter. That is slower but never wrong. You boot both builds side by side and compare every frame.

   • Generate: <RECOMP_EXE> --rom <ABSOLUTE_PATH_TO_ROM> --coverage coverage/boot.cov --out generated. Chaotix's tool is chaotix_recomp.
   • Build with the one check command. Never edit anything in generated/.
   • Run headless in lockstep, like chaotix_headless --rom <ABSOLUTE_PATH_TO_ROM> --frames 600 --lockstep. It compares registers, RAM, VRAM and the 32X frame buffer.
   • Save a screenshot of the first frame with --shot and look at it yourself.
   • Write the fallback count and the result in PROGRESS.md.
   Prompt for ClaudeCopy

   GOAL: Recompile <GAME> and boot it to the SEGA logo with lockstep passing.
   READ FIRST: SCOPE.md, PROGRESS.md, notes/functions.csv, the Tools section of https://github.com/YuutaTsubasa/ChaotixRecompiled
   FENCE: Edit only `tools/recompiler/`, `src/runtime/dispatch*` and `CMakeLists.txt`. Never edit `generated/`. Do not stub any hardware access.
   CHECK: Run the one check, then `<HEADLESS_EXE> --rom <ABSOLUTE_PATH_TO_ROM> --frames 600 --lockstep --shot out/first.png`. Done means 600 frames with zero lockstep differences and a picture I can see.
   BUDGET: Stop after 4 failed builds, or 2 hours without a new frame.
   IF BLOCKED: Stop. Paste the first differing frame, register and value. Do not hide a difference by skipping it.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: lockstep output and screenshot path. 3) Files changed. 4) Fallback count. 5) New parking-lot items.

   Done whenA headless run shows the first 32X picture, with zero lockstep differences for 600 frames.

   Proof this works: Chaotix Recompiled (lockstep, 3,200 frames boot to level), knuckles-chaotix-recomp (draws the SEGA logo; --xcheck)

6. Close code gaps and RAM code

   Each fallback is code the recompiler did not cover. Some is real code in RAM: SH-2 code in SDRAM or cache, and 68000 jump stubs. You handle each gap at its cause. One unit is one fallback address.

   • After each run, list fallback addresses with their counts.
   • For each one, decide: missed function start, jump table target, RAM code, or self-modifying write.
   • For a missed start, add proof to the map or record a new coverage session.
   • For RAM code, check its bytes against the ROM at run time. Chaotix keeps a code epoch counter and drops to the interpreter when the code changes.
   • Track writes per function, not globally. Chaotix cut 4,049,824 checks to 75 over 3,000 frames this way.
   • Measure native coverage on a play session you did not use for coverage. Chaotix reached 99.7 to 100% for the 68000 and 100% for the SH-2.
   Prompt for ClaudeCopy

   GOAL: Remove fallback address <ADDRESS> (<CPU>) from <GAME>'s recompiled build.
   READ FIRST: CLAUDE.md, `out/fallbacks.txt`, the listing at <ADDRESS>, notes/functions.csv
   FENCE: Edit only `tools/recompiler/`, `tools/rom_analyzer/`, `coverage/` and notes/functions.csv. Never edit `generated/`. Never add an address only because a log names it.
   CHECK: Regenerate, run the one check, then `<HEADLESS_EXE> --rom <ABSOLUTE_PATH_TO_ROM> --replay-input tests/inputs/<RUN> --lockstep`. Done means <ADDRESS> no longer falls back, lockstep has zero differences, and no new fallback appears.
   BUDGET: Stop after 3 failed tries or 45 minutes.
   IF BLOCKED: Stop. Paste the listing and say which kind of gap it is.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: fallback counts before and after, lockstep output. 3) Files changed. 4) Kind of gap and cause. 5) New parking-lot items.

   Done whenFallbacks are zero on recorded sessions, except proven RAM code. Native coverage on a held-out session is written in PROGRESS.md.

   Proof this works: Chaotix Recompiled (code epoch counter, per-function write tracking, held-out coverage), knuckles-chaotix-recomp (44 missed 68000 addresses, VBlank handler reached by a RAM pointer)

7. Build the 32X hardware layer and timing

   The runtime stands in for the 32X and the Genesis. It needs the 32X VDP modes, the COMM ports, PWM sound, timers and the Genesis chips. Timing between four CPUs is the hard part. Each fix gets a lockstep run behind it.

   • Run all CPUs off one clock and slice each scanline. Chaotix uses four slices. knuckles-chaotix-recomp uses sixteen.
   • Model the COMM ports exactly. Read the hazards in sega-vr-disasm's COMM_REGISTERS_HARDWARE_ANALYSIS.md first.
   • Fast-forward idle loops only when the result is exact. Chaotix does this for COMM polls and V-blank waits.
   • Run the Z80 up to the 68000's time before the 68000 reads sound state. That fixed Chaotix's silent sound test.
   • Use Nuked-OPN2 or your own YM2612 code for FM music, as knuckles-chaotix-recomp did.
   • At each milestone, compare a screenshot with PicoDrive in BizHawk 2.11.1. Your interpreter is not proof of real hardware.
   Prompt for ClaudeCopy

   GOAL: Fix hardware behaviour <SYMPTOM> in the <GAME> runtime (<SUBSYSTEM>: VDP, COMM, PWM, Z80 or timers).
   READ FIRST: CLAUDE.md, `notes/hardware-facts.md`, the matching section of https://github.com/viciious/32XDK/blob/main/docs/32x-hardware-manual.md
   FENCE: Edit only `src/runtime/<SUBSYSTEM>*` and `notes/hardware-facts.md`. Never edit `generated/` or `tests/golden/`.
   CHECK: Run the one check with long tests on, then `<HEADLESS_EXE> --rom <ABSOLUTE_PATH_TO_ROM> --replay-input tests/inputs/<RUN> --lockstep --shot out/<RUN>.png`. Done means lockstep stays clean, the golden hashes still match, and the symptom is gone in the screenshot or WAV.
   BUDGET: Stop after 2 fix tries that do not change the result.
   IF BLOCKED: Stop. Cite the manual line you relied on and what the run showed instead.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: check output and file paths. 3) Files changed. 4) The hardware rule, with its source. 5) New parking-lot items.

   Done whenA full level plays with sound, lockstep stays clean on every recorded session, and a person signed off the play test.

   Proof this works: Chaotix Recompiled (issue #50 Z80 fix, exact idle fast-forward, four slices per scanline), knuckles-chaotix-recomp (sixteen slices, Nuked-OPN2), sega-vr-disasm (COMM register hazards)

8. Harden it and ship without the game

   You lock in what works so old fixes stay fixed. Then you package it so nobody gets the game from you. The player's own ROM is checked by hash. Chaotix ships no ROM bytes and no game data.

   • Save golden frame hashes for fixed inputs. Chaotix's long test checks 720 golden frame hashes over a 36,000-frame run.
   • Run random-input sweeps that must be bit-identical every time. Chaotix runs 33 of them before each release.
   • Keep enhancements off by default. Test that widescreen leaves the centre 320 pixels unchanged.
   • Build from a fresh clone and run every test with the ROM present.
   • Make the program check the player's ROM by SHA-1 before it runs.
   Prompt for ClaudeCopy

   GOAL: Add a regression set and a ROM-free release check for <GAME>.
   READ FIRST: PROGRESS.md, `tests/golden/`, the Tests section of https://github.com/YuutaTsubasa/ChaotixRecompiled
   FENCE: Edit only `tests/`, `tools/release/` and `.github/`. Do not change game behaviour. Do not change any expected hash.
   CHECK: From a fresh clone run `cmake -S . -B build -G Ninja -DGAME_ROM=<ABSOLUTE_PATH_TO_ROM> -DGAME_LONG_TESTS=ON`, `cmake --build build`, then `(cd build && ctest --output-on-failure)` and `python3 tools/release/scan_rom_bytes.py dist/<ZIP> <ABSOLUTE_PATH_TO_ROM>`. Done means all tests pass and the scan finds no ROM bytes.
   BUDGET: Stop after 3 hours.
   IF BLOCKED: Stop. Say which check fails and paste its output.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: both outputs. 3) Files changed. 4) What is still untested by a person. 5) New parking-lot items.

   Done whenA fresh clone passes every lockstep, golden and sweep test, and the release scan finds no ROM bytes.

   Proof this works: Chaotix Recompiled (139 tests per release, 33 random sweeps, no-game-data CI), https://yuuta-tsubasa.studio/ChaotixRecompiled/

Path B: Full decomp for porting

No full 32X decomp exists, so this path joins proven pieces. First you make a disassembly that rebuilds the ROM byte for byte, as two projects did. Then you rewrite each routine in C. You prove each one against recorded calls from your Path A interpreter. Last, you replace the CPUs and the COMM handshakes with plain code.

1. Check prior work and choose how to prove the C

   You learn what exists and how the game was made. If the source family is known, like Doom from Jaguar Doom, you can start from C. If not, you assume assembly and prove C by tests. Matching bytes needs the original compiler, and none is known for any 32X game.

   • Search for a disassembly or rebuild of your game. Read nukeykt/Doom32x-RE if your game is Doom.
   • Look at 20 SH-2 functions spread across the ROM. Note how they start and end, and any shared helper code like division or copy loops.
   • Look for any released source of the same game on another system.
   • Write the route in SCOPE.md: C checked by lockstep tests, or byte matching if you prove a compiler.
   Prompt for ClaudeCopy

   GOAL: Decide how C for <GAME> will be proven, and record the Path B route in SCOPE.md.
   READ FIRST: SCOPE.md, Ghidra listings of 20 SH-2 and 20 68000 functions spread across the ROM, notes/prior-work.md
   FENCE: Edit only `SCOPE.md` and `notes/compiler.md`. No code. Do not download compilers.
   CHECK: Run `git status --short` and `grep -c '^verdict:' notes/compiler.md`. Done means only SCOPE.md and notes/compiler.md changed, the grep prints 1, and notes/compiler.md lists all 40 sampled functions with start and end patterns and any shared helper code with its address.
   BUDGET: 2 hours.
   IF BLOCKED: Stop. Say what evidence is missing. Do not name a compiler without a byte-level match.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the sample table. 3) Files changed. 4) The verdict and what would change it. 5) New parking-lot items.

   Done whenSCOPE.md names the route, and notes/compiler.md holds the evidence for it.

   Proof this works: Doom32x-RE (C from Jaguar Doom source), sega-vr-disasm (SH-2 functions kept as assembly)

2. Make a disassembly that rebuilds byte for byte

   The disassembly is the base for everything else. It must rebuild the exact ROM, so any wrong change fails at once. The Macroassembler AS knows the 68000, the SH-2 family and the Z80, so one tool covers the whole cartridge.

   • Install AS: download the Win32 binaries, or build the C sources in WSL.
   • Split the ROM into sections by CPU. Switch the AS CPU setting for each part: CPU 68000, CPU SH7600 for the SH-2, and CPU Z80.
   • Build like the Chaotix prototype disassembly: asl -xx -q -A -L -U -E -i . main.asm, then p2bin main.p <OUT>.32x. That project keeps its own asl and p2bin builds in tool/linux/, with extra p2bin options.
   • Or copy sega-vr-disasm's route. It assembles 68000 code with vasm. It assembles each SH-2 function with sh-elf-as --isa=sh2, places it with a linker script, and includes the bytes.
   • Write tools/build.py. It assembles, compares the SHA-1 with SCOPE.md, and exits 0 only on a match.
   • Prove the gate works: change one byte and confirm the build fails.
   • Keep unknown spans as raw bytes read from your ROM at build time. Never commit them.
   Prompt for ClaudeCopy

   GOAL: Produce a disassembly of <GAME> that rebuilds the ROM byte for byte.
   READ FIRST: SCOPE.md, notes/functions.csv, http://john.ccac.rwth-aachen.de:8000/as/ (CPU list and manual), the make.sh of https://github.com/Ushupiuck/chaotix-1207-disasm
   FENCE: Edit only `src/`, `tools/` and `config/`. Never edit `config/expected.sha1`. Never commit ROM bytes.
   CHECK: Run `python3 tools/build.py`. Done means it exits 0 with a SHA-1 match, and `python3 tools/build.py --corrupt <ADDRESS>` exits non-zero.
   BUDGET: Stop after 4 hours, or 3 failed tries on the same mismatch.
   IF BLOCKED: Stop. Paste the first differing offset and the bytes on both sides.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: both build outputs. 3) Files changed. 4) Share of the ROM still raw bytes, per CPU. 5) New parking-lot items.

   Done whentools/build.py prints a SHA-1 match, and the corrupt test fails as it should.

   Proof this works: sega-vr-disasm (first commit: byte-for-byte ROM match; byte match kept until tag v5.0.0), https://github.com/matiaszanolli/sega-vr-disasm/blob/master/Makefile (sh-elf-as --isa=sh2, linker scripts), sonicretro/chaotix (68000 and Z80 side builds bit-perfect), Ushupiuck/chaotix-1207-disasm (AS build script), http://john.ccac.rwth-aachen.de:8000/as/as_EN.html (CPU list names SH7600 as the SH-2)

3. Turn every SH-2 byte into real source

   Two Chaotix disassemblies stopped here. They left the SH-2 code in a closed IDA database, so only one small driver was buildable. You move every SH-2 routine into assembler source. Runtime coverage tells you what is code and what is data.

   • Feed the coverage files from Path A into the disassembler. Executed bytes are code. Bytes only read are data.
   • Convert SH-2 routines from raw words to instructions, one section at a time. Rebuild after each one.
   • Before you move any SH-2 code, find every MOV.L @(disp,PC) that reads a nearby literal pool. Shared pools break silently.
   • Name data by kind: tables, strings, art, palettes, sound.
   • Track progress per CPU in notes/functions.csv.
   Prompt for ClaudeCopy

   GOAL: Convert SH-2 section <SECTION> of <GAME> from raw words to readable source, keeping the byte match.
   READ FIRST: notes/functions.csv, the coverage report from `python3 tools/coverage.py --list 50`, the SH2 Patching Discipline rules in https://github.com/matiaszanolli/sega-vr-disasm/blob/master/CLAUDE.md
   FENCE: Edit only files for <SECTION> under `src/sh2/` and notes/functions.csv. Use the project tools to convert. Do not hand-edit other sections.
   CHECK: Run `python3 tools/build.py` and `python3 tools/coverage.py`. Done means the SHA-1 still matches and no executed SH-2 byte in <SECTION> is still raw data.
   BUDGET: Stop after 90 minutes or 3 rollbacks.
   IF BLOCKED: Stop. A rollback means the guess was wrong. List the addresses you could not settle.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: build output and coverage counts before and after. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenNo executed byte in the recorded sessions is outside known code, for all three CPUs, and the build still matches.

   Proof this works: sega-vr-disasm (75 SH-2 functions as source while still byte-identical at tag v5.0.0; all 92 by tag v6.2.0, after it stopped matching), sonicretro/chaotix (SH-2 left in an IDA database)

4. Write down how the CPUs talk

   A port must replace the COMM handshakes with normal code. So you need a full written map of who sends what, through which register, and who waits. sega-vr-disasm found that each SH-2 polls its own COMM register with its own command table.

   • List every read and write of the COMM registers on every CPU. Use rom_analyzer --refs-to <ADDRESS> style queries.
   • For each command, write its sender, receiver, register, data and the wait that follows.
   • Map SDRAM: which areas hold code, shared data and buffers.
   • Save it as notes/comm-protocol.md with a source line for every claim.
   • Confirm each command with a trace from your Path A headless build.
   Prompt for ClaudeCopy

   GOAL: Document the COMM command <COMMAND> of <GAME> from sender to receiver.
   READ FIRST: `notes/comm-protocol.md`, https://github.com/matiaszanolli/sega-vr-disasm/blob/master/CLAUDE.md (COMM Register Safety), the listings that touch the COMM registers
   FENCE: Edit only `notes/comm-protocol.md` and `tools/trace/`. No game or runtime code.
   CHECK: Run `<HEADLESS_EXE> --rom <ABSOLUTE_PATH_TO_ROM> --trace comm --frames 600`. Done means every step you wrote appears in the trace, in order, and each claim names its listing address.
   BUDGET: 90 minutes.
   IF BLOCKED: Stop. Mark the claim unverified and say what trace would settle it.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the trace lines. 3) Files changed. 4) Unverified claims. 5) New parking-lot items.

   Done whenEvery COMM command is in notes/comm-protocol.md, each one confirmed by a trace.

   Proof this works: sega-vr-disasm (master polls COMM0, slave polls COMM2, documented dispatch tables), https://github.com/viciious/32XDK/blob/main/docs/32x-hardware-manual.md

5. First light: one routine in C, end to end

   You prove the whole loop on one small routine. Pick a leaf, which calls nothing else. Record every call to it in the interpreter: registers in, memory writes out. Your C must give the same results for every call.

   • Add a capture mode to your Path A interpreter that logs each call to one address.
   • Write the C in game/c/<CPU>/<ADDRESS>.c. Use m2c with target sh2 for a first SH-2 draft. It reads GNU as syntax, like sega-vr-disasm's SH-2 files.
   • Replay every captured call against the C, built for your PC.
   • If you proved a compiler, also compile with sh-elf-gcc from marsdev and diff with asm-differ.
   • Write the one-unit check into notes/method.md so every worker uses it.
   Prompt for ClaudeCopy

   GOAL: Write routine <ADDRESS> (<CPU>, <NAME>) of <GAME> as C and pass its capture replay.
   READ FIRST: the source file for <ADDRESS>, `notes/method.md`, `notes/comm-protocol.md` if the routine touches COMM
   FENCE: Create only `game/c/<CPU>/<ADDRESS>.c` and its prototype line. Do not edit the disassembly, captures or any check script. No inline assembly.
   CHECK: Run `python3 tools/replay.py <CPU> <ADDRESS> game/c/<CPU>/<ADDRESS>.c`. Done means every recorded call gives the same registers and memory writes.
   BUDGET: Stop after 5 meaningfully different tries.
   IF BLOCKED: Stop. Paste the first failing call: inputs, expected and actual.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the replay output. 3) Files changed. 4) What was learned for notes/method.md. 5) New parking-lot items.

   Done whenOne routine passes its capture replay, and the method is written down for workers.

   Proof this works: Chaotix Recompiled (reference interpreter as the answer key), knuckles-chaotix-recomp (--xcheck compares registers, target and every byte touched), https://github.com/matt-kempster/m2c

6. Grind: every routine as C, leaves first

   Now you hand out routines in batches. Keep 68000 and SH-2 work in separate batches, since each has its own checks. Each worker has its own git worktree. A gate script must pass before a batch merges.

   • Write a queue script that lists the next routines, leaves first, with CPU and call count.
   • Give each worker one batch in its own worktree, with absolute paths to the ROM and tools.
   • Write a gate that builds, replays captures for the batch, and runs a short lockstep session.
   • Merge one batch at a time. Run the full gate again after each merge.
   • Track counts per CPU in PROGRESS.md: done, tested, left.
   Prompt for ClaudeCopy

   GOAL: Write the next batch of <N> routines from `python3 tools/queue.py --cpu <CPU> -n <N>` as C, each passing its replay.
   READ FIRST: CLAUDE.md, `notes/method.md`, the queue output, one finished routine of the same CPU
   FENCE: Work only in this worktree. Create or edit only the `game/c/<CPU>/<ADDRESS>.c` files for this batch. Never edit check scripts, captures or other batches.
   CHECK: Run `python3 tools/gate.py --files <FILES>`. Done means every step prints PASS for every file.
   BUDGET: 5 tries per routine. Skip a routine after that and list it.
   IF BLOCKED: Stop that routine, not the batch. Record it in `notes/hard.md` with the first failing call.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the gate output. 3) Files changed. 4) Routines skipped and why. 5) New parking-lot items.

   Done whenThe queue is empty for all three CPUs, and the gate passes on the merged branch.

   Proof this works: Doom32x-RE (file-by-file rework, commits per file), https://github.com/cdlewis/snowboardkids2-decomp (one unit per run; from ai-decomp-practice.md)

7. Prove the whole game runs from the C

   Unit replays are evidence, not the verdict. Now you swap every recompiled routine for its C version inside the Path A runtime. Whole recorded sessions must still match the interpreter at every frame.

   • Add a build switch that calls the C routine instead of the generated one, routine by routine.
   • Turn all C routines on and run every recorded session in lockstep.
   • Prove the check can fail: break one routine and confirm a FAIL.
   • Have a person play the build and sign it off in docs/USER_VERIFIED.md.
   Prompt for ClaudeCopy

   GOAL: Show that <GAME> runs entirely from the hand-written C and equals the reference.
   READ FIRST: PROGRESS.md, the gate script, the list of recorded sessions
   FENCE: Edit only `tools/` scripts for this proof and `PROGRESS.md`. Do not change any C to make this pass; send failures back as units.
   CHECK: Run `<WHOLE_GAME_CHECK>` and then `<WHOLE_GAME_CHECK> --corrupt <ADDRESS>`. Done means the first passes on every session and the second fails.
   BUDGET: 3 hours.
   IF BLOCKED: Stop. List each failing session with its first differing frame.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: both outputs. 3) Files changed. 4) Sessions not covered. 5) New parking-lot items.

   Done whenEvery recorded session matches with all C routines on, the corrupt test fails, and a person signed off a full play.

   Proof this works: Chaotix Recompiled (36,000-frame lockstep run, golden hashes)

8. Port: remove the CPUs and the handshakes

   The C still assumes four CPUs and big-endian memory. You turn COMM handshakes into normal calls or threads. You move memory to the host's byte order. The frame buffer becomes a texture, and PWM becomes normal audio.

   • Put all game memory access behind one header, such as src/mem.h. Fail the build if code touches raw memory elsewhere.
   • Replace each COMM command from notes/comm-protocol.md with a direct call or a queue between two threads.
   • Swap byte order at the edges: ROM data reads, save files and hardware ports.
   • Copy the finished frame buffer to an SDL texture each frame. Send PWM samples to SDL audio.
   • Keep the Z80 sound driver on an interpreter with a YM2612 core, or rewrite it in C later.
   • Compare the native build with the Path A build at every frame of the test runs.
   Prompt for ClaudeCopy

   GOAL: Replace COMM command <COMMAND> in the <GAME> C port with a direct call, keeping every frame the same.
   READ FIRST: `notes/comm-protocol.md` entry for <COMMAND>, `src/mem.h`, CLAUDE.md
   FENCE: Edit only the files the port queue lists for <COMMAND> and `src/mem.h`. Do not change game logic.
   CHECK: Run `<NATIVE_COMPARE_COMMAND>`. Done means the native build equals the Path A build on every test run, and the port queue no longer lists <COMMAND>.
   BUDGET: Stop after 3 failed tries on the same mismatch.
   IF BLOCKED: Stop. Paste the first differing frame and the value that differs.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: compare output and queue counts. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenNo CPU emulation or COMM polling is left, and the native build matches the Path A build on every test run.

   Proof this works: d32xr (one C code base split across both SH-2s for rendering), Chaotix Recompiled (same runtime built for Windows, macOS, Android and iOS)

9. Harden the port for other systems

   A port needs C that acts the same under any compiler. So you build it two ways and compare. You also run a sanitizer, a compiler mode that catches undefined behaviour. Then you build for each new system and rerun the golden runs.

   • Record golden runs: per-frame hashes of game RAM, frame buffer and sound.
   • Build again with a second compiler, such as Clang next to GCC, and compare every frame.
   • Build with -fsanitize=undefined and replay the golden runs.
   • Build for each target system and run the same golden runs there.
   • Scan the release for ROM bytes. Ship only your code and a ROM check.
   Prompt for ClaudeCopy

   GOAL: Add second-compiler and sanitizer golden checks to the <GAME> port.
   READ FIRST: PROGRESS.md, `tests/golden/`, the platform table in https://github.com/YuutaTsubasa/ChaotixRecompiled
   FENCE: Edit only the build files and `tools/golden.py`. Do not change game code to pass a check; file each failure as a unit.
   CHECK: Run `python3 tools/golden.py --build gcc`, `python3 tools/golden.py --build clang` and `python3 tools/golden.py --build ubsan`. Done means all three pass on every golden run.
   BUDGET: 3 hours.
   IF BLOCKED: Stop. Paste the first differing frame and which build differs.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the three outputs. 3) Files changed. 4) Builds not yet run on real hardware. 5) New parking-lot items.

   Done whenGolden runs match bit for bit across two compilers and a sanitizer build, on each target system.

   Proof this works: Chaotix Recompiled (GCC, Clang and MSVC build warning-free; lockstep bit-identical on Apple M1)

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

Cut 32X work by CPU and by recorded session. On Path A, one unit is one fallback address, one lockstep difference or one hardware rule. On Path B, one unit is one routine on one CPU, or one COMM command. Keep 68000 and SH-2 units in separate batches. Every unit has one check: zero lockstep differences, a zero fallback count, a SHA-1 match or a passing capture replay.

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`, `PROGRESS.md` and `notes/divergence-log.md` at the start of every session.
- Never edit anything in `generated/`. Fix the recompiler, the analyzer or the runtime, then regenerate.
- The one check is `cmake --build build && (cd build && ctest --output-on-failure)` with `GAME_ROM` set. No pasted output means not done.
- Do not guess hardware behaviour. Cite `docs/32x-hardware-manual.md` or a trace for every rule you add.
- Code the recompiler cannot handle falls back to the interpreter. Report the fallback count in every status.
- Never change a golden hash or lockstep baseline alone. A change needs its reason in the same commit and my approval.
- SH-2 addresses at `$0600xxxx` are SDRAM. Never read them as ROM offsets. The SH-2 cannot reach 68000 work RAM.
- Before changing COMM code, read `notes/comm-protocol.md`. Read-during-write is undefined, and SH-2 writes are buffered.
- Test SH-2 changes one at a time. Check shared literal pools before you overwrite any SH-2 word.
- If a second try fails for a related reason, stop coding and read the docs. Do not try random addresses.
- The ROM lives at `<ABSOLUTE_PATH_TO_ROM>`. Never commit it, its bytes, or generated code. Coverage files hold addresses only.
- In a worktree, use absolute paths for the ROM and tools, and use your own build folder.
- Write side issues in `notes/parking-lot.md` and dead ends in `notes/findings.md`. Start every report with DONE, PARTIAL or BLOCKED.

Keep the context small

• Never read a generated C++ file whole. Search for the address, then read a few lines.
• Give Claude the first differing frame and the two state dumps, not the whole lockstep log.
• Keep hardware facts in notes/hardware-facts.md and point to sections. The full manual is long.
• Use separate sessions for 68000 work and SH-2 work, so only one instruction set is in context.
• Add Read deny rules for generated/**, build/** and trace folders.
• Clear the chat after each unit. The ledgers and the divergence log carry the state.

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> (SHA-1 <SHA1>) suits Path A, Path B, or both, and draft SCOPE.md.
READ FIRST: bytes $100-$1FF and $3C0-$3EF of `<ABSOLUTE_PATH_TO_ROM>`, https://github.com/YuutaTsubasa/ChaotixRecompiled (README), https://github.com/viciious/32XDK/blob/main/docs/32x-hardware-manual.md
FENCE: Create only `SCOPE.md` and `notes/prior-work.md`. No code. Do not copy the ROM.
CHECK: Run `sha1sum <ABSOLUTE_PATH_TO_ROM>` and `python3 -c "d=open('<ABSOLUTE_PATH_TO_ROM>','rb').read();print(len(d),d[0x100:0x110],[hex(int.from_bytes(d[o:o+4],'big')) for o in range(0x3D4,0x3F0,4)])"`. Done means SCOPE.md matches that output and lists size, `SEGA 32X` system field, title, region, the user header values, prior work with links, a guess at C or assembly with evidence, the chosen path, the first milestone with its check, and an out-of-scope list.
BUDGET: 45 minutes.
IF BLOCKED: Stop. Say what you could not check.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: header fields and hash. 3) Files changed. 4) Risks you see. 5) New parking-lot items.

GOAL: Produce `notes/functions.csv` for <GAME>: every routine start with CPU, address, size, proof and status.
READ FIRST: SCOPE.md, the analyzer output in `out/map`, the coverage files in `coverage/`
FENCE: Edit only `notes/functions.csv` and scripts in `tools/map/`. Do not edit the recompiler.
CHECK: Run `python3 tools/map/check_ledger.py notes/functions.csv`. Done means no overlaps, every row names a CPU and a proof, and SH-2 rows use SDRAM or cartridge addresses, never raw file offsets.
BUDGET: 2 hours.
IF BLOCKED: Stop. List the address ranges you could not classify.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: checker output and counts per CPU. 3) Files changed. 4) Unclassified ranges. 5) New parking-lot items.

GOAL: Fix <UNIT> (fallback at <ADDRESS> on <CPU>, or the first lockstep difference in session <RUN>) in <GAME>.
READ FIRST: CLAUDE.md, `notes/divergence-log.md`, the listing at <ADDRESS>
FENCE: Edit only the recompiler, analyzer or runtime file named in the unit, plus the notes. Never edit `generated/` or `tests/golden/`.
CHECK: Run the one check with `GAME_ROM` set. Done means the unit is gone, lockstep is clean on every recorded session, and the fallback count did not rise.
BUDGET: 3 tries or 45 minutes.
IF BLOCKED: Stop. Report the evidence and your two best causes.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: check output before and after. 3) Files changed. 4) Cause in one sentence. 5) New parking-lot items.

GOAL: Write routine <ADDRESS> (<CPU>, <NAME>) as C and pass its capture replay.
READ FIRST: the source file for <ADDRESS>, `notes/method.md`, one finished routine for the same CPU
FENCE: Create only `game/c/<CPU>/<ADDRESS>.c` and its prototype. No inline assembly. No edits to checks, captures or other routines.
CHECK: Run `python3 tools/replay.py <CPU> <ADDRESS> game/c/<CPU>/<ADDRESS>.c`. Done means every recorded call gives the same registers and memory writes.
BUDGET: 5 meaningfully different tries.
IF BLOCKED: Stop. Paste the first failing call with inputs, expected and actual.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the replay output. 3) Files changed. 4) Lessons for notes/method.md. 5) New parking-lot items.

GOAL: Pick the next <N> units from `<QUEUE_COMMAND>` and launch one worker per unit, each in its own worktree.
READ FIRST: CLAUDE.md, PROGRESS.md, the queue output
FENCE: Do not do unit work yourself. Each worker gets one task card, one worktree, absolute paths, and its own build folder. Never mix 68000 and SH-2 units in one worker. Do not merge a batch whose gate failed.
CHECK: After each worker reports, run `<GATE_COMMAND>` on its branch. Done means every merged branch passed the gate, and the gate passes again on the merged main branch.
BUDGET: One round of <N> workers. Stop after the round.
IF BLOCKED: Stop. List each failed unit with its report.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: gate output for each merge. 3) Branches merged. 4) Units returned to the queue. 5) New parking-lot items.

GOAL: Find the proven cause of <SYMPTOM> in <GAME>. Do not fix it yet.
READ FIRST: `notes/divergence-log.md`, `notes/comm-protocol.md`, recorded session <RUN>, CLAUDE.md
FENCE: Read and run only. You may add logging under `tools/debug/`. No edits to the game, runtime or golden files.
CHECK: Run `<HEADLESS_EXE> --rom <ABSOLUTE_PATH_TO_ROM> --replay-input tests/inputs/<RUN> --lockstep` and paste the first difference it prints. Done means you name the first differing frame, the CPU, the first wrong write (address, value, expected value), and the instruction or hardware rule behind it, with pasted dumps from both sides.
BUDGET: 90 minutes.
IF BLOCKED: Stop. Give the narrowest frame range you reached and what evidence would settle it.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the dumps. 3) Files changed. 4) Proposed fix and how to check it. 5) New parking-lot items.

GOAL: Check that the work in <BRANCH> is real.
READ FIRST: CLAUDE.md, the worker's report, `git diff <BASE>..<BRANCH>`
FENCE: Read and run only. Do not fix anything.
CHECK: Rerun the one check yourself with `GAME_ROM` set. Then look for: edits under `generated/`, changed golden hashes or baselines, skipped or shortened lockstep runs, stubbed COMM waits, fallback counts that went up, enhancements left on, ROM bytes in tracked files, and edits outside the fence. Done means each item is marked clean or found, with file and line.
BUDGET: 45 minutes.
IF BLOCKED: Stop. Say what you could not run.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) PASS or FAIL. 2) Proof: your own check output. 3) Each finding with file and line. 4) Whether the report matched what you saw. 5) New parking-lot items.

GOAL: Report where <GAME> stands, using numbers from the ledgers only.
READ FIRST: PROGRESS.md, `notes/functions.csv`, `out/fallbacks.txt`, `notes/divergence-log.md`, `notes/parking-lot.md`
FENCE: Edit only `PROGRESS.md`. No code.
CHECK: Run the one check and paste its summary line. Done means every number in the report comes from a file or that output.
BUDGET: 15 minutes.
IF BLOCKED: Stop. Say which file is missing or stale.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Counts per CPU: routines done and left, fallbacks, sessions passing lockstep, open differences. 3) What changed today. 4) Top three risks. 5) Parking-lot items for me to decide.

GOAL: Write what the next session needs to continue <TASK> without this chat.
READ FIRST: PROGRESS.md, `notes/handoff.md`, `git status`, `git log -5 --oneline`
FENCE: Edit only `notes/handoff.md` and `PROGRESS.md`. Commit nothing else.
CHECK: Run `git status --short` and `git log -1 --oneline`. Done means notes/handoff.md names every file git status lists and has: the current unit, what was tried with results, the last check output, uncommitted changes, the exact next command, and what is checked by a machine versus still to be played by a person.
BUDGET: 10 minutes.
IF BLOCKED: Stop. Write what you have.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the new handoff section. 3) Files changed. 4) The next command. 5) New parking-lot items.

GOAL: Give me a plain answer on <UNIT>: can it be done with what we have, and what would it take?
READ FIRST: the attempts in `notes/findings.md` for <UNIT>, the last check output
FENCE: No code changes. No new tries.
CHECK: Rerun the last check command written in `notes/findings.md` for <UNIT> and paste its output. Done means you state one of: CAN DO (with the plan and its check), CANNOT DO NOW (with the missing piece, such as an unknown compiler or a hardware fact nobody has documented), or NEEDS A RULING (with the options).
BUDGET: 20 minutes.
IF BLOCKED: Say BLOCKED and why in one sentence.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) CAN DO, CANNOT DO NOW or NEEDS A RULING. 2) Proof: the evidence behind it. 3) Options with cost and risk. 4) What you recommend. 5) New parking-lot items.

GOAL: Ask me to approve one change outside the current fence for <UNIT>.
READ FIRST: SCOPE.md, CLAUDE.md, the evidence for the needed change
FENCE: Make no change yet. Write the request in `notes/scope-requests.md` only.
CHECK: Run `git status --short`. Done means it shows only `notes/scope-requests.md` changed, and the request names the files outside the fence, why the change is needed with evidence, what else it could break (all four CPUs share the clock), and how it will be checked.
BUDGET: 15 minutes.
IF BLOCKED: Stop. Say what you need to know.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the evidence. 3) The exact change proposed. 4) The risk and how to test it. 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 a disassembly exists. Only Chaotix and Virtua Racing Deluxe have one.
• How much code runs from RAM, and how the two SH-2s split work. Each pattern needs its own handling.
• How tightly the CPUs are timed through the COMM ports. Loose games boot fast. Tight ones need many timing fixes.
• Whether you write your own interpreters or reuse Musashi and PicoDrive code. The answer key comes before everything else.
• Your review time. Each unit needs a look at its proof, and that is your 10 to 15 hours a week.

The facts behind these numbers

Projects reviewed (10)

RecompLauncher lists fewer than 10 games for the 32X: just 2 projects for 2 games. One more project came from outside it (Doom32x-RE). Only 3 distinct 32X games have any public source project anywhere, so fewer than 10 real projects exist. To reach 10 entries, 7 more projects for the same three games were reviewed live with the GitHub API.

What each project teaches

What we could not check

• Which compiler any shipped 32X game used. The PSY-Q Development System (32X) entry was seen only in a search summary, because Sega Retro blocks automated readers.
• Whether PicoDrive or BizHawk need a 32X BIOS file for 32X games. Do not download one; Chaotix Recompiled shows a game can boot without it.
• Whether the GhidraMCP server works with Ghidra 12.2. Its README names Ghidra 12.1.4.
• Whether the official AS build assembles a whole 32X cartridge. The Chaotix prototype disassembly ships its own asl and p2bin builds, and its p2bin -z option is not in the official manual.
• Whether sega-vr-disasm's tag v5.0.0 still rebuilds the ROM byte for byte. Its README points to a v5.0-freeze branch for that, but the branch was not found on 2026-11-13.
• Whether the 2021 vasm binaries on the vasm page include the vasmm68k_mot build that sega-vr-disasm uses.
• Whether m2c and asm-differ give useful output on 32X SH-2 code. No reviewed 32X project used them.
• How much work came before each project's first public commit. Chaotix Recompiled and sega-vr-disasm both started with big working commits.
• Whether Doom32x-RE builds, or how close it is to the cartridge.
• How Chaotix Recompiled used Claude day to day. Its docs/superpowers/ folder holds one plan file (frame pacing, 2026-09-27). The repo does not say which tool wrote it.
• Whether s32xfan/virtuaracing used AI, and what language its recompiler is written in.
• That the same 32X boot shortcut works for every game. It is proven only for Knuckles' Chaotix.
• All Path B time ranges. No 32X game has a full decomp, so they are estimates from a disassembly and from Genesis projects.

Sources

• Chaotix Recompiled README
• The Recompiled Handbook (Chaotix Recompiled)
• Virtua Racing Deluxe Enhanced README
• Doom32x-RE repository
• sega-vr-disasm README
• sega-vr-disasm CLAUDE.md
• sega-vr-disasm Makefile
• The Macroassembler AS user manual (English)
• Musashi README
• binutils-sh-elf file list (noble)
• knuckles-chaotix-recomp README
• Knuckles' Chaotix Disassembly (Sonic Retro)
• Chaotix 1207 prototype disassembly
• s32xfan/virtuaracing README
• DOOM 32X: Resurrection README
• 32X hardware manual (32XDK transcription)
• 32XDK wiki: SH2 on the 32X
• Plutiedev: ROM header
• PicoDrive README
• BizHawk README
• Ghidra SuperH language definitions
• GhidraMCP README
• The Macroassembler AS
• vasm
• MSYS2
• Ubuntu package binutils-sh-elf (noble)
• marsdev README
• m2c README
• asm-differ README
• Capstone README