Game Gear decomp guide

What this system is like

The Game Gear is a handheld Master System. It runs a Z80 chip at about 3.5 MHz. Games come on small cartridges, from 128 KB to 1 MB in the projects we read. Every game we found was written by hand in Z80 assembly, not in C.

Path A is new but works. Three projects turned the game's machine code into C by static recompilation. A shared framework, smsggrecomp, does this for both the Master System and the Game Gear. 43 of its 56 commits carry a Claude co-author line.

Path B is the hard part. Three projects made a disassembly that rebuilds the ROM byte for byte. A disassembly is the game's machine code written out as assembly text. No one has rewritten a whole Game Gear game in C. One project tried and stopped. We tell you plainly that this path is unproven.

Most work runs on Windows. Only a few tools need WSL: z80dasm, the PSP kit and some shell scripts. The field is small. We found only seven real Game Gear projects, so this guide adds three Master System ones.

Two paths

Path A: Get it running on PC

You give your own ROM and a game.toml file to smsggrecomp. Its tool SmsRecomp.exe writes C, one function per Z80 routine. A runtime stands in for the video chip, sound chip, ports and mapper. Code it missed runs on a built-in interpreter for now. You close each gap and check the build against the interpreter and an emulator.

1. Pick the game and write the scope

   A different dump or region is a different program. So you pin the exact ROM by hash first. Then you look for prior work. A disassembly or a recomp of your game can save weeks.

   • Print size, CRC32, SHA-1 and the header with Python: python -c "import zlib,hashlib;d=open(r'<ABSOLUTE_PATH_TO_ROM>','rb').read();print(len(d),format(zlib.crc32(d),'08X'),hashlib.sha1(d).hexdigest(),d[0x7FF0:0x7FF8],hex(d[0x7FFF]))".
   • Check that bytes $7FF0 to $7FF7 read TMR SEGA. Check that the high digit of the last byte is 5, 6 or 7. That marks a Game Gear region. Headers can hold mistakes, so the hash is what pins the ROM.
   • Read the game list in smsggrecomp's CLAUDE.md. It names Sonic Blast, Sonic Chaos, Sonic and Tails 1 and 2 with their CRC32 values.
   • Search GitHub, smspower.org and Sonic Retro for a disassembly of your game. Search for a Master System version too.
   • Write SCOPE.md: game, region, CRC32, SHA-1, size, goal, technique, first milestone and its check, and an out-of-scope list.
   Prompt for ClaudeCopy

   GOAL: Draft SCOPE.md for a Game Gear static recomp of <GAME> (<REGION>).
   READ FIRST: bytes $7FF0-$7FFF of `<ABSOLUTE_PATH_TO_ROM>` (read only), https://www.smspower.org/Development/ROMHeader, https://github.com/mstan/smsggrecomp/blob/main/CLAUDE.md
   FENCE: Create only `SCOPE.md` and `notes/prior-work.md`. Do not copy or move the ROM. Do not write code.
   CHECK: Run the Python one-liner from step 1 of the guide and paste its output. Done means SCOPE.md has the game, region, size in bytes, CRC32, SHA-1, the header text and region digit, goal, technique, 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 region 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: paste the hash and header output. 3) Files changed. 4) Prior work found, with links. 5) New parking-lot items.

   Done whenSCOPE.md names the exact ROM by CRC32, SHA-1 and size, lists prior work with links, and you approved it.

   Proof this works: SonicBlastGGRecomp (ROM pinned by CRC32 0x031B9DA9 and size), Devilish PSP (embed_rom.py --check refuses other dumps), https://www.smspower.org/Development/ROMHeader

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

   You install the build tools and make a small game repo. The framework sits in it as a pinned submodule. The ROM and the generated C stay out of git. You also write the one check command now, even if it does little yet.

   • Install MSYS2 from msys2.org. In the MINGW64 shell run pacman -S mingw-w64-x86_64-gcc mingw-w64-x86_64-cmake mingw-w64-x86_64-ninja mingw-w64-x86_64-SDL2.
   • Make your game repo. Add the framework: git submodule add https://github.com/mstan/smsggrecomp then git submodule update --init --recursive.
   • Copy the shape of SonicBlastGGRecomp: game.toml (with platform = "gg" and your crc32), build.ps1, and tests/coverage/. Its CMakeLists.txt is three lines: set SMSGG_ROOT, include smsggrecomp/cmake/SmsGame.cmake, and call sms_add_game(<GAME>Recomp).
   • Add *.gg, *.sms, *.bin, generated/, build/, out/ and coverage-*/ to .gitignore before the ROM is anywhere near the repo.
   • Build once: powershell -File build.ps1 -Rom '<ABSOLUTE_PATH_TO_ROM>'. The script builds the recompiler, regenerates the C and links the runtime.
   • The build looks for cmake.exe, ninja.exe and gcc.exe in C:\msys64\mingw64\bin. If MSYS2 lives elsewhere, add -Sdl '<MSYS2_MINGW64_DIR>'.
   • Write tools/check.ps1. It runs build.ps1, then build\<GAME>Recomp.exe '<ABSOLUTE_PATH_TO_ROM>' --frames 600 --report out\boot.json with no window. It prints PASS only if the report shows "dispatch_misses":0. Otherwise it prints FAIL and the count.
   Prompt for ClaudeCopy

   GOAL: Set up a game repo for <GAME> on smsggrecomp with one check command.
   READ FIRST: SCOPE.md, https://github.com/mstan/smsggrecomp/blob/main/README.md, https://github.com/mstan/SonicBlastGGRecomp (README, build.ps1, CMakeLists.txt, game.toml)
   FENCE: Edit only files in this repo. Add smsggrecomp as a submodule; never edit inside it. Do not add features.
   CHECK: Run `powershell -File tools/check.ps1 '<ABSOLUTE_PATH_TO_ROM>'`. Done means the build finishes, `git status` shows no ROM and no generated C, and the check prints PASS or a FAIL line with the miss count.
   BUDGET: Stop after 3 failed builds with the same error.
   IF BLOCKED: Stop. Paste the exact error. Do not switch compilers or install new tools without asking.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: paste the build tail and the check output. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenbuild.ps1 makes an exe from your ROM, git status shows no ROM or generated C, and tools/check.ps1 prints PASS or FAIL with a miss count.

   Proof this works: SonicBlastGGRecomp (build.ps1, MSYS2 default path C:\msys64\mingw64), https://github.com/mstan/smsggrecomp/blob/main/tools/build_game.ps1 (tool paths) and runner/main.c (--frames, --report), Sonic the Hedgehog (Master System version) recomp (same build layout), https://github.com/mstan/smsggrecomp

