trace-detective

Translates Meson2 trace opcode streams into root-cause narratives for experts.

Updated Dec 30, 2025

Search Tags:#debugging #trace #narrative-generation #crash-analysis #trace-analysis #mesen2 #z3ed

Ready to run

npx skills add https://github.com/scawful/afs_scawful --skill trace-detective

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: trace-detective
Source: https://github.com/scawful/afs_scawful/tree/main/skills/trace-detective
Command: npx skills add https://github.com/scawful/afs_scawful --skill trace-detective

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Trace Detective helps debugging Mesen2 traces by capturing and translating low-level traces into actionable insights for expert review.

Core Features & Use Cases

Trace Capture: Use z3ed to pull the last N instructions or run forward with logging.
Signal Filtering: Filter for control flow changes and key RAM/register writes to identify crash vectors.
Narrative Generation: Convert traces into high-level narratives suitable for handoffs to experts.
Expert Handoff: Package a Debug Context Pack for Qwen/Claude including summaries, relevant ASM, and memory snapshots.

Quick Start

Capture the last 60 frames of execution trace and generate a concise narrative debug summary for expert handoff.

Frequently Asked Questions about trace-detective

High-intent search queries and answers about installing and using this skill.

FAQPage Schema

How do I analyze Mesen2 execution traces to find the root cause of a crash?▼

To analyze Mesen2 execution traces, you capture opcode streams using z3ed and filter for control flow changes, key RAM writes, and critical registers to identify crash vectors. Trace Detective automates this by translating low-level traces into high-level narratives.

Do I need z3ed and a running Mesen2 instance to capture and debug traces?▼

Yes, you need z3ed available in your PATH and a running Mesen2 instance with an active socket server. These prerequisites are required to pull instruction logs, reproduce the crash, and capture the execution trace for analysis.

Can I generate a debug summary of opcode streams for expert handoff?▼

You can generate a debug summary by converting opcode streams into high-level narratives. Trace Detective packages a Debug Context Pack that includes summaries, relevant ASM, and memory snapshots suitable for handoff to experts like Qwen or Claude.

What is the best way to filter signal noise from Mesen2 trace logs?▼

The best way to filter signal noise from Mesen2 trace logs is to isolate control flow changes and critical register writes. By focusing on subroutine boundaries and specific RAM writes, you can narrow down the exact crash vector.

How does translating opcode streams into high-level narratives work for trace analysis?▼

Translating opcode streams into high-level narratives works by mapping low-level execution instructions to subroutine boundaries and memory states. This process highlights the logical sequence of events leading to a failure, making complex trace analysis readable.

Does trace analysis work without an active socket server in Mesen2?▼

No, trace analysis requires an active socket server in Mesen2 to reproduce and capture the execution traces. Without the socket server, z3ed cannot pull the last N instructions or run forward with logging to identify the crash.