debug-run-transcript-maintainer

Name: debug-run-transcript-maintainer
Author: Undertone0809

247stars30forks

How to install debug-run-transcript-maintainer?

undertone0809/rudder/debug-run-transcript-maintainer

$npx -y skills add Undertone0809/rudder --skill debug-run-transcript-maintainer

Installs into the current project.

Summary

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/stderr, run quality, or recent org run behavior.

Files · 1

View on GitHub

SKILL.md

1	# Debug Run Transcript
2
3	Analyze Rudder agent runs by reconstructing the execution story from the best available source.
4
5	## Purpose
6
7	Runs fail for several different reasons:
8	- the model/runtime emitted an error
9	- the transcript parser missed useful structure
10	- the event stream is incomplete
11	- the stored excerpts are too shallow
12	- a tool call succeeded, but Rudder's message/run lifecycle marked the
13	workflow failed during stream finalization, persistence, or UI status mapping
14	- the operator has only a partial run ID or limited context
15
16	This skill helps diagnose those cases without getting stuck on the wrong data source.
17
18	Debugging proves what happened in a run; it does not by itself prove that a
19	product fix works. When a transcript diagnosis leads to a code, CLI, skill,
20	runtime, or UI change, hand the work back to the lifecycle verification path and
21	require product proof for the affected actor and terminal surface.
22
23	## Source Priority
24
25	Always use sources in this order:
26
27	1. Run-intelligence loader/API
28	- Best default.
29	- Reads run metadata, run events, and the underlying run log.
30	- Reconstructs transcript entries with runtime-specific parsers.
31	2. Filesystem run log fallback
32	- Use when the local API is unavailable but run logs exist on disk.
33	- Good for transcript/tool-call reconstruction.
34	3. Direct database queries
35	- Use only for targeted checks or when the first two paths are unavailable.
36	- DB rows alone are not the full transcript story.
37
38	## Important Lessons / Known Traps
39
40	- Do not assume `~/.rudder/instances/dev/postgres-uri` exists. In this repo it is not a reliable universal entrypoint.
41	- 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.
42	- Do not write `WHERE id LIKE 'prefix%'` against `uuid` columns. Cast first: `id::text ILIKE 'prefix%'`.
43	- Do not assume `pnpm exec tsx` works from the repo root here. Prefer the repo-local launcher:
44
45	```bash
46	node cli/node_modules/tsx/dist/cli.mjs ...
47	```
48
49	- Do not treat `stdout_excerpt` / `stderr_excerpt` as the whole log. They are quick diagnostics only.
50	- If `/api/run-intelligence/runs/<id>/log` 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/API while the run log lives under `~/.rudder/instances/e2e/data/run-logs/...`).
51
52	## Workflow
53
54	### 1. Identify the run
55
56	If the user gives:
57	- a full run ID: use it directly
58	- a short prefix like `7d28669d`: treat it as a prefix
59	- a recent-run batch request like "prod Z Studio 最近 30 个 run": treat it as
60	batch mode and identify the org/runtime/time window before deep-diving
61	- only an agent or timeframe: first help locate likely runs before deeper analysis
62
63	If the user provides no identifying info at all, ask for at least one of:
64	- run ID or prefix
65	- agent name
66	- approximate time window
67
68	### 1.1 Batch mode for recent runs
69
70	Use batch mode when the user asks for recent N runs, org-level run quality,
71	efficiency, repeated failures, automation output quality, or "有什么可以优化".
72
73	Batch mode is not the same as a Codex session benchmark. Stay on Rudder agent
74	run evidence: `heartbeat_runs`, run-intelligence metadata, run logs,
75	`result_json`, `usage_json`, stderr/stdout excerpts, and transcript outlines.
76
77	Workflow:
78
79	1. Resolve the active Rudder instance and org. Prefer explicit org names from
80	the prompt, then live API/org listings, then local instance files.
81	2. Build the cohort with a stable ordering, usually most recent finished runs
82	for the selected org and optional agent/runtime filter.
83	3. For each run, capture status, duration, runtime, cost/tokens when present,
84	result shape, stderr/error excerpt, and whether raw log/transcript evidence
85	exists.
86	4. Classify reusable failure classes: no-op heartbeat, missing context, shallow
87	final answer, repeated tool/runtime failure, excessive cost, blocked
88	environment, stale session continuity, or missing handoff artifact.
89	5. Deep-dive only the representative runs needed to prove each failure class.
90	Do not parse every full log when metadata already shows the distribution.
91	6. Output optimization proposals tied to evidence, not a generic agent-quality
92	essay.
93
94	If localhost, API, or Postgres access is blocked by sandbox or runtime policy,
95	do not stop. Pivot to filesystem-side evidence:
96
97	- `~/.rudder/instances/*/data/run-logs`
98	- local run-intelligence artifacts or log stores
99	- workspace artifacts referenced by recent runs
100	- database directory or config files that identify the likely instance
101	- available JSON summaries, excerpts, and session ids
102
103	State wh