3. Map the ROM into a function list

   The recompiler starts at the reset and interrupt vectors and follows calls. It cannot see code reached through tables or pushed addresses. You find those starts by reading the code. Every start needs proof, because a wrong Z80 start decodes into nonsense.

   • Open the ROM in Emulicious. Use its disassembler, which splits code from data as the game runs. Play the attract demo and the first level.
   • Load the ROM in Ghidra 12.2 with the Z80 language. The Ghidra-SegaMasterSystem-Loader finds the header but does not map banks, so load each 16 KB bank at its window yourself.
   • In WSL, get a second opinion on a doubtful bank: sudo apt install z80dasm, then run z80dasm on that bank's bytes.
   • Write notes/functions.csv with address, bank, size, name, proof and status.
   • Add proven starts to the [functions] extra list in game.toml, with jump tables beside them. Note which bank each one lives in.
   Prompt for ClaudeCopy

   GOAL: Build the first function list for <GAME> and feed proven starts to game.toml.
   READ FIRST: SCOPE.md, `game.toml`, the Emulicious or Ghidra listing at `<LISTING_PATH>`, https://github.com/mstan/smsggrecomp/blob/main/PRINCIPLES.md (sections 13 and 16)
   FENCE: Edit only `game.toml`, `notes/functions.csv` and scripts under `tools/map/`. Do not edit the framework or anything in `generated/`.
   CHECK: Run `powershell -File build.ps1 -Rom '<ABSOLUTE_PATH_TO_ROM>'`. Done means it finishes, every row in functions.csv names its bank and its proof, and no start sits inside another routine.
   BUDGET: Stop after 2 hours or 3 failed builds with the same error.
   IF BLOCKED: Stop. Do not guess entry points. List the addresses you could not prove.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: entry count and the build summary. 3) Files changed. 4) Unproven addresses. 5) New parking-lot items.

   Done whennotes/functions.csv lists every start with its bank and proof, and the build runs on the new game.toml without errors.

   Proof this works: SonicBlastGGRecomp (its dispatch_manifest.txt grew from 40 to 198 ROM-verified entries, per smsggrecomp COVERAGE.md), https://github.com/mstan/smsggrecomp (README: the function finder starts at the vectors plus [functions].extra seeds and jump tables), KishinDoujiZenkiDecomp (bank-aware tracer, z80dasm as second opinion), https://github.com/VGKintsugi/Ghidra-SegaMasterSystem-Loader

4. Write test routes you can replay

   You need a check that does not trust your eyes. A route is a small text file of button presses and captures, tied to your ROM's CRC32. The framework runs it twice: once as native code and once in the interpreter. Then it compares the results.

   • Write one route file per scene, such as tests/coverage/<RUN>.txt. The first line is rom <CRC32>. Then lines like 300 pad S, 310 pad - and 1250 capture title. Pad letters are UDLRABS, and - lets go.
   • Run one route: build\<GAME>Recomp.exe '<ABSOLUTE_PATH_TO_ROM>' --route tests/coverage/<RUN>.txt --report out/<RUN>.json.
   • List your routes in tests/coverage/suite.json: rom_crc32, rom_size, and a cases list where each case has a name, a route file and a frames count.
   • Run the suite: python smsggrecomp/tools/run_coverage_suite.py --runtime build/<GAME>Recomp.exe --rom <ABSOLUTE_PATH_TO_ROM> --suite tests/coverage/suite.json --out coverage-<N>. Use a new folder name each time. The tool refuses a folder that already exists.
   • For a second opinion, run the ROM in Mesen with no window: Mesen.exe --testRunner <SCRIPT>.lua <ABSOLUTE_PATH_TO_ROM> --doNotSaveSettings. End the script with emu.stop(0). smsggrecomp/tools/oracle/mesen_vdp_dump.lua is a working example.
   Prompt for ClaudeCopy

   GOAL: Write <N> replayable routes for <GAME> and run them as a coverage suite.
   READ FIRST: SCOPE.md, https://github.com/mstan/smsggrecomp/blob/main/COVERAGE.md, the `tests/coverage/` folder of https://github.com/mstan/SonicBlastGGRecomp
   FENCE: Edit only `tests/coverage/` (route files and suite.json, no ROM bytes) and `tools/ref/`. Do not change game logic or the framework.
   CHECK: Run `python smsggrecomp/tools/run_coverage_suite.py --runtime build/<GAME>Recomp.exe --rom <ABSOLUTE_PATH_TO_ROM> --suite tests/coverage/suite.json --out coverage-<N>` with a folder that does not exist yet. Done means it prints one `zero fallback:` line per route and writes `coverage-<N>/report.json`.
   BUDGET: Stop after 3 hours or 3 failed tries on the same route.
   IF BLOCKED: Stop. Do not loosen a capture or delete a route to get a pass. Tell me what differs.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the suite summary lines. 3) Files changed. 4) Which scenes the routes cover and which they skip. 5) New parking-lot items.

   Done whenThe coverage suite prints a zero fallback: line and an equal surface captures: count for every route, and writes report.json.

   Proof this works: SonicBlastGGRecomp (tests/coverage/suite.json, 30 act and character cases), https://github.com/mstan/smsggrecomp/blob/main/COVERAGE.md, Devilish PSP (27 scripted button sessions)

