C64_SKILLS/.ai/skills/debugging-monitor/SKILL.md

Skill: Debugging with Monitors, Assemblers, Disassemblers, and Emulators

Use this skill when

The task involves entering ML, inspecting memory, using monitors, disassembling ROM/RAM, debugging crashes, emulator setup, or converting between BASIC loaders and assembly.

Core tools

• Machine-language monitor: inspect/change memory and registers, run code, break, disassemble.
• Assembler: converts mnemonics to opcodes.
• Disassembler: converts opcodes back to mnemonics.
• Emulator monitor: VICE monitor is excellent for breakpoints/watchpoints.

Common monitor activities

• Memory dump: inspect bytes at an address.
• Assemble line: write one instruction at an address.
• Disassemble range: inspect ML/ROM code.
• Fill memory: clear or initialize a range.
• Hunt/search: find byte patterns such as 20 D2 FF for JSR $FFD2.
• Register view: inspect A/X/Y/SP/PC/flags.

Debugging workflow

1. Confirm load address and SYS start address.
2. Verify first bytes in memory match assembled output.
3. Put BRK in suspected code path when using a monitor.
4. Single-step through register changes.
5. Check stack if RTS returns to nonsense.
6. Check zero-page pointers for little-endian order.
7. Check interrupt state and banking register $01 after crashes.
8. Reset emulator snapshots frequently.

Crash checklist

• Did the routine end with RTS when called by SYS?
• Did code overwrite BASIC text or variables?
• Did code corrupt $01 and bank out KERNAL/BASIC unexpectedly?
• Did an IRQ vector point to invalid memory?
• Was a hardware interrupt acknowledged?
• Did the stack underflow/overflow?
• Was PETSCII/screen code confused with ASCII?

Agent checklist

When helping debug:

1. Ask for start address, assembler, and emulator if not provided.
2. Request or infer memory map touched by the code.
3. Provide monitor commands conceptually, not tied to one monitor unless specified.
4. Use small reproducible examples.