People who liked this also viewed

6 picks

Type

debug-run-transcript-maintainer

247stars30forks

View on GitHub

How to install debug-run-transcript-maintainer?

undertone0809/rudder/debug-run-transcript-maintainer

$npx -y skills add Undertone0809/rudder --skill debug-run-transcript-maintainer

Installs into the current project.

Summary

Files · 1

View on GitHub

SKILL.md

1	# Debug Run Transcript
2
3	Analyze Rudder agent runs by reconstructing the execution story from the best available source.
4
5	## Purpose
6
7	Runs fail for several different reasons:
8	- the model/runtime emitted an error
9	- the transcript parser missed useful structure
10	- the event stream is incomplete
11	- the stored excerpts are too shallow
12	- a tool call succeeded, but Rudder's message/run lifecycle marked the
13	workflow failed during stream finalization, persistence, or UI status mapping
14	- the operator has only a partial run ID or limited context
15
16	This skill helps diagnose those cases without getting stuck on the wrong data source.
17
18	Debugging proves what happened in a run; it does not by itself prove that a
19	product fix works. When a transcript diagnosis leads to a code, CLI, skill,
20	runtime, or UI change, hand the work back to the lifecycle verification path and
21	require product proof for the affected actor and terminal surface.
22
23	## Source Priority
24
25	Always use sources in this order:
26
27	1. Run-intelligence loader/API
28	- Best default.
29	- Reads run metadata, run events, and the underlying run log.
30	- Reconstructs transcript entries with runtime-specific parsers.
31	2. Filesystem run log fallback
32	- Use when the local API is unavailable but run logs exist on disk.
33	- Good for transcript/tool-call reconstruction.
34	3. Direct database queries
35	- Use only for targeted checks or when the first two paths are unavailable.
36	- DB rows alone are not the full transcript story.
37
38	## Important Lessons / Known Traps
39
40	- Do not assume `~/.rudder/instances/dev/postgres-uri` exists. In this repo it is not a reliable universal entrypoint.
41	- 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.
42	- Do not write `WHERE id LIKE 'prefix%'` against `uuid` columns. Cast first: `id::text ILIKE 'prefix%'`.
43	- Do not assume `pnpm exec tsx` works from the repo root here. Prefer the repo-local launcher:
44
45	```bash
46	node cli/node_modules/tsx/dist/cli.mjs ...
47	```
48
49	- Do not treat `stdout_excerpt` / `stderr_excerpt` as the whole log. They are quick diagnostics only.
50	- If `/api/run-intelligence/runs/<id>/log` 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/API while the run log lives under `~/.rudder/instances/e2e/data/run-logs/...`).
51
52	## Workflow
53
54	### 1. Identify the run
55
56	If the user gives:
57	- a full run ID: use it directly
58	- a short prefix like `7d28669d`: treat it as a prefix
59	- a recent-run batch request like "prod Z Studio 最近 30 个 run": treat it as
60	batch mode and identify the org/runtime/time window before deep-diving
61	- only an agent or timeframe: first help locate likely runs before deeper analysis
62
63	If the user provides no identifying info at all, ask for at least one of:
64	- run ID or prefix
65	- agent name
66	- approximate time window
67
68	### 1.1 Batch mode for recent runs
69
70	Use batch mode when the user asks for recent N runs, org-level run quality,
71	efficiency, repeated failures, automation output quality, or "有什么可以优化".
72
73	Batch mode is not the same as a Codex session benchmark. Stay on Rudder agent
74	run evidence: `heartbeat_runs`, run-intelligence metadata, run logs,
75	`result_json`, `usage_json`, stderr/stdout excerpts, and transcript outlines.
76
77	Workflow:
78
79	1. Resolve the active Rudder instance and org. Prefer explicit org names from
80	the prompt, then live API/org listings, then local instance files.
81	2. Build the cohort with a stable ordering, usually most recent finished runs
82	for the selected org and optional agent/runtime filter.
83	3. For each run, capture status, duration, runtime, cost/tokens when present,
84	result shape, stderr/error excerpt, and whether raw log/transcript evidence
85	exists.
86	4. Classify reusable failure classes: no-op heartbeat, missing context, shallow
87	final answer, repeated tool/runtime failure, excessive cost, blocked
88	environment, stale session continuity, or missing handoff artifact.
89	5. Deep-dive only the representative runs needed to prove each failure class.
90	Do not parse every full log when metadata already shows the distribution.
91	6. Output optimization proposals tied to evidence, not a generic agent-quality
92	essay.
93
94	If localhost, API, or Postgres access is blocked by sandbox or runtime policy,
95	do not stop. Pivot to filesystem-side evidence:
96
97	- `~/.rudder/instances/*/data/run-logs`
98	- local run-intelligence artifacts or log stores
99	- workspace artifacts referenced by recent runs
100	- database directory or config files that identify the likely instance
101	- available JSON summaries, excerpts, and session ids
102
103	State wh

People who liked this also viewed

6 picks

Type