Skip to content
Skills Library
AI & agents · Analysis

debug-runs

/debug-runs

Find and read the agent chat runs behind a run id, a user's email, or an object id or link (deck, design, dashboard, document, plan, recording, …) in any app, then work out what failed or why the object looks the way it does. Use when someone reports a broken chat, a failed run, or a bad result and gives you any of those instead of a thread.

Licence
MIT
Last repository change
13.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 13.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Find and read the agent chat runs behind a run id, a user's email, or an object id or link (deck, design, dashboard, document, plan, recording, …) in any app, then work out what failed or why the object looks the way it does. Use when someone reports a broken chat, a failed run, or a bad result and gives you any of those instead of a thread.

Original author description

Find and read the agent chat runs behind a run id, a user's email, or an object id or link (deck, design, dashboard, document, plan, recording, …) in any app, then work out what failed or why the object looks the way it does. Use when someone reports a broken chat, a failed run, or a bad result and gives you any of those instead of a thread.

How it works

  1. 1. Find the runs
  2. 2. Read a thread
  3. 3. Diagnose
  4. Retention
  5. Rules
Original SKILL.md headings · 93 lines, 666 words
SKILL.md preview
---
name: debug-runs
description: >-
  Find and read the agent chat runs behind a run id, a user's email, or an
  object id or link (deck, design, dashboard, document, plan, recording, …)
  in any app, then work out what failed or why the object looks the way it
  does. Use when someone reports a broken chat, a failed run, or a bad
  result and gives you any of those instead of a thread.
scope: dev
metadata:
  internal: true
---

# Debug Runs

`scripts/debug-runs.ts` reads production app databases (read-only, one
transaction per query) and turns a run id, email, or object id into the chats
and runs that touched it, with the full conversation.

It needs `<APP>_DATABASE_URL` entries in the repo-root `.env` or
`DATABASE_URL` in `templates/<app>/.env`. A worktree without its own `.env`
falls back to the main checkout's. An app whose credentials fail shows up as an `error`
entry; it was not searched, which is not the same as "nothing found".

## 1. Find the runs

```bash
pnpm exec tsx scripts/debug-runs.ts find <input> [--app NAME] [--days 30] [--limit 20]
```

| Input | Example | How it is matched |
|---|---|---|
| Run id | `run-1700000000000-example` | live `agent_runs`/traces, else the thread active at the timestamp inside the id |
| Email | `user@example.com` | threads they own, plus their MCP/A2A calls |
| Object link | `https://slides.agent-native.com/deck/EXAMPLE_deck1` | app from the host, id from the path |
| Bare object id | `EXAMPLE_design1` | every app: thread scope, owner lookup, owner's threads, audit inputs |

Prefer the link over a bare id: it searches one app and also scans that app's
audit log even when the object was deleted. `--app` does the same for a bare
id.

Each `results[]` entry is one app:

- `owners`: the table the object lives in and its owner.
- `threads[]`: `matchedBy`, title, owner, scope, and `runs[]` with status,
  error, model, and timing.
- `externalAgentSessions`: calls from Claude Code, Codex, ChatGPT, and other
  MCP/A2A clients, grouped by client with 30-minute gaps. Their conversation
  lives in that client; only the calls reached us.
- `uiSessions`: audited UI edits to the object outside any chat.
- `auditError`: the audit scan timed out; rerun with a smaller `--days`.

## 2. Read a thread

```bash
pnpm exec tsx scripts/debug-runs.ts show <runId | threadId> [--app NAME]
```

This writes `.tmp/debug-runs/<app>-<threadId>.md` and a `.json` beside it.
The `.md` has the run list, live run rows, terminal run events, failed trace
spans, versions the thread wrote, audited actions, and the transcript: user
messages, assistant text, reasoning, and every tool call with its arguments
and result. Long values are capped in the `.md`; the `.json` has them whole,
plus the raw `thread_data`, including `_debugPrompts`, the system prompt of
each run.

## 3. Diagnose

**What failed.** Start at the failed run's `error`, then the last tool call
before it. `result: (none recorded…)` means the run died inside that call.
Then check the terminal event and failed spans, if they are still retained. A
`runs[].screen` value is what the user was looking at when the run started.
For a provider `ERROR ID`, search Sentry (the `sentry-cli` skill) by the
user's email and the run's time window; run and thread ids sit in event
extras, not tags.

**Why it looks like this.** The "versions written by this thread" section
links each saved version to its `runId`/`turnId`, in apps that keep versions
(Analytics, Content, Design, Plan, Slides). Diff the version before and after
the run in that app's versions table. Elsewhere, follow the mutating tool
calls on the object in order. `uiSessions` and `externalAgentSessions` show
edits that came from outside this chat.

## Retention

| Data | Kept |
|---|---|
| `chat_threads.thread_data` (the full conversation) | until the user deletes the chat |
| `agent_runs`, `agent_run_events` | 24h after success, 7 days after an error |
| `agent_trace_spans`, `agent_trace_summaries` | 30 days |
| `agent_audit_log` | 365 days |

A deleted chat is gone; its audit rows remain. Threads created before May 2026
have no run ids, so `runs[]` is empty and only the transcript is available.

## Rules

- This is customer data. Keep it in `.tmp/`. Never paste transcripts, emails,
  or object contents into GitHub, Slack, Jira, or commits; summarize the cause
  and cite ids.
- For ad-hoc SQL beyond the script, stay read-only and never `LIKE` across
  `chat_threads.thread_data` without an `owner_email` or time filter. Design's
  table alone is over 1 GB, and an unfiltered scan times out against
  production.

Versions

The database has no other skills named debug-runs.

Database snapshot: 13.11.2026 · package version 8368fd3c2500 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100t3-side-chat
    Read the user's T3 Code chats (projects, threads, transcripts) so a terminal agent can work as a side chat alongside a T3 Code agent. Use when the user mentions T3 / T3 Code, a T3 thread or project, a t3-thread:// link, or refers to "the other chat", "the agent in T3", or a…
  • 100error-shape-for-agents
    Return errors an agent can act on: what failed, why, and the next call that would work. Use when a tool can fail because of bad arguments, missing files or an empty result
  • 100debug-production
    Debug a running Last Light instance (usually production) via the `lastlight` CLI instead of SSH. Use when investigating a failed/stuck workflow, a bad agent run, a phase error, or "why didn't the bot do X" — anything that previously meant SSHing in to read SQLite or session logs.
  • 100codex-thread-reader
    Locate and read a Codex thread by a codex thread link, thread id, or rollout path across all local CODEX_HOME directories (~/.codex, ~/.codex-gpt, ...). Use when the user pastes a codex:// link, asks to understand the 前因后果 of a Codex session, wants a timeline of what a…
  • 100debug-comfy-workflow
    Diagnose a VibeComfy or ComfyUI workflow that fails validation, conversion, node/model resolution, runtime execution, or output production. Use when the user asks why a workflow does not run, has missing nodes/models, validation errors, bad wiring, failed RunPod/local runs, or…
  • 100running-chat-assistant
    Runs and tests a Robomotion Chat Assistant flow (one that starts at Robomotion.ChatAssistant.ChatIn) the way its users meet it: as an Agent, in the real Chat Assistant page. `robomotion agent` pushes the flow, makes the agent and its robot, starts it on this machine and chats…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.