| name | strace |
| description | Optimize a multi-agent system's prompts or other components using trajectory data, improve performance while reducing analysis cost — even at large scale. Use when the user wants to improve agent performance, revise prompts, or diagnose failures, and has execution traces available for analysis. Works at any scale: from a handful of traces to large collections. Do NOT use for building new agents from scratch, or when no traces exist.
|
strace — Multi-Agent System Trace Analysis & Repair Pipeline
strace is a skill with a four-stage pipeline for diagnosing and improving multi-agent systems.
Each stage is run as an independent subagent using instructions from agents/.
Stages pass context forward via files written to output/.
Step 0 — Triage (always run this first)
Before spawning any subagents, assess the situation and decide which stages to run.
Check these signals:
| Signal | Implication |
|---|
output/dependency_prior_analysis.md exists | Skip Stage 1 |
output/high_priority_components.json exists | Skip Stage 2 |
| Only 1 trace provided, or user points to a specific trace | Skip Stage 2 — go directly to Stage 3 |
| User already described which component is failing | Skip Stage 1 and Stage 2; treat user's description as system structure |
| User says "just fix the prompts" with attribution results available | Skip Stages 1–3, run Stage 4 only |
| User asks about manifestation node / "where does it fail?" | Note: this is answered as part of Stage 3 — no separate step needed |
State your plan explicitly before proceeding. Example:
"You have 1 trace and no prior output. I'll run Stage 1 to map the system, then skip Stage 2 and
go directly to Stage 3 to attribute the root cause. Stage 4 only if you want prompt fixes."
Then execute that plan. Do not enumerate possibilities — just commit to a path.
Do NOT read agent files before completing triage. Only load agents/<stage>.md immediately
before executing that stage — skip loading it entirely if the stage is not needed.
Pipeline Overview
Stage 1: Environment-Modeling → output/dependency_prior_analysis.md
Stage 2: Trace-Selection → output/high_priority_components.json
output/trace_summaries.json
Stage 3: Self-Debugging & Root Cause Attribution → output/attributions/<trace>.json (one per trace)
Stage 4: Harness-Engineering → output/prompts_revised/<agent>_revised.md
Stages share context via files in output/. Each stage can be skipped if its output already exists
or the situation makes it unnecessary (see Step 0).
Stage 1 — Environment-Modeling
instructions: agents/agent-env-modeling.md
Reads source code, prompts, and docs to catalog every component (decision-makers, executors, passive
state), infer data and control dependencies, and write a compact dependency prior list.
Skip if: output/dependency_prior_analysis.md already exists and reflects current codebase.
Output: output/dependency_prior_analysis.md
Stage 2 — Trace-Selection
instructions: agents/trace-selection.md
Statistically analyzes all traces to find the worst-performing components (failure rate × downstream
impact), then selects ≤5 representative traces per component covering distinct failure patterns.
Skip if: only small number of traces provided, user already knows which component to investigate, or
output/high_priority_components.json already exists.
Output: output/trace_summaries.json, output/high_priority_components.json, output/trace_analysis_report.md
Stage 3 — Self-Debugging & Root Cause Attribution
instructions: agents/trace-self-debug.md
For each trace, backtracks from the manifestation node to find the upstream component that actually
caused the failure. Spawn one subagent per trace; they can run in parallel.
Skip if: attribution results already exist in output/attributions/.
Output: output/attributions/<trace_filename>.json per trace
After all subagents complete, summarize which components appear most as root causes — this is the
input to Stage 4.
Stage 4 — Harness-Engineering
instructions: agents/harness-engineering.md
Synthesizes attribution results into targeted prompt edits. Produces gradient blocks per trace,
then revised prompt files. Validates that decision-maker / executor boundaries are not violated.
Skip if: user only wants diagnosis, not prompt fixes.
Output: output/prompts_revised/<name>_revised.md, output/prompt_mapping.json
Trace Scripts
Three utility scripts in scripts/ for reading and searching trace files. Use these instead of
loading full trace files — they handle truncation, structure inspection, and targeted search.
When spawning subagents for Stages 2–4, include the relevant script usage in the subagent prompt
so it knows how to read traces efficiently.
scripts/get_json_structure.py — Inspect trace structure
Show the schema of a JSON file with type placeholders. Use this first on an unfamiliar trace
to understand its format before reading specific positions.
python scripts/get_json_structure.py <file_path>
scripts/read_trace_positions.py — Read specific positions
Read specific 1-based positions from a trace file. Supports dict-keyed traces
(sub_agent_calling_N, step_N, etc.) and list-based traces. Long strings are
automatically truncated.
python scripts/read_trace_positions.py <file_path> <pos1> <pos2> ...
python scripts/read_trace_positions.py trace.json 1 3 5 --max-string-length 3000
scripts/search_context_in_file.py — Search with context
Search for text in a trace file and return surrounding context. Optionally filter
to specific sub_agent_calling_N blocks.
python scripts/search_context_in_file.py <file_path> <target_text>
python scripts/search_context_in_file.py trace.json "error" --window-before 600 --window-after 600
python scripts/search_context_in_file.py trace.json "failed" --filter-positions 2 5 8
Notes
- All output files land in
output/ — create it if it doesn't exist
- Each subagent is stateless; pass context explicitly (file paths, relevant file contents) in the prompt
- For Stage 3, parallel subagents are preferred — spawn all trace attribution agents in the same turn
- After Stage 4, ask the user whether they want to apply the revised prompts to their codebase
(copy
output/prompts_revised/ → original prompt locations)
Agents
agents/agent-env-modeling.md — Stage 1agents/trace-selection.md — Stage 2agents/trace-self-debug.md — Stage 3agents/harness-engineering.md — Stage 4
