{
  "markdown": "# Agent Trace Triage\n\n**Claude Code plugin** that debugs failed AI agent runs from a trace file (JSON/JSONL).\n\nWhen your agent loops, picks the wrong tool, or burns tokens for no reason, this skill:\n\n1. **Parses** your trace (LangChain, OpenAI tool_calls, custom JSONL, partial OTEL)\n2. **Detects loops** deterministically (repeat, ping-pong, retry-without-progress)\n3. **Classifies** the failure into a fixable bucket\n4. **Writes** a markdown triage report\n5. **Scaffolds** a regression test so the bug does not come back\n\nNo npm dependencies. Node.js 18+ only.\n\n---\n\n## Quick start\n\n### Install as a project plugin\n\nClone into your repo or add as submodule, then in Claude Code:\n\nOr copy the skill only:\n\n```bash\ncp -r skills/agent-trace-triage ~/.claude/skills/agent-trace-triage\n```\n\n### Export a trace\n\nUse the simplest format (one JSON object per line):\n\n```jsonl\n{\"type\":\"tool_call\",\"tool\":\"my_tool\",\"arguments\":{\"id\":1},\"status\":\"ok\"}\n```\n\nSee [skills/agent-trace-triage/references/trace-formats.md](skills/agent-trace-triage/references/trace-formats.md).\n\n### Run in Claude Code\n\n```text\n/agent-trace-triage traces/my-failed-run.jsonl\n```\n\nClaude will run the bundled scripts and fix your agent code.\n\n### Run scripts locally (no Claude)\n\n```bash\nnpm test\nnpm run loops:example\nnpm run triage:example\n```\n\nOr directly:\n\n```bash\nnode skills/agent-trace-triage/scripts/detect-loops.mjs examples/sample-failed-trace.jsonl --json\nnode skills/agent-trace-triage/scripts/triage.mjs examples/sample-failed-trace.jsonl --out triage-report.md\n```\n\n---\n\n## What gets detected\n\n| Pattern | Meaning |\n|---------|---------|\n| `direct_repeat` | Same tool + same args 3+ times in a row |\n| `ping_pong` | Two tools alternating with no progress |\n| `retry_without_progress` | Same tool, many arg variants, no convergence |\n\n| Failure bucket | Typical fix |\n|----------------|-------------|\n| `recovery_policy` | Max iterations, loop guards, stop on duplicate results |\n| `tool_execution` | Auth, timeouts, rate limits, structured errors |\n| `tool_selection` | Fewer tools, clearer descriptions |\n| `tool_arguments` | JSON Schema, strict mode, examples |\n| `state_orchestration` | Agent state, graph edges, message history |\n\n---\n\n## Repository layout\n\n```text\n.claude-plugin/plugin.json          # Plugin manifest\nskills/agent-trace-triage/\n  SKILL.md                          # /agent-trace-triage command\n  scripts/                          # parse, detect-loops, triage (Node)\n  references/                       # Taxonomy, formats, schema audit\n  templates/                        # Regression test stubs\ntests/                              # Automated tests + fixtures\nexamples/sample-failed-trace.jsonl\n```\n\n---\n\n## Publish to Claude plugin directory\n\n1. Push this repo to **public** GitHub.\n2. Update `homepage` in `.claude-plugin/plugin.json`.\n3. Run `claude plugin validate` from repo root (requires Claude Code CLI).\n4. Submit: [claude.ai/settings/plugins/submit](https://claude.ai/settings/plugins/submit)\n\n---\n\n## CI example\n\n```yaml\n- name: Agent trace regression\n  run: |\n    node skills/agent-trace-triage/scripts/detect-loops.mjs traces/latest.jsonl --json\n```\n\nExit code `1` = loop still present (fail build).\n\n---\n\n## Limitations (honest)\n\n- Requires a trace with **tool name + arguments**. Chat-only logs are not enough.\n- Classification heuristics are conservative; Claude applies repo-specific fixes in Step 3.\n- Does not replace Langfuse/Datadog — it **uses** their exports when you provide them.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n",
  "bytes": 3560,
  "sha": "ede18426a36d1e5ac8aee1ff81d0e72f3a88233326720374449a526a1fdb8379",
  "repo_slug": "wasayabid/agent-trace-triage",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_wasayabid_agent_trace_triage_agent_trace_868f529f/readme"
}