5. First light: boot to the title screen

   You generate the C, build it and boot it. The interpreter fallback stays on for now, so missed code still runs. The goal is the Sega logo and the title screen, matching the interpreter.

   • Build: powershell -File build.ps1 -Rom '<ABSOLUTE_PATH_TO_ROM>'.
   • Run it: .\build\<GAME>Recomp.exe '<ABSOLUTE_PATH_TO_ROM>' --window 3.
   • Run your boot route twice: once as is, and once with --interp, which runs the reference interpreter. Compare the files each capture line wrote. A one-case suite does both runs for you.
   • Read dispatch_misses.log. The runner writes it in the folder you ran it from. Copy its line count into PROGRESS.md.
   • Close old copies before each run. In PowerShell: taskkill /F /IM <GAME>Recomp.exe. In Git Bash: taskkill //F //IM <GAME>Recomp.exe. The framework's rule 24 allows one copy at a time.
   Prompt for ClaudeCopy

   GOAL: Generate, build and boot <GAME> to its title screen with the interpreter fallback on.
   READ FIRST: SCOPE.md, PROGRESS.md, game.toml, https://github.com/mstan/smsggrecomp/blob/main/CLAUDE.md
   FENCE: Edit only `game.toml`, the per-game source files and `CMakeLists.txt`. Never edit `generated/`. Never edit the framework submodule.
   CHECK: Run `powershell -File tools/check.ps1 '<ABSOLUTE_PATH_TO_ROM>'` and the boot route. Done means the build runs to the title with no crash, and the boot captures match the interpreter.
   BUDGET: Stop after 4 failed builds or 2 hours without a new frame.
   IF BLOCKED: Stop. Paste the last log lines and the first differing capture. Do not stub a routine to get past a crash.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: check output, route report and a screenshot path. 3) Files changed. 4) Miss count. 5) New parking-lot items.

   Done whenThe build reaches the title screen with no crash, and the boot route's captures match the interpreter.

   Proof this works: SonicBlastGGRecomp (v0.0.1 on 2026-06-23 boots through the intro to the title), Sonic the Hedgehog (Master System version) recomp (boots and plays Green Hill Zone)

6. Close the code gaps

   A dispatch miss means the game jumped to an address with no generated function. The interpreter hides it, so you must look. One unit of work is one missed address. You prove where its routine starts, then regenerate.

   • After every run, read dispatch_misses.log. Empty means done for that run. In a suite run, each route has its own log in coverage-<N>/<CASE>/native/.
   • For each address, find it in your Emulicious or Ghidra listing. Decide: real routine start, middle of a routine, or data.
   • Check which bank was live when the jump happened. The same address can mean different code in different banks.
   • Add proven starts to game.toml with a note of the proof. Never add an address only because the log names it.
   • Regenerate, rebuild and rerun every route. Repeat until the log is empty on all of them. The suite exits with code 1 while any route still has a miss or interpreted cycles.
   Prompt for ClaudeCopy

   GOAL: Resolve dispatch miss <ADDRESS> (bank <BANK>) in <GAME>.
   READ FIRST: `dispatch_misses.log`, the listing at <ADDRESS>, `notes/functions.csv`, https://github.com/mstan/smsggrecomp/blob/main/PRINCIPLES.md (section 16)
   FENCE: Edit only `game.toml` and `notes/functions.csv`. Never edit `generated/`. Never add an address only because the miss log names it.
   CHECK: Rebuild and run the coverage suite. Done means <ADDRESS> no longer appears in `dispatch_misses.log`, no new miss appears, and every route still matches.
   BUDGET: Stop after 3 failed tries or 45 minutes.
   IF BLOCKED: Stop. Paste the listing and say why the start is unclear.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the listing, the miss count before and after, the suite summary. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whenrun_coverage_suite.py exits with code 0, so every route has zero misses and zero interpreted cycles, and the capture counts did not drop.

   Proof this works: SonicBlastGGRecomp (all 30 routes with zero fallback), https://github.com/mstan/smsggrecomp/blob/main/PRINCIPLES.md (13a and 16), MMPR: The Movie, Game Gear to PC (runtime miss log closes gaps)

7. Fix differences at the first divergence

   A wrong picture often starts with a wrong value many frames earlier. So you never chase the symptom. You find the first frame where native code and the interpreter differ. Then you narrow it to one instruction, one port or one mapper rule.

   • Find the first route capture that differs in coverage-<N>/report.json. The suite compares four files per capture: .png, .vram, .cram and .regs.
   • Copy that route to tests/probe/<RUN>.txt. Add capture lines at earlier frames and run it native and with --interp. Halve the gap until you have the first differing frame.
   • For a third opinion, dump the same frame from your build with --frames <N> --dump-frame <F> --dump-out x.png. Dump it in Mesen with mesen_vdp_dump.lua. Compare with python smsggrecomp/tools/oracle/vdp_diff.py x.png.vram x.png.cram <MESEN_VRAM> <MESEN_CRAM>.
   • Read the listing for the code that writes the first wrong byte. Name one instruction, one port or one mapper rule as the cause.
   • Fix the cause in the recompiler, the runtime or game.toml. Never in generated C.
   • Write each case in notes/divergence-log.md as frame, symptom, cause and fix.
   Prompt for ClaudeCopy

   GOAL: Find and fix the first divergence in route <RUN> of <GAME>.
   READ FIRST: `notes/divergence-log.md`, `coverage-<N>/report.json` for <RUN>, https://github.com/mstan/smsggrecomp/blob/main/COVERAGE.md (route controls), https://github.com/mstan/smsggrecomp/blob/main/ACCURACY.md (section 4)
   FENCE: Edit only the files named in CLAUDE.md for runtime fixes, `game.toml`, probe routes in `tests/probe/`, and `notes/divergence-log.md`. Never edit `generated/` or `tests/coverage/`.
   CHECK: Run the coverage suite into a new `coverage-<N>` folder. Done means <RUN> matches further than before, the cause is one instruction, port or mapper rule, and no other route got worse.
   BUDGET: Stop after 2 fix tries that do not move the first divergence.
   IF BLOCKED: Stop. Report the frame, both values, and your best two causes with proof for each.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: first divergent frame before and after. 3) Files changed. 4) The cause in one sentence. 5) New parking-lot items.

   Done whenIn report.json, every capture of every route has all four files equal, and each fix has a line in notes/divergence-log.md.

   Proof this works: https://github.com/mstan/smsggrecomp/blob/main/COVERAGE.md (capture lines, native and interpreter runs compared), https://github.com/mstan/smsggrecomp/blob/main/ACCURACY.md (--dump-frame, mesen_vdp_dump.lua, vdp_diff.py), SonicBlastGGRecomp (one 33-pixel ring-icon capture traced to one pending sprite byte), MMPR: The Movie, Game Gear to PC (RAM, VRAM, CRAM and frames compared every frame)

