debug-run-transcript-maintainer

Debug Run Transcript

Analyze Rudder agent runs by reconstructing the execution story from the best available source.

Purpose

Runs fail for several different reasons:

• the model/runtime emitted an error
• the transcript parser missed useful structure
• the event stream is incomplete
• the stored excerpts are too shallow
• a tool call succeeded, but Rudder's message/run lifecycle marked the workflow failed during stream finalization, persistence, or UI status mapping
• the operator has only a partial run ID or limited context

This skill helps diagnose those cases without getting stuck on the wrong data source.

Debugging proves what happened in a run; it does not by itself prove that a product fix works. When a transcript diagnosis leads to a code, CLI, skill, runtime, or UI change, hand the work back to the lifecycle verification path and require product proof for the affected actor and terminal surface.

Source Priority

Always use sources in this order:

1. Run-intelligence loader/API
   • Best default.
   • Reads run metadata, run events, and the underlying run log.
   • Reconstructs transcript entries with runtime-specific parsers.
2. Filesystem run log fallback
   • Use when the local API is unavailable but run logs exist on disk.
   • Good for transcript/tool-call reconstruction.
3. Direct database queries
   • Use only for targeted checks or when the first two paths are unavailable.
   • DB rows alone are not the full transcript story.

Important Lessons / Known Traps

• Do not assume ~/.rudder/instances/dev/postgres-uri exists. In this repo it is not a reliable universal entrypoint.
• Do not start with heartbeat_run_events and assume they are the complete transcript. They are supplemental run events, not the full parsed execution trace.
• Do not write WHERE id LIKE 'prefix%' against uuid columns. Cast first: id::text ILIKE 'prefix%'.
• Do not assume pnpm exec tsx works from the repo root here. Prefer the repo-local launcher: