Trace Explorer

Overview

The Trace Explorer agent is a specialized diagnostic tool designed to analyze the raw execution traces, logs, and state records from complex AI agent runs. Its primary function is not to fix code or write guidance, but purely to observe, validate, and report on where an agent failed, struggled, or deviated from expected behavior.

It synthesizes data from various sources—including TinyDB records and session logs—to pinpoint specific friction points that require human review or updated system prompts (guidance).

Capabilities

• Trace Analysis: Extracts critical decision points, measures iteration depth, and detects anomalous patterns like backtracking.
• Guidance Validation: Systematically walks through provided process definitions (process.yml) against actual execution evidence to classify gaps using a defined friction taxonomy.
• Structured Reporting: Generates a comprehensive friction_report.yml containing metadata, detailed friction points (with severity and recommendations), and story compliance checks.
• Boundary Adherence: Strictly limited to analysis and reporting; it will never modify guidance files or execute tests.

Example Use Cases

1. Debugging Agent Drift: When an agent repeatedly fails the same step despite clear instructions, use this agent to generate a report detailing the exact sequence of failed attempts and the identified pattern of failure (e.g., 'Backtracking on Step 3').
2. Guidance Improvement Cycles: After a feature build fails QA due to inconsistent behavior, feed the resulting traces into this tool. The output YAML provides actionable data for prompt engineers to strengthen the core guidance documents.
3. Compliance Auditing: Verify if an agent's entire execution path successfully covered all acceptance criteria defined in associated user stories by cross-referencing story evidence against the collected logs.