8. Harden it and ship without the game

   You lock in what works. Old fixes must stay fixed. Then you package the build so nobody gets the game from you. Players bring their own ROM, and the build checks its CRC32.

   • Cover every level and both endings with routes. Keep the suite in tests/coverage/suite.json.
   • Keep zero fallback as the gate. run_coverage_suite.py already exits with code 1 if any route has a miss or interpreted cycles.
   • Build from a fresh clone and rerun the whole suite.
   • Ship an exe that refuses any ROM but yours, by CRC32 and size. Keep SDL2.dll next to it.
   • Scan the release zip for ROM bytes before you publish it. Play it through yourself and record that you did.
   Prompt for ClaudeCopy

   GOAL: Add a full regression suite and a ROM-free release package for <GAME>.
   READ FIRST: PROGRESS.md, `tests/coverage/suite.json`, the README of https://github.com/mstan/SonicBlastGGRecomp
   FENCE: Edit only `tests/`, `tools/release/` and `.github/`. Do not change game behaviour. Do not change any expected capture.
   CHECK: From a fresh clone, run the coverage suite, then `python tools/release/scan_rom_bytes.py dist/<ZIP> <ABSOLUTE_PATH_TO_ROM>`. Done means all routes pass with zero fallback 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 a person has not yet played through. 5) New parking-lot items.

   Done whenA fresh clone passes every route with zero fallback, the scan finds no ROM bytes, and you played it to the end.

   Proof this works: SonicBlastGGRecomp (pre-built Windows x64 zip, ROM never shipped), MMPR: The Movie, Game Gear to PC (two full playthroughs to the ending), Devilish PSP (generated output kept out of git)

Path B: Full decomp for porting

You first make a disassembly that rebuilds the ROM byte for byte. You label it, split out the art and levels, and sort code from data. Then you rewrite routines in C and prove each one against a reference interpreter. Last, you put the hardware behind an interface and build for a new system. The first half is proven on this system. The C half is not.

1. Check prior work and pick the route

   A disassembly may already exist for your game or its Master System twin. Starting from one saves weeks. You also decide how far to go. A byte-matching disassembly is a real, proven goal. A full C rewrite is not proven here yet.

   • Search GitHub for <GAME> disassembly and <GAME> disasm. Check smspower.org and Sonic Retro.
   • Check for a Master System version of the game. Sonic Chaos, Sonic 2 and Sonic 1 have Master System disassemblies.
   • Hash your ROM as in Path A step 1. A Japanese and a US ROM are different targets.
   • Write in SCOPE.md which milestone you aim for: matching disassembly, labelled and split, or C rewrite.
   • Write down plainly that the C step has no Game Gear example to copy.
   Prompt for ClaudeCopy

   GOAL: Decide the Path B route for <GAME> (<REGION>, SHA-1 <SHA1>) and update SCOPE.md.
   READ FIRST: SCOPE.md, `notes/prior-work.md`, https://github.com/tbarnavon/KishinDoujiZenkiDecomp (README), https://github.com/TheRavenfreak/Sonic-1-Game-Gear-Disassembly (README)
   FENCE: Edit only `SCOPE.md` and `notes/prior-work.md`. No code. Do not download any ROM or any repo that contains one.
   CHECK: Done means SCOPE.md names the target milestone, the assembler (WLA DX or sdasz80), any existing disassembly with its link and licence, and the risks.
   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: links and hashes. 3) Files changed. 4) Risks you see. 5) New parking-lot items.

   Done whenSCOPE.md names the milestone, the assembler and any prior disassembly, and you approved it.

   Proof this works: KishinDoujiZenkiDecomp (C rewrite tried and abandoned), Sonic Chaos (Master System version) disassembly, Sonic-1-Game-Gear-Disassembly (README: started in 2017)

2. Set up the assembler and the byte check

   You pick one assembler and pin its version. You write one build script and one verify script. The verify script compares your built ROM with your original, byte for byte. The original stays outside the repo and is read-only.

   • Download wla_dx_v10.7_Win64.zip from the WLA DX releases page and unzip it into tools/wla/. Or pin SDCC, as Zenki pinned 4.1.0.
   • Write build.bat or tools/build.py. It runs wla-z80 -v -o game.o game.asm and then wlalink -d -v -S game.link build/game.gg.
   • Write tools/verify.py. It prints MATCH or the first differing offset and bank.
   • Keep the original in a folder outside the repo, such as <ABSOLUTE_PATH_TO_ORIGINAL_DIR>. Add *.gg, *.sms and build/ to .gitignore.
   • Add a PreToolUse hook that blocks edits to tools/verify.py and to the expected hash file.
   Prompt for ClaudeCopy

   GOAL: Set up a pinned assembler, a build script and a byte-check script for <GAME>.
   READ FIRST: SCOPE.md, https://wla-dx.readthedocs.io/en/latest/, the build scripts of https://github.com/Strugglemeat/supercolumnsgg-disasm (assemble.sh)
   FENCE: Edit only `build.bat`, `tools/`, `.gitignore`, `.claude/settings.json` and `CLAUDE.md`. Do not write game source yet.
   CHECK: Run `python tools/verify.py <ABSOLUTE_PATH_TO_ROM> build/game.gg` on a test file. Done means it prints MATCH for an identical file and the first differing offset for a changed copy.
   BUDGET: Stop after 90 minutes.
   IF BLOCKED: Stop. Paste the error. Do not install a different assembler without asking.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: both verify outputs. 3) Files changed. 4) What is left. 5) New parking-lot items.

   Done whentools/verify.py prints MATCH on an identical file and an offset on a changed one, and the hook blocks edits to it.

   Proof this works: supercolumnsgg-disasm (SHA-1 check in assemble.sh), KishinDoujiZenkiDecomp (tools/build.py and tools/verify.py), https://github.com/vhelin/wla-dx

