Agent Run Post-Mortem: Trace Root Cause and Prompt or Tool Fixes

Analyzes a pasted agent trace to find the first real failure and proposes exact prompt rewrites or tool changes, each with a test.

You get: Working code with an explanation

More like this

The prompt

agent-run-post-mortem-trace-root-cause-and-prompt-or-tool-fixes.md
Act as a senior engineer who runs post-mortems on LLM agent runs. Here is the trace or log: {paste your agent trace or log here}

If the original goal, system prompt or tool definitions are not in the trace, ask me one or two short questions first. List what you assumed separately.

Rules:
- Find the first point where the run went wrong, not the loudest error. Cite the step number or a quoted line as evidence.
- Classify the failure as bad tool call, lost context, loop, ambiguous instruction or tool design gap, and state your confidence.
- Separate root cause from symptoms and show the chain between them.
- Make every fix specific. Give exact replacement wording for a prompt line, or a concrete tool change such as a parameter, schema constraint or error message, and say how to test it.

Output:
1. Verdict in two sentences.
2. Timeline table with step, action, outcome and status (ok, suspect, failure).
3. Root cause with evidence.
4. Fixes table with fix, exact change, failure it prevents, and test.
5. Missing information and risks of the fixes.
6. Next actions in priority order.

The analysis is good if each claim points to a trace step and each fix could be applied and tested today.

Example output

AI-written example
# Post-mortem: invoice-email agent, run 7f3a

## 1. Verdict
The run failed at step 3, when the agent picked the first of three fuzzy "Acme" matches without checking which customer the user meant. That wrong choice led to an irreversible email to the wrong company (step 5) and a false success report (step 6).

## 2. Timeline
| Step | Action | Outcome | Status |
|---|---|---|---|
| 1 | User: "Send Acme Corp their March invoice." | Goal is clear, but "Acme Corp" is not a customer ID | ok |
| 2 | `search_invoices(customer="Acme", month="2024-03")` | 3 results: Acme Corp, Acme Corporation Ltd, Acme Labs | suspect |
| 3 | Agent: "Using the first match." | Picked INV-2041, which belongs to Acme Labs | **failure** |
| 4 | `get_invoice("INV-2041")` | Returns `customer_name: "Acme Labs"`, which the agent ignored | suspect |
| 5 | `send_email(to="billing@acmelabs.example", ...)` | 200 OK, invoice delivered to the wrong company | failure |
| 6 | Agent: "Sent Acme Corp's March invoice." | Claim contradicts step
Generated from this prompt by AI. Your results will vary.

Tips and common edits

Use after an agent run fails, stalls or loops. Paste the full trace, and add the system prompt and tool definitions if you have them.

Questions about this prompt

Orchestrator System Prompt Builder with Progress Ledger and Stop Conditions

Writes a ready-to-deploy orchestrator system prompt that delegates to your workers, tracks progress in a ledger, merges results and stops on defined conditions.

Parallel Git Worktree Task Split with Interface Contracts and Merge Order

Turns a pasted feature spec into independent coding-agent tasks with file ownership, interface contracts, a merge order and a done command for each task.

Characterization Tests Before a Refactor

Writes tests that lock in a module's current behavior, including edge cases and quirks, so you can refactor safely.

Codebase Tour for a Specific Task

Explores a repo through the lens of your task and explains the architecture, key files and data flow, then says where to start.

Failing Test First Bug Fix

Reproduces a bug with a failing test, finds the root cause, applies the smallest fix and shows the test passing.

Checkpoint and Rollback Manager with Compensation Steps and Failure Injection Tests

Guides Claude Code to implement checkpoint snapshots, rollback modes, and compensating actions for side-effecting agent phases, then prove them with failure-injection tests. Helps you decide the rollback strategy per phase.

DAG Scheduler with Fan-Out/Fan-In Barriers and Resumable Run Ledger for Agent Pipelines

Guides Claude Code to build or refactor a dependency-aware DAG scheduler for agent phases, with cycle validation, bounded parallelism, join policies, retries, and an append-only run ledger so interrupted runs resume without redoing finished nodes.

Subagent Fan-Out Plan for a Large Codebase Migration

Plans a big migration so an orchestrating agent can split it into independent chunks for parallel subagents, each with a clear brief, a verification command and merge rules.

Typed Phase Handoff Contracts and Validator for Multi-Agent Pipelines

Has Claude Code define schema-based handoff contracts between agent phases, generate a validator, and add contract tests. Supports the decision of which phase boundaries need strict contracts versus lightweight checks.

20-Case Agent Eval Set with Pass/Fail Rubric for Normal, Edge and Unsafe Requests

Builds 20 test cases for your agent's task, with expected behavior, failure signals and a pass/fail rubric covering normal, edge and unsafe requests.

Agent Tool Names, Descriptions and JSON Schemas from API Docs

Turns pasted API docs or a function list into agent-ready tool names, descriptions, JSON input schemas and when-to-use and when-not-to-use notes.

Agent Workflow Decomposition with Autonomy Levels and Stop Rules

Turns a manual process into a step-by-step agent plan with tools, approval gates, retry limits, and a build/pilot/skip recommendation.