[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6K2YG63DJWP9W8NPFHTJT0F":3,"skill-same:01M6K2YG63DJWP9W8NPFHTJT0F":74},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":40,"linkOnly":41,"markdownContent":42,"markdownBody":43,"frontMatter":44,"refName":45,"commitSha":46,"skillDirectory":47,"forksCount":48,"repositoryHtmlUrl":49,"repositoryHomepageUrl":50,"ownerHtmlUrl":51,"ownerBlogUrl":6,"ownerDescription":52,"updatedAt":53,"install":54,"resources":67},"01M6K2YG63DJWP9W8NPFHTJT0F","debug-run-transcript-maintainer",null,"Use when analyzing one Rudder agent run or recent run batches: run IDs, partial IDs, transcripts, run logs, execution traces, runtime failures, finalizer failures, stdout\u002Fstderr, run quality, or recent org run behavior.","Undertone0809\u002Frudder","Undertone0809","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F72488598?v=4","01M6K2XANP3QJEF503JX2C693T","Zeeland","01M6K2XATQXEYF7N2QG8KZVEEY",296,"Apache-2.0","https:\u002F\u002Fgithub.com\u002FUndertone0809\u002Frudder\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fmaintainer\u002Fdebug-run-transcript-maintainer\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[24,25,26,27,28,29,30,31,32,33,34,35,36,37,38,39],"debug","run","transcript","debug run transcript maintainer","logs","analyzing","ids","execution","quality","behavior","use","runtime","org","transcripts","batches","traces","2026-11-10 10:12:30",false,"---\nname: debug-run-transcript-maintainer\ndescription: \"Use when analyzing one Rudder agent run or recent run batches: run IDs, partial IDs, transcripts, run logs, execution traces, runtime failures, finalizer failures, stdout\u002Fstderr, run quality, or recent org run behavior.\"\n---\n\n# Debug Run Transcript\n\nAnalyze Rudder agent runs by reconstructing the execution story from the best available source.\n\n## Purpose\n\nRuns fail for several different reasons:\n- the model\u002Fruntime emitted an error\n- the transcript parser missed useful structure\n- the event stream is incomplete\n- the stored excerpts are too shallow\n- a tool call succeeded, but Rudder's message\u002Frun lifecycle marked the\n  workflow failed during stream finalization, persistence, or UI status mapping\n- the operator has only a partial run ID or limited context\n\nThis skill helps diagnose those cases without getting stuck on the wrong data source.\n\nDebugging proves what happened in a run; it does not by itself prove that a\nproduct fix works. When a transcript diagnosis leads to a code, CLI, skill,\nruntime, or UI change, hand the work back to the lifecycle verification path and\nrequire product proof for the affected actor and terminal surface.\n\n## Source Priority\n\nAlways use sources in this order:\n\n1. **Run-intelligence loader\u002FAPI**\n   - Best default.\n   - Reads run metadata, run events, and the underlying run log.\n   - Reconstructs transcript entries with runtime-specific parsers.\n2. **Filesystem run log fallback**\n   - Use when the local API is unavailable but run logs exist on disk.\n   - Good for transcript\u002Ftool-call reconstruction.\n3. **Direct database queries**\n   - Use only for targeted checks or when the first two paths are unavailable.\n   - DB rows alone are not the full transcript story.\n\n## Important Lessons \u002F Known Traps\n\n- Do **not** assume `~\u002F.rudder\u002Finstances\u002Fdev\u002Fpostgres-uri` exists. In this repo it is not a reliable universal entrypoint.\n- 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.\n- Do **not** write `WHERE id LIKE 'prefix%'` against `uuid` columns. Cast first: `id::text ILIKE 'prefix%'`.\n- Do **not** assume `pnpm exec tsx` works from the repo root here. Prefer the repo-local launcher:\n\n```bash\nnode cli\u002Fnode_modules\u002Ftsx\u002Fdist\u002Fcli.mjs ...\n```\n\n- Do **not** treat `stdout_excerpt` \u002F `stderr_excerpt` as the whole log. They are quick diagnostics only.\n- If `\u002Fapi\u002Frun-intelligence\u002Fruns\u002F\u003Cid>\u002Flog` returns `404`, do **not** assume the run has no raw log anywhere. First check whether you are querying the wrong Rudder instance (for example `dev` server\u002FAPI while the run log lives under `~\u002F.rudder\u002Finstances\u002Fe2e\u002Fdata\u002Frun-logs\u002F...`).\n\n## Workflow\n\n### 1. Identify the run\n\nIf the user gives:\n- a full run ID: use it directly\n- a short prefix like `7d28669d`: treat it as a prefix\n- a recent-run batch request like \"prod Z Studio 最近 30 个 run\": treat it as\n  batch mode and identify the org\u002Fruntime\u002Ftime window before deep-diving\n- only an agent or timeframe: first help locate likely runs before deeper analysis\n\nIf the user provides no identifying info at all, ask for at least one of:\n- run ID or prefix\n- agent name\n- approximate time window\n\n### 1.1 Batch mode for recent runs\n\nUse batch mode when the user asks for recent N runs, org-level run quality,\nefficiency, repeated failures, automation output quality, or \"有什么可以优化\".\n\nBatch mode is not the same as a Codex session benchmark. Stay on Rudder agent\nrun evidence: `heartbeat_runs`, run-intelligence metadata, run logs,\n`result_json`, `usage_json`, stderr\u002Fstdout excerpts, and transcript outlines.\n\nWorkflow:\n\n1. Resolve the active Rudder instance and org. Prefer explicit org names from\n   the prompt, then live API\u002Forg listings, then local instance files.\n2. Build the cohort with a stable ordering, usually most recent finished runs\n   for the selected org and optional agent\u002Fruntime filter.\n3. For each run, capture status, duration, runtime, cost\u002Ftokens when present,\n   result shape, stderr\u002Ferror excerpt, and whether raw log\u002Ftranscript evidence\n   exists.\n4. Classify reusable failure classes: no-op heartbeat, missing context, shallow\n   final answer, repeated tool\u002Fruntime failure, excessive cost, blocked\n   environment, stale session continuity, or missing handoff artifact.\n5. Deep-dive only the representative runs needed to prove each failure class.\n   Do not parse every full log when metadata already shows the distribution.\n6. Output optimization proposals tied to evidence, not a generic agent-quality\n   essay.\n\nIf localhost, API, or Postgres access is blocked by sandbox or runtime policy,\ndo not stop. Pivot to filesystem-side evidence:\n\n- `~\u002F.rudder\u002Finstances\u002F*\u002Fdata\u002Frun-logs`\n- local run-intelligence artifacts or log stores\n- workspace artifacts referenced by recent runs\n- database directory or config files that identify the likely instance\n- available JSON summaries, excerpts, and session ids\n\nState which sources were unavailable and label any conclusions that are based\non fallback evidence rather than live API\u002FDB reads.\n\n### 1.2 Separate root cause evidence from fix proof\n\nWhen the user is debugging a concrete failure that may need a fix, keep two\nledgers separate:\n\n- Root cause evidence: run metadata, transcript entries, stdout\u002Fstderr, events,\n  source code, config, database rows, or runtime state that explains why the run\n  behaved that way.\n- Product proof required after a fix: actor, trigger, system effect, terminal\n  surface, seed\u002Fmutation data, screenshots, API readback, or CLI output needed\n  to show the workflow now behaves correctly.\n\nIf the debug stage finds the likely fix but the terminal workflow has not been\nrerun, say `fix proof missing` instead of calling the issue resolved. For\nagent-facing bugs, prefer rerunning a disposable agent issue or heartbeat path\nafter implementation rather than only checking stored excerpts or database rows.\n\n### 1.3 Diagnose finalizer failures separately from tool failures\n\nWhen the user says a tool failed, or a UI surface shows `failed`, do not assume\nthe named tool was the root cause. Split the execution into layers:\n\n1. Tool result: did the tool call return `isError`, stderr, HTTP error, or a\n   malformed payload?\n2. Assistant output: did the model produce a final answer, structured result,\n   or continuation after the tool result?\n3. Runtime process: did the adapter process exit cleanly, timeout, receive a\n   signal, or lose the session?\n4. Rudder finalizer: did stream close, message persistence, run status update,\n   transcript parsing, or result extraction mark the run\u002Fmessage failed?\n5. Terminal surface: did Messenger, Issue Detail, run-intelligence, or another\n   UI\u002FAPI consumer show a failure state that disagrees with lower-level evidence?\n\nIf tool results are successful but the UI or run row is failed, classify the\nroot cause as `finalizer\u002Fstatus-mapping suspected` until proven otherwise. The\nnext source of truth is the server log, stream route, adapter finalization path,\nrun events, message status rows, and UI status mapping, not another inspection\nof the successful tool payload.\n\n### 2. Preferred path: run-intelligence CLI helpers\n\nUse these first when working locally in this repo.\n\n**High-level diagnosis**\n```bash\nnode cli\u002Fnode_modules\u002Ftsx\u002Fdist\u002Fcli.mjs packages\u002Frun-intelligence-core\u002Fsrc\u002Fcli\u002Fanalyze.ts \u003Crun-id-or-prefix> [auto|quick|error|perf|full]\n```\n\n**Outline model turns \u002F steps**\n```bash\nnode cli\u002Fnode_modules\u002Ftsx\u002Fdist\u002Fcli.mjs packages\u002Frun-intelligence-core\u002Fsrc\u002Fcli\u002Ftrace-outline.ts \u003Crun-id-or-prefix>\n```\n\n**Inspect a specific step**\n```bash\nnode cli\u002Fnode_modules\u002Ftsx\u002Fdist\u002Fcli.mjs packages\u002Frun-intelligence-core\u002Fsrc\u002Fcli\u002Ftrace-entry.ts \u003Crun-id-or-prefix> \u003CstepIndex|turn:N>\n```\n\nThese commands already know how to:\n- search by run prefix across orgs\n- fetch run metadata, events, and logs through the API\n- fall back to filesystem run logs if the API path is unavailable\n- parse runtime-specific stdout into transcript entries\n\n### 3. API path if you need raw data\n\nIf the local Rudder server is up, use the run-intelligence API directly.\n\nUseful endpoints:\n\n```bash\ncurl http:\u002F\u002F127.0.0.1:3100\u002Fapi\u002Forgs\ncurl \"http:\u002F\u002F127.0.0.1:3100\u002Fapi\u002Frun-intelligence\u002Forgs\u002F\u003Corg-id>\u002Fruns?limit=50&runIdPrefix=\u003Cprefix>\"\ncurl \"http:\u002F\u002F127.0.0.1:3100\u002Fapi\u002Frun-intelligence\u002Fruns\u002F\u003Crun-id>\"\ncurl \"http:\u002F\u002F127.0.0.1:3100\u002Fapi\u002Frun-intelligence\u002Fruns\u002F\u003Crun-id>\u002Fevents\"\ncurl \"http:\u002F\u002F127.0.0.1:3100\u002Fapi\u002Frun-intelligence\u002Fruns\u002F\u003Crun-id>\u002Flog\"\n```\n\nIf `RUDDER_API_URL` is set, use that base URL instead of `http:\u002F\u002F127.0.0.1:3100\u002Fapi`.\n\n### 4. Filesystem fallback\n\nIf the API path is unavailable, the run-intelligence CLI loader can still fall back to filesystem logs automatically.\n\nDefault local run-log root:\n\n```text\n~\u002F.rudder\u002Finstances\u002Fdev\u002Fdata\u002Frun-logs\n```\n\nIf the run came from a different local instance, also check sibling stores such as:\n\n```text\n~\u002F.rudder\u002Finstances\u002Fe2e\u002Fdata\u002Frun-logs\n```\n\nThis matters when:\n- run detail and events resolve correctly through one server\n- but `\u002Frun-intelligence\u002Fruns\u002F\u003Cid>\u002Flog` returns `404`\n- and the raw log actually exists under another instance root\n\nUse the same CLI commands above before inventing a custom parser.\n\n### 5. Direct DB fallback\n\nUse DB queries only when you need targeted supplementary checks.\n\nExamples:\n\n**Run metadata by prefix**\n```sql\nSELECT\n  r.id,\n  r.status,\n  r.exit_code,\n  r.signal,\n  r.error,\n  r.error_code,\n  r.started_at,\n  r.finished_at,\n  r.session_id_before,\n  r.session_id_after,\n  r.stdout_excerpt,\n  r.stderr_excerpt,\n  r.usage_json,\n  r.result_json,\n  a.name AS agent_name,\n  a.agent_runtime_type\nFROM heartbeat_runs r\nJOIN agents a ON r.agent_id = a.id\nWHERE r.id::text ILIKE '7d28669d%'\nORDER BY r.created_at DESC;\n```\n\n**Run events by prefix**\n```sql\nSELECT\n  seq,\n  event_type,\n  stream,\n  level,\n  message,\n  payload,\n  created_at\nFROM heartbeat_run_events\nWHERE run_id::text ILIKE '7d28669d%'\nORDER BY seq, id;\n```\n\n**Likely error events**\n```sql\nSELECT\n  seq,\n  event_type,\n  stream,\n  level,\n  message,\n  payload\nFROM heartbeat_run_events\nWHERE run_id::text ILIKE '7d28669d%'\n  AND (\n    stream = 'stderr'\n    OR level = 'error'\n    OR event_type ILIKE '%error%'\n    OR COALESCE(payload->>'isError', payload->>'is_error', 'false') = 'true'\n  )\nORDER BY seq, id;\n```\n\n## Interpreting the data\n\nWhen analyzing a run, focus on these in order:\n\n1. **Run summary**\n   - status\n   - duration\n   - runtime type \u002F agent name\n   - exit code \u002F signal \u002F error \u002F error code\n   - token and cost fields from `usage_json`\n\n2. **Transcript story**\n   - model turns\n   - tool calls and tool results\n   - stderr \u002F system events\n   - where the run first visibly goes wrong\n\n3. **Supporting evidence**\n   - run events such as `adapter.invoke`, `heartbeat.run.status`, `heartbeat.run.log`\n   - `stdout_excerpt` \u002F `stderr_excerpt`\n   - session IDs before\u002Fafter\n\n## What to look for\n\n### Tool call problems\n- tool call without matching tool result\n- tool result marked error\n- unexpectedly large tool payloads or truncation\n- successful tool results followed by a failed message\u002Frun status; treat this\n  as a lifecycle\u002Ffinalizer problem, not as a tool-call problem, until logs prove\n  the tool caused the final failure\n\n### Output problems\n- stderr that explains the failure more clearly than `error`\n- no parsed `result` entry even though raw log exists\n- transcript parser missing structure that is visible in raw log\n- assistant final text exists but Rudder still stored failed status\n\n### Metadata problems\n- `status` inconsistent with `exit_code` or `error_code`\n- `usage_json` missing obvious token\u002Fcost fields\n- `result_json` present but too shallow to explain failure\n- message status, run status, and transcript terminal event disagree with each\n  other\n\n### Session \u002F continuity problems\n- surprising `session_id_before` \u002F `session_id_after`\n- retries or continuation context missing\n- repeated init\u002Fstart signals without a clean result\n\n## Output Format\n\nPresent findings in this order:\n\n### 1. Run Summary\n```text\nRun: 7d28669d-...\nAgent: CEO (claude_local)\nStatus: failed\nDuration: 3m 38s\nCost: $0.7919 | 47.8k in | 8.3k out | 2.1k cached\nExit Code: 1\nError: unknown session\n```\n\n### 2. What Happened\n- Short narrative of the execution flow\n- First clear failure point\n- Whether the root cause came from transcript, raw log, or run event evidence\n\n### 3. Key Evidence\n- Tool calls\n- Error snippets\n- Relevant system \u002F adapter.invoke events\n- Session \u002F retry clues\n- Lifecycle\u002Ffinalizer evidence when tool results and final UI status disagree\n\n### 4. Raw Log\n\nOnly if the user asks. Save outside the repo, for example:\n\n```bash\nprintf \"%s\" \"$LOG_CONTENT\" > \u002Ftmp\u002Frun-\u003Crun-id>.log\n```\n\n## Notes\n\n- `heartbeat_run_events` may contain `stream = null` for non-log events.\n- `payload` may use either `isError` or `is_error` depending on source.\n- For costs\u002Ftokens, check `inputTokens`, `outputTokens`, `cachedInputTokens`, `cachedTokens`, `costUsd`, and `totalCostUsd`.\n- The best default is usually: run `analyze.ts`, then `trace-outline.ts`, then inspect raw events\u002Flog only if the diagnosis is still unclear.\n","# Debug Run Transcript\n\nAnalyze Rudder agent runs by reconstructing the execution story from the best available source.\n\n## Purpose\n\nRuns fail for several different reasons:\n- the model\u002Fruntime emitted an error\n- the transcript parser missed useful structure\n- the event stream is incomplete\n- the stored excerpts are too shallow\n- a tool call succeeded, but Rudder's message\u002Frun lifecycle marked the\n  workflow failed during stream finalization, persistence, or UI status mapping\n- the operator has only a partial run ID or limited context\n\nThis skill helps diagnose those cases without getting stuck on the wrong data source.\n\nDebugging proves what happened in a run; it does not by itself prove that a\nproduct fix works. When a transcript diagnosis leads to a code, CLI, skill,\nruntime, or UI change, hand the work back to the lifecycle verification path and\nrequire product proof for the affected actor and terminal surface.\n\n## Source Priority\n\nAlways use sources in this order:\n\n1. **Run-intelligence loader\u002FAPI**\n   - Best default.\n   - Reads run metadata, run events, and the underlying run log.\n   - Reconstructs transcript entries with runtime-specific parsers.\n2. **Filesystem run log fallback**\n   - Use when the local API is unavailable but run logs exist on disk.\n   - Good for transcript\u002Ftool-call reconstruction.\n3. **Direct database queries**\n   - Use only for targeted checks or when the first two paths are unavailable.\n   - DB rows alone are not the full transcript story.\n\n## Important Lessons \u002F Known Traps\n\n- Do **not** assume `~\u002F.rudder\u002Finstances\u002Fdev\u002Fpostgres-uri` exists. In this repo it is not a reliable universal entrypoint.\n- 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.\n- Do **not** write `WHERE id LIKE 'prefix%'` against `uuid` columns. Cast first: `id::text ILIKE 'prefix%'`.\n- Do **not** assume `pnpm exec tsx` works from the repo root here. Prefer the repo-local launcher:\n\n```bash\nnode cli\u002Fnode_modules\u002Ftsx\u002Fdist\u002Fcli.mjs ...\n```\n\n- Do **not** treat `stdout_excerpt` \u002F `stderr_excerpt` as the whole log. They are quick diagnostics only.\n- If `\u002Fapi\u002Frun-intelligence\u002Fruns\u002F\u003Cid>\u002Flog` returns `404`, do **not** assume the run has no raw log anywhere. First check whether you are querying the wrong Rudder instance (for example `dev` server\u002FAPI while the run log lives under `~\u002F.rudder\u002Finstances\u002Fe2e\u002Fdata\u002Frun-logs\u002F...`).\n\n## Workflow\n\n### 1. Identify the run\n\nIf the user gives:\n- a full run ID: use it directly\n- a short prefix like `7d28669d`: treat it as a prefix\n- a recent-run batch request like \"prod Z Studio 最近 30 个 run\": treat it as\n  batch mode and identify the org\u002Fruntime\u002Ftime window before deep-diving\n- only an agent or timeframe: first help locate likely runs before deeper analysis\n\nIf the user provides no identifying info at all, ask for at least one of:\n- run ID or prefix\n- agent name\n- approximate time window\n\n### 1.1 Batch mode for recent runs\n\nUse batch mode when the user asks for recent N runs, org-level run quality,\nefficiency, repeated failures, automation output quality, or \"有什么可以优化\".\n\nBatch mode is not the same as a Codex session benchmark. Stay on Rudder agent\nrun evidence: `heartbeat_runs`, run-intelligence metadata, run logs,\n`result_json`, `usage_json`, stderr\u002Fstdout excerpts, and transcript outlines.\n\nWorkflow:\n\n1. Resolve the active Rudder instance and org. Prefer explicit org names from\n   the prompt, then live API\u002Forg listings, then local instance files.\n2. Build the cohort with a stable ordering, usually most recent finished runs\n   for the selected org and optional agent\u002Fruntime filter.\n3. For each run, capture status, duration, runtime, cost\u002Ftokens when present,\n   result shape, stderr\u002Ferror excerpt, and whether raw log\u002Ftranscript evidence\n   exists.\n4. Classify reusable failure classes: no-op heartbeat, missing context, shallow\n   final answer, repeated tool\u002Fruntime failure, excessive cost, blocked\n   environment, stale session continuity, or missing handoff artifact.\n5. Deep-dive only the representative runs needed to prove each failure class.\n   Do not parse every full log when metadata already shows the distribution.\n6. Output optimization proposals tied to evidence, not a generic agent-quality\n   essay.\n\nIf localhost, API, or Postgres access is blocked by sandbox or runtime policy,\ndo not stop. Pivot to filesystem-side evidence:\n\n- `~\u002F.rudder\u002Finstances\u002F*\u002Fdata\u002Frun-logs`\n- local run-intelligence artifacts or log stores\n- workspace artifacts referenced by recent runs\n- database directory or config files that identify the likely instance\n- available JSON summaries, excerpts, and session ids\n\nState which sources were unavailable and label any conclusions that are based\non fallback evidence rather than live API\u002FDB reads.\n\n### 1.2 Separate root cause evidence from fix proof\n\nWhen the user is debugging a concrete failure that may need a fix, keep two\nledgers separate:\n\n- Root cause evidence: run metadata, transcript entries, stdout\u002Fstderr, events,\n  source code, config, database rows, or runtime state that explains why the run\n  behaved that way.\n- Product proof required after a fix: actor, trigger, system effect, terminal\n  surface, seed\u002Fmutation data, screenshots, API readback, or CLI output needed\n  to show the workflow now behaves correctly.\n\nIf the debug stage finds the likely fix but the terminal workflow has not been\nrerun, say `fix proof missing` instead of calling the issue resolved. For\nagent-facing bugs, prefer rerunning a disposable agent issue or heartbeat path\nafter implementation rather than only checking stored excerpts or database rows.\n\n### 1.3 Diagnose finalizer failures separately from tool failures\n\nWhen the user says a tool failed, or a UI surface shows `failed`, do not assume\nthe named tool was the root cause. Split the execution into layers:\n\n1. Tool result: did the tool call return `isError`, stderr, HTTP error, or a\n   malformed payload?\n2. Assistant output: did the model produce a final answer, structured result,\n   or continuation after the tool result?\n3. Runtime process: did the adapter process exit cleanly, timeout, receive a\n   signal, or lose the session?\n4. Rudder finalizer: did stream close, message persistence, run status update,\n   transcript parsing, or result extraction mark the run\u002Fmessage failed?\n5. Terminal surface: did Messenger, Issue Detail, run-intelligence, or another\n   UI\u002FAPI consumer show a failure state that disagrees with lower-level evidence?\n\nIf tool results are successful but the UI or run row is failed, classify the\nroot cause as `finalizer\u002Fstatus-mapping suspected` until proven otherwise. The\nnext source of truth is the server log, stream route, adapter finalization path,\nrun events, message status rows, and UI status mapping, not another inspection\nof the successful tool payload.\n\n### 2. Preferred path: run-intelligence CLI helpers\n\nUse these first when working locally in this repo.\n\n**High-level diagnosis**\n```bash\nnode cli\u002Fnode_modules\u002Ftsx\u002Fdist\u002Fcli.mjs packages\u002Frun-intelligence-core\u002Fsrc\u002Fcli\u002Fanalyze.ts \u003Crun-id-or-prefix> [auto|quick|error|perf|full]\n```\n\n**Outline model turns \u002F steps**\n```bash\nnode cli\u002Fnode_modules\u002Ftsx\u002Fdist\u002Fcli.mjs packages\u002Frun-intelligence-core\u002Fsrc\u002Fcli\u002Ftrace-outline.ts \u003Crun-id-or-prefix>\n```\n\n**Inspect a specific step**\n```bash\nnode cli\u002Fnode_modules\u002Ftsx\u002Fdist\u002Fcli.mjs packages\u002Frun-intelligence-core\u002Fsrc\u002Fcli\u002Ftrace-entry.ts \u003Crun-id-or-prefix> \u003CstepIndex|turn:N>\n```\n\nThese commands already know how to:\n- search by run prefix across orgs\n- fetch run metadata, events, and logs through the API\n- fall back to filesystem run logs if the API path is unavailable\n- parse runtime-specific stdout into transcript entries\n\n### 3. API path if you need raw data\n\nIf the local Rudder server is up, use the run-intelligence API directly.\n\nUseful endpoints:\n\n```bash\ncurl http:\u002F\u002F127.0.0.1:3100\u002Fapi\u002Forgs\ncurl \"http:\u002F\u002F127.0.0.1:3100\u002Fapi\u002Frun-intelligence\u002Forgs\u002F\u003Corg-id>\u002Fruns?limit=50&runIdPrefix=\u003Cprefix>\"\ncurl \"http:\u002F\u002F127.0.0.1:3100\u002Fapi\u002Frun-intelligence\u002Fruns\u002F\u003Crun-id>\"\ncurl \"http:\u002F\u002F127.0.0.1:3100\u002Fapi\u002Frun-intelligence\u002Fruns\u002F\u003Crun-id>\u002Fevents\"\ncurl \"http:\u002F\u002F127.0.0.1:3100\u002Fapi\u002Frun-intelligence\u002Fruns\u002F\u003Crun-id>\u002Flog\"\n```\n\nIf `RUDDER_API_URL` is set, use that base URL instead of `http:\u002F\u002F127.0.0.1:3100\u002Fapi`.\n\n### 4. Filesystem fallback\n\nIf the API path is unavailable, the run-intelligence CLI loader can still fall back to filesystem logs automatically.\n\nDefault local run-log root:\n\n```text\n~\u002F.rudder\u002Finstances\u002Fdev\u002Fdata\u002Frun-logs\n```\n\nIf the run came from a different local instance, also check sibling stores such as:\n\n```text\n~\u002F.rudder\u002Finstances\u002Fe2e\u002Fdata\u002Frun-logs\n```\n\nThis matters when:\n- run detail and events resolve correctly through one server\n- but `\u002Frun-intelligence\u002Fruns\u002F\u003Cid>\u002Flog` returns `404`\n- and the raw log actually exists under another instance root\n\nUse the same CLI commands above before inventing a custom parser.\n\n### 5. Direct DB fallback\n\nUse DB queries only when you need targeted supplementary checks.\n\nExamples:\n\n**Run metadata by prefix**\n```sql\nSELECT\n  r.id,\n  r.status,\n  r.exit_code,\n  r.signal,\n  r.error,\n  r.error_code,\n  r.started_at,\n  r.finished_at,\n  r.session_id_before,\n  r.session_id_after,\n  r.stdout_excerpt,\n  r.stderr_excerpt,\n  r.usage_json,\n  r.result_json,\n  a.name AS agent_name,\n  a.agent_runtime_type\nFROM heartbeat_runs r\nJOIN agents a ON r.agent_id = a.id\nWHERE r.id::text ILIKE '7d28669d%'\nORDER BY r.created_at DESC;\n```\n\n**Run events by prefix**\n```sql\nSELECT\n  seq,\n  event_type,\n  stream,\n  level,\n  message,\n  payload,\n  created_at\nFROM heartbeat_run_events\nWHERE run_id::text ILIKE '7d28669d%'\nORDER BY seq, id;\n```\n\n**Likely error events**\n```sql\nSELECT\n  seq,\n  event_type,\n  stream,\n  level,\n  message,\n  payload\nFROM heartbeat_run_events\nWHERE run_id::text ILIKE '7d28669d%'\n  AND (\n    stream = 'stderr'\n    OR level = 'error'\n    OR event_type ILIKE '%error%'\n    OR COALESCE(payload->>'isError', payload->>'is_error', 'false') = 'true'\n  )\nORDER BY seq, id;\n```\n\n## Interpreting the data\n\nWhen analyzing a run, focus on these in order:\n\n1. **Run summary**\n   - status\n   - duration\n   - runtime type \u002F agent name\n   - exit code \u002F signal \u002F error \u002F error code\n   - token and cost fields from `usage_json`\n\n2. **Transcript story**\n   - model turns\n   - tool calls and tool results\n   - stderr \u002F system events\n   - where the run first visibly goes wrong\n\n3. **Supporting evidence**\n   - run events such as `adapter.invoke`, `heartbeat.run.status`, `heartbeat.run.log`\n   - `stdout_excerpt` \u002F `stderr_excerpt`\n   - session IDs before\u002Fafter\n\n## What to look for\n\n### Tool call problems\n- tool call without matching tool result\n- tool result marked error\n- unexpectedly large tool payloads or truncation\n- successful tool results followed by a failed message\u002Frun status; treat this\n  as a lifecycle\u002Ffinalizer problem, not as a tool-call problem, until logs prove\n  the tool caused the final failure\n\n### Output problems\n- stderr that explains the failure more clearly than `error`\n- no parsed `result` entry even though raw log exists\n- transcript parser missing structure that is visible in raw log\n- assistant final text exists but Rudder still stored failed status\n\n### Metadata problems\n- `status` inconsistent with `exit_code` or `error_code`\n- `usage_json` missing obvious token\u002Fcost fields\n- `result_json` present but too shallow to explain failure\n- message status, run status, and transcript terminal event disagree with each\n  other\n\n### Session \u002F continuity problems\n- surprising `session_id_before` \u002F `session_id_after`\n- retries or continuation context missing\n- repeated init\u002Fstart signals without a clean result\n\n## Output Format\n\nPresent findings in this order:\n\n### 1. Run Summary\n```text\nRun: 7d28669d-...\nAgent: CEO (claude_local)\nStatus: failed\nDuration: 3m 38s\nCost: $0.7919 | 47.8k in | 8.3k out | 2.1k cached\nExit Code: 1\nError: unknown session\n```\n\n### 2. What Happened\n- Short narrative of the execution flow\n- First clear failure point\n- Whether the root cause came from transcript, raw log, or run event evidence\n\n### 3. Key Evidence\n- Tool calls\n- Error snippets\n- Relevant system \u002F adapter.invoke events\n- Session \u002F retry clues\n- Lifecycle\u002Ffinalizer evidence when tool results and final UI status disagree\n\n### 4. Raw Log\n\nOnly if the user asks. Save outside the repo, for example:\n\n```bash\nprintf \"%s\" \"$LOG_CONTENT\" > \u002Ftmp\u002Frun-\u003Crun-id>.log\n```\n\n## Notes\n\n- `heartbeat_run_events` may contain `stream = null` for non-log events.\n- `payload` may use either `isError` or `is_error` depending on source.\n- For costs\u002Ftokens, check `inputTokens`, `outputTokens`, `cachedInputTokens`, `cachedTokens`, `costUsd`, and `totalCostUsd`.\n- The best default is usually: run `analyze.ts`, then `trace-outline.ts`, then inspect raw events\u002Flog only if the diagnosis is still unclear.\n",{"name":5,"description":7},"main","26d5d68bcbc55caeac1dc6a266d973e8c3831f1c",".agents\u002Fskills\u002Fmaintainer\u002Fdebug-run-transcript-maintainer",31,"https:\u002F\u002Fgithub.com\u002FUndertone0809\u002Frudder","https:\u002F\u002Frudderhq.dev","https:\u002F\u002Fgithub.com\u002FUndertone0809","Creator of Rudder, Spark Lab. I design SDKs, infra and software for human and the NEW WORLD.","2026-11-08 00:09:15",{"source":8,"skillName":5,"commands":55,"prompt":65,"zipAvailable":66},[56,59,62],{"tool":57,"command":58},"npx","npx skills add Undertone0809\u002Frudder --skill debug-run-transcript-maintainer",{"tool":60,"command":61},"bunx","bunx skills add Undertone0809\u002Frudder --skill debug-run-transcript-maintainer",{"tool":63,"command":64},"pnpm","pnpm dlx skills add Undertone0809\u002Frudder --skill debug-run-transcript-maintainer","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002FUndertone0809\u002Frudder\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fmaintainer\u002Fdebug-run-transcript-maintainer\u002FSKILL.md",true,[68],{"path":69,"resourceType":70,"resourceTypeDesc":71,"sizeBytes":72,"sourceHtmlUrl":73},"references\u002Frunbook.md","REFERENCE","参考文档",13103,"https:\u002F\u002Fgithub.com\u002FUndertone0809\u002Frudder\u002Fblob\u002Fmain\u002F.agents\u002Fskills\u002Fmaintainer\u002Fdebug-run-transcript-maintainer\u002Freferences\u002Frunbook.md",[75,88,101,127,156,181],{"skillNo":76,"name":77,"nameZh":6,"description":78,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":79,"categories":80,"keywords":81,"publishedAt":40},"01M6K33ZG45BN249F4DZRCCSJN","Source Synthesis","Synthesize evidence into a concise conclusion.","https:\u002F\u002Fgithub.com\u002FUndertone0809\u002Frudder\u002Fblob\u002Fmain\u002Ftests\u002Fe2e\u002Ffixtures\u002Fcodex-plugin-research\u002Fskills\u002Fsynthesis\u002FSKILL.md",[],[82,83,84,85,86,87],"Synthesis","source","source synthesis","concise","synthesize","evidence",{"skillNo":89,"name":90,"nameZh":6,"description":91,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":92,"categories":93,"keywords":99,"publishedAt":40},"01M6K33XMZXRM31H2SG618C37F","Evidence Research","Gather and cite evidence before reaching a conclusion.","https:\u002F\u002Fgithub.com\u002FUndertone0809\u002Frudder\u002Fblob\u002Fmain\u002Ftests\u002Fe2e\u002Ffixtures\u002Fcodex-plugin-research\u002Fskills\u002Fevidence\u002FSKILL.md",[94],{"categoryNo":95,"categoryName":96,"taxonomyType":97,"taxonomyTypeDesc":98},"01JBSEEDCAT000000000000021","资料检索与研究","SCENARIO","使用场景",[100,87,90],"research",{"skillNo":102,"name":103,"nameZh":6,"description":104,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":105,"categories":106,"keywords":108,"publishedAt":40},"01M6K33RHAPNGPCM2FGPWTZQ8G","deep-research","Conducts enterprise-grade research with multi-source synthesis, citation tracking, and verification. Produces citation-backed reports through a structured pipeline with source credibility scoring, and grounds abstract findings in concrete examples, cases, counterexamples, or mini-scenarios when helpful. Triggers on \"deep research\", \"comprehensive analysis\", \"research report\", \"compare X vs Y\", \"analyze trends\", or \"state of the art\". Not for simple lookups, debugging, or questions answerable with 1-2 searches.","https:\u002F\u002Fgithub.com\u002FUndertone0809\u002Frudder\u002Fblob\u002Fmain\u002Fserver\u002Fresources\u002Fcommunity-skills\u002Fdeep-research\u002FSKILL.md",[107],{"categoryNo":95,"categoryName":96,"taxonomyType":97,"taxonomyTypeDesc":98},[109,110,100,111,112,113,84,114,115,116,117,118,119,120,121,122,123,124,125,126],"deep research","deep","state","debugging","triggers","for","with","multi","compare","verification","scoring","Art","reports","analyze","analysis","pipeline","Enterprise","examples",{"skillNo":128,"name":129,"nameZh":6,"description":130,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":131,"categories":132,"keywords":136,"publishedAt":40},"01M6K33JPMYXHY9E4WR0K9EK0V","visualize","Create safe inline visual explanations in Rudder Chat. Use when asked for a chart, plot, diagram, timeline, comparison, static map, simulator, scenario view, or compact visual that materially improves understanding. Prefer Mermaid for static node-and-edge structures; use Rudder's runtime-neutral HTML\u002FSVG\u002FCSS message envelope for custom geometry. Rudder visuals are declarative and scriptless: convert simulator requests to static scenarios or disclosure-based comparisons and never rely on JavaScript, network access, or external assets.","https:\u002F\u002Fgithub.com\u002FUndertone0809\u002Frudder\u002Fblob\u002Fmain\u002Fserver\u002Fresources\u002Fbundled-skills\u002Fvisualize\u002FSKILL.md",[133],{"categoryNo":134,"categoryName":135,"taxonomyType":97,"taxonomyTypeDesc":98},"01JBSEEDCAT000000000000009","前端开发",[129,137,138,139,140,141,142,143,144,145,146,147,148,149,150,151,152,153,154,155],"static","inline","chart","scenario","access","geometry","map","message","compact","back","never","node","mermaid","network","create","diagram","safe","css","markdown",{"skillNo":157,"name":158,"nameZh":6,"description":159,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":160,"categories":161,"keywords":165,"publishedAt":40},"01M6K339S5PWH9RTZZA71CPD32","skill-creator","Create new skills, modify and improve existing skills, and measure skill performance. Use when users want to create a skill from scratch, edit or optimize an existing skill, run evals to test a skill, benchmark skill performance with variance analysis, or optimize a skill's description for better triggering accuracy.","https:\u002F\u002Fgithub.com\u002FUndertone0809\u002Frudder\u002Fblob\u002Fmain\u002Fserver\u002Fresources\u002Fbundled-skills\u002Fskill-creator\u002FSKILL.md",[162],{"categoryNo":163,"categoryName":164,"taxonomyType":97,"taxonomyTypeDesc":98},"01JBSEEDCAT000000000000023","Skill与智能体开发",[166,167,168,169,170,171,172,173,114,174,175,176,177,34,178,179,123,180,25,151],"skill creator","creator","run evals","performance","variance analysis","existing skill","Existing","accuracy","From Scratch","users","optimize","evals","edit","improve","benchmark",{"skillNo":182,"name":183,"nameZh":6,"description":184,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":185,"categories":186,"keywords":187,"publishedAt":40},"01M6K333T855082YFXZ4FW0SE7","rudder-docs","Use when the user asks how Rudder works; needs current Rudder docs, exact behavior, commands, contracts, APIs, or source evidence; asks to create, hire, or configure Rudder agents; or asks to scaffold, develop, or verify Rudder plugins. For explicit creation requests, verify the current interface before acting within existing authorization. Do not use for greetings, ordinary work merely running inside Rudder, routine actions already clear from the active context and typed tools, non-Rudder plugin work, or general coding and research tasks that do not ask about Rudder.","https:\u002F\u002Fgithub.com\u002FUndertone0809\u002Frudder\u002Fblob\u002Fmain\u002Fserver\u002Fresources\u002Fbundled-skills\u002Frudder-docs\u002FSKILL.md",[],[188,189,190,83,191,192,193,194,195,196,197,198,199,200,201,202,203,204,151,205],"rudder docs","docs","context","interface","hire","creation","commands","active","do","contracts","ask","work","coding","configure","how","Tools","actions","tasks"]