3. First light: a disassembly that rebuilds the ROM

   You turn the whole ROM into assembly that rebuilds byte for byte. At first, most of it is raw data. That is fine. The point is a source tree that passes the byte check from day one.

   • Export a first listing from Emulicious, as Super Columns did. Or write a bank-aware tracer in Python, as Zenki and MMPR did.
   • Set the WLA DX memory map with .MEMORYMAP and .ROMBANKMAP. Put each 16 KB bank under its own .BANK and .ORG.
   • Keep unknown spans as .INCBIN files named by address.
   • Build and run python tools/verify.py <ABSOLUTE_PATH_TO_ROM> build/game.gg.
   • Commit only when it prints MATCH. Never commit the ROM or any .bin cut from it.
   Prompt for ClaudeCopy

   GOAL: Produce a WLA DX source tree that rebuilds <GAME> byte for byte.
   READ FIRST: SCOPE.md, `<LISTING_PATH>` (the Emulicious export or tracer output), https://wla-dx.readthedocs.io/en/latest/asmdiv.html
   FENCE: Edit only `src/`, `game.link` and scripts under `tools/disasm/`. Do not edit `tools/verify.py`. Keep ROM-derived `.bin` files in the ignored `extracted/` folder.
   CHECK: Run `build.bat` then `python tools/verify.py <ABSOLUTE_PATH_TO_ROM> build/game.gg`. Done means it prints MATCH.
   BUDGET: Stop after 3 hours or 5 builds that do not move the first differing offset.
   IF BLOCKED: Stop. Paste the first differing offset, its bank, and both byte runs.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the verify output. 3) Files changed. 4) How much is code and how much is still raw data. 5) New parking-lot items.

   Done whentools/verify.py prints MATCH on a build from a clean checkout.

   Proof this works: supercolumnsgg-disasm (Emulicious export rebuilt by WLA DX), MMPR: The Movie, Game Gear to PC (all 32 banks reassemble byte-identical), KishinDoujiZenkiDecomp (both ROMs rebuild byte for byte)

4. Sort code from data and label it

   Now you turn raw bytes into named routines and named data. You trace code while tracking which bank is live. You mark every claim as confirmed or supposed. One unit is one routine or one table.

   • Run a tracer that follows jumps and calls and tracks bank writes to $FFFD, $FFFE and $FFFF. Have it list jump tables it finds.
   • Check the tracer against z80dasm in WSL. Test your decoder by round-tripping every documented Z80 instruction.
   • Log the addresses the game really runs, with an Emulicious trace log. Add those to the code list.
   • Write notes/functions.csv with address, bank, size, name, status (confirmed or supposed) and proof.
   • Rebuild and verify after every rename. Once the source is stable, add a FROZEN marker so the generator stops overwriting hand edits.
   Prompt for ClaudeCopy

   GOAL: Label routine <ADDRESS> (bank <BANK>) in <GAME> and mark it confirmed or supposed.
   READ FIRST: `notes/functions.csv`, `src/<FILE>.asm` around <ADDRESS>, `notes/ram-map.md`
   FENCE: Edit only labels and comments in `src/<FILE>.asm`, plus `notes/functions.csv` and `notes/ram-map.md`. Do not change any instruction or byte.
   CHECK: Run `build.bat` then `python tools/verify.py <ABSOLUTE_PATH_TO_ROM> build/game.gg`. Done means it prints MATCH and the CSV row names its proof: a caller, a trace hit, or a RAM write.
   BUDGET: Stop after 30 minutes on one routine.
   IF BLOCKED: Stop. Mark the routine supposed and say what proof is missing.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: verify output and the CSV row. 3) Files changed. 4) New questions. 5) New parking-lot items.

   Done whenEvery routine in notes/functions.csv is confirmed or supposed with proof, and the build still prints MATCH.

   Proof this works: KishinDoujiZenkiDecomp (confirmed vs supposed marks; 73 routines still supposed), Devilish PSP (static survey plus recorded sessions), https://packages.ubuntu.com/noble/z80dasm

5. Split the art, levels and sound into files

   A port needs data you can read and change. You extract each data format to an editable file. The build converts them back. The byte check proves nothing changed by accident.

   • Write one extractor per format in Python: tiles to PNG, tile maps and levels to CSV, scripts to text.
   • Write the matching packer. The build calls it before wla-z80.
   • Make the build refuse to overwrite an edited asset unless you pass FORCE=1.
   • Watch for fixed slots. If a split section grows past its old size, the ROM breaks. Keep a size check in the build.
   • Rebuild and verify after every split.
   Prompt for ClaudeCopy

   GOAL: Split the <FORMAT> data at <ADDRESS_RANGE> of <GAME> into editable files that rebuild byte for byte.
   READ FIRST: `notes/functions.csv`, `notes/data-formats.md`, the routine that reads this data at <READER_ADDRESS>
   FENCE: Edit only `tools/assets/`, `assets/<FORMAT>/`, the `.INCBIN` or include lines in `src/`, and `notes/data-formats.md`. Do not change code bytes.
   CHECK: Run `build.bat` then `python tools/verify.py <ABSOLUTE_PATH_TO_ROM> build/game.gg`. Done means it prints MATCH and an edited asset changes the ROM only in its own range.
   BUDGET: Stop after 2 hours or 3 failed round trips.
   IF BLOCKED: Stop. Describe the bytes you cannot explain.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: verify output. 3) Files changed. 4) What the format is, in two lines. 5) New parking-lot items.

   Done whenEvery split format round-trips to MATCH, and the format is written in notes/data-formats.md.

   Proof this works: KishinDoujiZenkiDecomp (PNG, CSV and script assets, FORCE=1 rule), Sonic-1-Game-Gear-Disassembly (build breaks if a split overflows), Sonic Chaos (Master System version) disassembly (flashes colours when a split grows)

