Crash Investigator

crash-investigator

Autonomous crash analysis for Mesen2. Captures execution traces upon crash/pause, resolves symbols using z3ed, and generates annotated reports for debugging.

scawful/afs_scawful·0installs0stars

SKILL.md

Full skill instructions

Crash Investigator

Scope

Detection: Monitors Mesen2 for pauses (breakpoints) or manual triggers.
Data Capture: Retrieves CPU state (registers) and execution trace (PC history).
Analysis: Resolves raw addresses to symbols and source lines using z3ed.
Reporting: Generates Markdown reports ready for LLM consumption.

Core Capabilities

1. Manual Dump

Trigger an immediate analysis of the current state.

dump: "I just saw a crash, analyze it."

2. Monitoring (The Sentinel)

Run in background to catch intermittent crashes.

monitor: Polls emulator state. If it pauses (hit breakpoint/crash), auto-dumps.

3. Trace Blame

Maps the execution history to source code.

Uses z3ed rom-resolve-address to turn $07B107 into Link_ResetProperties (Link.asm:45).

Workflow

Start Monitor: crash-investigator monitor.
Repro Bug: Play game until it crashes (CPU JAM / Breakpoint).
Auto-Dump: Tool detects pause, captures trace, resolves symbols.
Review: Read crash_reports/crash_20260125_120000.md.
Reason: Paste report into LLM: "Why did it crash at Link_Update?"

Dependencies

Tool: ~/src/hobby/yaze/scripts/ai/crash_dump.py
Mesen2: Must be running with socket server.
z3ed: Must be built with symbol support.
Symbols: ROM directory must contain .mlb or .sym files.

Example Prompts

"Monitor for crashes while I play the dungeon."
"Dump the current state; the game is softlocked."
"Analyze the last crash report."

Troubleshooting

No Trace Data: Ensure Mesen2 trace logging is enabled (internal buffer).
No Symbols: Check if .mlb file exists next to ROM. Run z3ed rom-resolve-address to verify.
Connection Error: Restart Mesen2.

Install skill

Copy and run in your terminal

npx -y skills add https://github.com/scawful/afs_scawful --skill crash-investigator

View on GitHub

skills/crash-investigator/SKILL.md

diff-runner
Regression testing tool for Oracle of Secrets. Records gameplay scenarios and replays them on new builds to detect logic bugs or desyncs.
0 installs
trace-detective
Trace analysis expert for Mesen2 debugging. Captures execution logs, filters for key state changes (subroutines, RAM writes), and summarizes failure chains for expert consultation.
0 installs
visual-verifier
Visual verification agent for ROM hacks. Compares emulator screenshots against "Golden Masters" to detect regressions, glitches, or UI errors.
0 installs
sprite-forge
SNES pixel art asset pipeline assistant. specialized in palette management, sprite sheet slicing, and 4bpp conversion workflows for Oracle of Secrets.
0 installs

More skills from scawful

scawful/afs_scawful

asm-guru

Expert SNES 65816 Assembly coding assistant. specialized in Oracle of Secrets architecture, memory maps, optimization patterns, and safe routine scaffolding.

0 0

View

scawful/afs_scawful

Train, evaluate, and maintain the scawful-echo persona and related avatar models (Echo/Memory/Muse). Use when working on persona voice, dataset prep, A/B testing, deployment, or tool-calling constraints for avatar models.

0 0

View

scawful/afs_scawful

chaos-monkey

Automated fuzzer for Oracle of Secrets. Injects random inputs to stress-test the game engine and detect crashes or softlocks.

0 0

View

scawful/afs_scawful

mesen2-oos-cli

Deprecated alias for the Mesen2-OOS debugging workflow. Use when older prompts mention mesen2-oos-cli; redirect to mesen2-oos-debugging instead.

0 0

View

scawful/afs_scawful

code-navigator

Static analysis tool for ASM codebases. Builds call graphs, finds callers/callees, and identifies memory write locations.

0 0

View

scawful/afs_scawful

model-training-expert

Expert guidance for LLM model training, synthetic data generation (SDE), Hierarchical MoE (H-MoE) management, and agentic evaluation. Use when setting up training runs (Vast.ai), generating datasets, or performing technical research PDF analysis for ROM hacking and general AI development.

0 0

View

scawful/afs_scawful

mesen2-oos-debugging

End-to-end Oracle of Secrets debugging using the Mesen2-OOS socket CLI, z3ed, and label/symbol tooling. Use for breakpoint/trace capture, memory inspection, savestate repro, overlays, or crash/regression triage (replaces mesen2-mcp and legacy Lua bridge workflows).

0 0

View

scawful/afs_scawful

agentic-context

Use the Agentic File System (AFS) context model for discovery, mounts, scratchpad memory, and file-based tool workflows. Use when a task involves .context operations, AFS CLI usage, or cross-agent context coordination.

0 0

View

scawful/afs_scawful

romhack-asm-tuner

SNES Assembly (65816) patch manager. Curates ASM snippets, verifies patches with Asar/Z3DK, and manages the code library for Oracle of Secrets.

0 0

View

scawful/afs_scawful

memory-cartographer

Dynamic RAM analyzer for SNES debugging. Monitors memory ranges in real-time via Mesen2 to identify unknown variables, detect changes, and map memory usage.

0 0

View

scawful/afs_scawful

semantic-query

High-level state query tool for Oracle of Secrets. Maps natural language questions ("is_safe", "has bow") to complex RAM inspections.

0 0

View

scawful/afs_scawful

alttp-disasm-labels

Read and interpret the Link to the Past (ALTTP) disassembly with label/symbol context. Use when mapping ROM/CPU addresses to labels, searching usdasm/jpdasm sources, or cross-referencing routines with Hyrule Historian, z3dk label indexes, or z3ed output.

0 0

View