6. Build the reference and one C routine

   Now the unproven part begins. You need an oracle: a Z80 interpreter plus a hardware model that runs the original code. Then you rewrite one small routine in C. A hook calls your C instead of the Z80 code, and the test compares the state after each call.

   • Use an interpreter that passes zexdoc and zexall, such as superzazu/z80. In WSL, run sudo apt install build-essential, then make && ./z80_tests in its folder.
   • Wrap it with a video, sound and mapper model. Or reuse the smsggrecomp runtime from Path A.
   • Record sessions as inputs plus a hash of RAM, VRAM and palette RAM for each frame.
   • Pick a leaf routine: one that calls nothing. Write it in C. Hook its address so the interpreter calls your C.
   • Replay the sessions with the hook on. Every frame hash must still match.
   Prompt for ClaudeCopy

   GOAL: Rewrite leaf routine <ADDRESS> of <GAME> in C and prove it with the session hashes.
   READ FIRST: `notes/functions.csv`, `src/<FILE>.asm` at <ADDRESS>, `tests/sessions/`, https://github.com/superzazu/z80 (README)
   FENCE: Edit only `c/<NAME>.c`, `c/hooks.c` and `notes/c-progress.md`. Do not edit the interpreter core, the sessions or their hashes.
   CHECK: Run `python tools/replay.py --all --hook <ADDRESS>`. Done means every session matches every frame with the hook on, and the hook was called at least once.
   BUDGET: Stop after 5 failed tries.
   IF BLOCKED: Stop. Report the first differing frame and the RAM bytes that differ.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: replay output and hook call count. 3) Files changed. 4) What the routine does. 5) New parking-lot items.

   Done whenAll sessions match every frame with the C routine hooked in, and the hook count is above zero.

   Proof this works: MMPR: The Movie, Game Gear to PC (interpreter passes zexdoc and zexall, used as oracle), Devilish PSP (reference interpreter, per-frame picture and audio CRCs), https://github.com/superzazu/z80

7. Grind: every routine as C, leaves first

   You repeat the last step for every routine. Leaves go first, then their callers. Each worker takes one routine and proves it with the same replay. Some code will fight you: jump tables, pushed returns and code copied into RAM.

   • Sort notes/functions.csv so routines with no unconverted callees come first.
   • Give each worker one routine, its own git worktree and the replay check.
   • Treat code copied into RAM as its own unit. Capture it from an interpreter RAM image, as Devilish did with its sound driver.
   • Write odd control flow plainly in C. Name each case in notes/c-progress.md.
   • Merge one batch at a time. Rerun every session after each merge.
   Prompt for ClaudeCopy

   GOAL: Convert the next <N> ready routines of <GAME> to C, one worker each.
   READ FIRST: `notes/functions.csv` (rows with status ready), `notes/c-progress.md`, one finished C routine as an example
   FENCE: Each worker edits only `c/<NAME>.c` and its hook line in its own worktree. The lead edits `notes/` only. Nobody edits sessions, hashes or the interpreter.
   CHECK: After each merge, run `python tools/replay.py --all`. Done means every session matches every frame, and each merged routine's hook was called.
   BUDGET: Each worker stops after 5 failed tries. The lead stops after <N> routines or 3 hours.
   IF BLOCKED: Stop that unit. Mark it hard in the CSV with the first differing frame.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: replay summary after the last merge. 3) Files changed. 4) Routines left, from the CSV. 5) New parking-lot items.

   Done whenEvery routine in notes/functions.csv is C, every session matches, and no Z80 code runs except the boot stub.

   Proof this works: MMPR: The Movie, Game Gear to PC (push-and-jump dispatch and RAM-built OUTI code handled), Devilish PSP (sound driver captured from a RAM image), KishinDoujiZenkiDecomp (a C rewrite was tried and abandoned, so expect this to be slow)

8. Port: build it for another system

   You put the video, sound and input behind one small interface. Then you write a back end for the new system. The same sessions must match on the new build. Devilish did this with recompiled C on a PSP.

   • Put every port write and read behind hw_ functions in one header. The game code calls only those.
   • Write a PC back end with SDL2 first. Check it against the sessions.
   • For a PSP target, install pspdev in WSL by its Windows guide, including its apt-get list. Build with psp-cmake and make.
   • Build in WSL on the Linux disk, not under /mnt/c. It is much faster.
   • Run the same sessions on each target. Compare per-frame picture and audio CRCs.
   Prompt for ClaudeCopy

   GOAL: Build <GAME> from C for <TARGET> and match the reference sessions there.
   READ FIRST: `notes/c-progress.md`, `c/hw.h`, https://pspdev.github.io/installation/windows.html (if the target is PSP), the README of https://github.com/slimhagrid/Devilish-PSP
   FENCE: Edit only `port/<TARGET>/` and `c/hw.h`. Do not change game routines in `c/`. Do not change sessions or hashes.
   CHECK: Run the sessions on the <TARGET> build, or its emulator, and compare frame CRCs. Done means every session matches.
   BUDGET: Stop after 4 hours or 3 failed builds with the same error.
   IF BLOCKED: Stop. Paste the error or the first differing frame.
   OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
   REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: CRC comparison per session. 3) Files changed. 4) What was not tested on real hardware. 5) New parking-lot items.

   Done whenEvery session matches on the new system, and the build ships no ROM data.

   Proof this works: Devilish PSP (same CRCs on the interpreter, a PC build and PPSSPP), KishinDoujiZenkiDecomp (one source builds a Game Gear and a Master System ROM), Tails Adventure Remake (one C++ code base for PC and Android)

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 Game Gear work by address, by bank and by route. On Path A, one unit is one dispatch miss, one divergent frame, or one runtime bug, each tied to a route. On Path B, one unit is one routine to label, one data format to split, or one routine to rewrite in C. Every unit has one check: an empty miss log, a suite report, a MATCH line, or a session replay. Always name the bank with the address.

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 generated C under `generated/`. Fix the recompiler, the runtime or `game.toml`, then regenerate.
- No stubs. If execution reaches unknown code, stop and find the real routine. Never fake its effect.
- Function starts come from the ROM listing, never from `dispatch_misses.log` alone. Name the bank with every address.
- After every run, `dispatch_misses.log` must be empty. Interpreter fallback is not a finished recompilation.
- Debug the first divergent frame, never the last visible symptom.
- The Game Gear is the Master System plus a `platform` flag. Never fork the engine for Game Gear work.
- The one check is `powershell -File tools/check.ps1 '<ABSOLUTE_PATH_TO_ROM>'` (Path A) or `python tools/verify.py <ABSOLUTE_PATH_TO_ROM> build/game.gg` (Path B). No pasted output means not done.
- Do not edit `tests/coverage/`, expected hashes, `tools/verify.py` or check scripts. A change needs my approval.
- The ROM lives at `<ABSOLUTE_PATH_TO_ROM>`. Never copy, commit or paste it or bytes cut from it.
- Close old copies with `taskkill /F /IM <EXE>` before each run (in Git Bash: `taskkill //F //IM <EXE>`). Run one copy at a time.
- In a worktree, use absolute paths for the ROM and tools.
- Never commit without my say-so. A fix is done only after I confirm it in the game.
- 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.
• Pass an address and its bank. Let Claude read only that routine in the listing.
• Give Claude the first divergent frame and the two capture files that differ, not whole logs.
• Do not paste a 390 KB disassembly. Split it into one file per bank first.
• Add Read deny rules for generated/**, build/** and coverage-*/**.
• Clear the chat after each unit. The ledgers 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> (<REGION>, CRC32 <CRC32>) suits Path A, Path B, or both, and draft SCOPE.md.
READ FIRST: bytes $7FF0-$7FFF of `<ABSOLUTE_PATH_TO_ROM>`, https://github.com/mstan/smsggrecomp/blob/main/CLAUDE.md, https://www.smspower.org/Development/ROMHeader
FENCE: Create only `SCOPE.md` and `notes/prior-work.md`. No code. Do not copy the ROM.
CHECK: Done means SCOPE.md lists ROM size, header text, region digit, CRC32, SHA-1, mapper guess, prior work with links, 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 output and hashes. 3) Files changed. 4) Risks you see. 5) New parking-lot items.

GOAL: Map bank <BANK> of <GAME> into routines and data, with proof for each start.
READ FIRST: `notes/functions.csv`, the Emulicious or Ghidra listing for bank <BANK>, an Emulicious trace log at `<TRACE_PATH>`
FENCE: Edit only `notes/functions.csv` and `notes/banks.md`. Do not edit `game.toml` yet. Do not edit code.
CHECK: Done means every byte range in bank <BANK> is code, data or unknown, every routine start names its proof, and the totals add up to 16,384 bytes.
BUDGET: 2 hours.
IF BLOCKED: Stop. List the ranges you could not sort and why.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: counts by type and the byte total. 3) Files changed. 4) Jump tables found. 5) New parking-lot items.

GOAL: Remove dispatch miss <ADDRESS> (bank <BANK>) or the first divergence in route <RUN> for <GAME>.
READ FIRST: `dispatch_misses.log`, the suite report for <RUN>, the listing at <ADDRESS>, `notes/divergence-log.md`
FENCE: Edit only `game.toml`, `notes/functions.csv`, `notes/divergence-log.md` and runtime files named in CLAUDE.md. Never edit `generated/` or `tests/coverage/`.
CHECK: Rebuild and run the coverage suite. Done means the miss is gone or the divergence moved later, and no other route got worse.
BUDGET: Stop after 3 failed tries or 45 minutes.
IF BLOCKED: Stop. Paste 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: suite summary before and after. 3) Files changed. 4) What is left. 5) New parking-lot items.

GOAL: Rewrite routine <ADDRESS> (bank <BANK>) of <GAME> in C and prove it.
READ FIRST: `src/<FILE>.asm` at <ADDRESS>, `notes/functions.csv`, one finished routine in `c/` as an example
FENCE: Edit only `c/<NAME>.c`, its hook line and its CSV row. Do not edit sessions, hashes, the interpreter or other routines.
CHECK: Run `python tools/replay.py --all --hook <ADDRESS>`. Done means every session matches every frame and the hook ran at least once.
BUDGET: Stop after 5 failed tries.
IF BLOCKED: Stop. Mark the row hard and report the first differing frame and bytes.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`. Do not fix them.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: replay output and hook count. 3) Files changed. 4) What the routine does. 5) New parking-lot items.

GOAL: Pick the next <N> units for <GAME> and start one worker per unit.
READ FIRST: `PROGRESS.md`, `notes/functions.csv` or `dispatch_misses.log`, `notes/parking-lot.md`
FENCE: The lead edits only `notes/`. Each worker gets one task card, its own git worktree, and absolute paths to the ROM and tools. No two workers touch the same file.
CHECK: After each merge, run the one check from CLAUDE.md. Done means every merged unit passes it on the merged branch, not only in its worktree.
BUDGET: Stop after <N> units or 3 hours.
IF BLOCKED: Stop that worker. Mark the unit hard with its evidence.
OTHER PROBLEMS: Workers write them in `notes/parking-lot.md`.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: check output after the last merge. 3) Units done and units marked hard. 4) What to send next. 5) New parking-lot items.

GOAL: Find the cause of <SYMPTOM> in <GAME> at about frame <FRAME>. Do not fix it yet.
READ FIRST: `notes/divergence-log.md`, https://github.com/mstan/smsggrecomp/blob/main/COVERAGE.md (route controls), the route that shows the bug
FENCE: Read only, except new probe routes in `tests/probe/`. No game or runtime fixes.
CHECK: Run the probe route native and with `--interp`, then compare the capture files. Done means you name the first frame where native and interpreter differ, the first differing byte, the code that wrote it and the bank that was live.
BUDGET: 90 minutes.
IF BLOCKED: Stop. Say which data you need that no capture records.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the two capture files that differ and the writer. 3) Files changed. 4) The cause in one sentence and a proposed fix. 5) New parking-lot items.

GOAL: Check that the work in <BRANCH_OR_COMMITS> for <GAME> is real.
READ FIRST: `git diff <BASE>..<BRANCH_OR_COMMITS>`, CLAUDE.md, the last report
FENCE: Read only. Do not fix anything.
CHECK: Rerun the one check from CLAUDE.md from a clean build. Then look for: edits in `generated/`, stubs or fake events, changed captures or hashes, edits to `verify.py` or check scripts, routes deleted or shortened, fallback counted as done, and files outside the fence.
BUDGET: 60 minutes.
IF BLOCKED: Stop. Say what you could not rerun.
OTHER PROBLEMS: Write them in `notes/parking-lot.md`.
REPORT: 1) PASS or FAIL. 2) Proof: the check output. 3) Each problem with file and line. 4) Claims you could not confirm. 5) New parking-lot items.

GOAL: Report the state of <GAME> with numbers only.
READ FIRST: `PROGRESS.md`, `notes/functions.csv`, the latest suite report or verify output
FENCE: Edit only `PROGRESS.md`.
CHECK: Done means each number comes from a file or a command you ran now.
BUDGET: 15 minutes.
IF BLOCKED: Stop. Say which number you could not get.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Routes passing, misses left, fallback cycles, routines confirmed, supposed and in C. 3) Files changed. 4) Top three blockers. 5) New parking-lot items.

GOAL: Write what the next session needs to carry on with <GAME>.
READ FIRST: `PROGRESS.md`, `notes/divergence-log.md`, `notes/findings.md`, this session's work
FENCE: Edit only `PROGRESS.md`, `notes/findings.md` and `notes/handoff.md`.
CHECK: Done means a fresh session could start from `notes/handoff.md` alone: the current unit, its last check output, dead ends tried, and the next command to run.
BUDGET: 15 minutes.
IF BLOCKED: Stop. Say what you could not record.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof: the handoff text. 3) Files changed. 4) The next unit. 5) New parking-lot items.

GOAL: Tell me plainly whether <UNIT> for <GAME> can be done, and what it would take.
READ FIRST: the unit's notes, the last three reports, `notes/findings.md`
FENCE: Read only.
CHECK: Done means you give one answer: can do, can do with <CHANGE>, or cannot do. Each answer needs proof from a listing, a log or a check output.
BUDGET: 30 minutes.
IF BLOCKED: Say what data would settle it.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof. 3) Files changed: none. 4) Options with their cost in hours. 5) New parking-lot items.

GOAL: Ask me to approve a change outside the fence for <GAME>. Do not make it.
READ FIRST: SCOPE.md, CLAUDE.md, the evidence that the change is needed
FENCE: Read only. No edits until I say yes.
CHECK: Done means you state the change, the files it touches, why the current fence cannot solve the unit, and how we will check it.
BUDGET: 15 minutes.
IF BLOCKED: Say what you still need to know.
REPORT: 1) DONE, PARTIAL or BLOCKED. 2) Proof of need. 3) Files that would change. 4) Risk to other games or routes. 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 your game is on smsggrecomp already, or close to one that is. Sonic games share engines.
• Whether a disassembly exists for your game or its Master System version.
• How much code hides behind jump tables, pushed returns and code copied into RAM.
• How many banks the game uses. Each bank adds places where the same address means different code.
• On Path B, how far you go. A matching disassembly took days with Claude. A C rewrite has no finished example.
• 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)

There are fewer than 10 games on RecompLauncher for the Game Gear: it lists one, Tails Adventure. We found six more Game Gear projects outside it, and no others. The Sonic Retro and Sega Retro lists blocked our reader, so we may have missed one there. To reach ten, we added three Master System projects. The Master System uses the same chip, video and sound, and each is marked as the Master System version.

What each project teaches

What we could not check

• Which assembler Sega's teams used for Game Gear games. No source we read says.
• That no retail Game Gear game was written in C. We found none, but did not check every game.
• Whether Ghidra-SegaMasterSystem-Loader, last pushed in 2019, loads in Ghidra 12.2.
• No step in this guide was run for this check. Nothing was built and no ROM was used. Commands were checked against docs and source code only. The hash one-liner was run on a made-up test file.
• Whether a game other than Sonic Blast builds on smsggrecomp without framework changes. Only two games use it so far.
• The Path B steps for a C rewrite with hooked routines. No Game Gear project has done this. The method comes from Genesis projects.
• How long MMPR and Devilish took before their first public commit. Both hide their history.
• Whether MMPR and Devilish used AI. Neither says.
• The verification numbers of MMPR, Devilish and Zenki. They are the authors' own claims.
• The script names tools/check.ps1, tools/verify.py, tools/replay.py and scan_rom_bytes.py. They follow the reviewed projects; you write your own.
• The Sonic Retro and Sega Retro disassembly lists. Bot checks blocked them, so we may have missed a project hosted only there.
• The TCP debug server in smsggrecomp's DEBUG.md (state, frame, rdb_window). Its runner/main.c parses no --port flag, though CLAUDE.md still shows --port 4390. The guide does not rely on it.
• Whether every capture can match. Sonic Blast still has one ring-icon capture that differs by 33 pixels.

Sources

• smsggrecomp README
• smsggrecomp CLAUDE.md
• smsggrecomp PRINCIPLES.md
• smsggrecomp COVERAGE.md
• smsggrecomp DEBUG.md
• smsggrecomp ACCURACY.md
• smsggrecomp runner command line (runner/main.c)
• smsggrecomp game build script
• smsggrecomp coverage suite runner
• SonicBlastGGRecomp suite.json
• SonicBlastGGRecomp README
• SonicTheHedgehogSMSRecomp README
• KishinDoujiZenkiDecomp
• SMS Power: ROM header
• SMS Power: Mappers
• SMS Power: Game Gear VDP
• SMS Power: Game Gear I/O port map
• SMS Power: Palette
• Wikipedia: Game Gear
• WLA DX repository
• WLA DX directives
• Mesen Community Edition
• Emulicious
• SDCC
• z80dasm in Ubuntu 24.04
• Ghidra
• Ghidra Sega Master System and Game Gear loader
• superzazu z80
• pspdev Windows install guide
• pspdev releases
• SDCC 4.6.0 source: Z80 assembler build file
• Original Mesen2 repo (archived)
• MSYS2
• Sonic Chaos (Master System) disassembly
• Sonic 2 (Master System) disassembly