1---
2name: reasoning-trace-optimizer
3description: "Debug and optimize AI agents by analyzing reasoning traces. Activates on 'debug agent', 'optimize prompt', 'analyze reasoning', 'why did the agent fail', 'improve agent performance', or when diagnosing agent failures and context degradation."
4---
5 
6# Reasoning Trace Optimizer
7 
8Debug and optimize AI agents by analyzing their reasoning traces. This skill uses MiniMax M2.1's interleaved thinking to provide deep insight into agent decision-making and generate concrete improvements.
9 
10## When to Activate
11 
12- User asks to "debug agent", "analyze reasoning", or "optimize prompt"
13- Agent task fails and user wants to understand why
14- User mentions "context degradation", "tool confusion", or "instruction drift"
15- Request to improve agent performance or reduce errors
16- User wants to generate shareable learnings from debugging sessions
17- After repeated failures on similar tasks
18 
19## Core Concepts
20 
21### Interleaved Thinking
22 
23Unlike standard reasoning models that think once at the start, interleaved thinking allows reasoning BETWEEN each tool interaction. This is critical because:
24 
251. **Long-horizon tasks** require maintaining focus across many turns
262. **External perturbations** (tool outputs, environment changes) need real-time adaptation
273. **Debugging** requires seeing HOW decisions were made, not just WHAT was output
28 
29### The Optimization Loop
30 
31```
32Execute Agent → Capture Traces → Analyze Patterns → Optimize Prompt → Re-run
33                                                          ↑____________|
34```
35 
36Each iteration improves the prompt based on detected patterns until convergence.
37 
38### Pattern Detection
39 
40Common failure patterns the analyzer detects:
41 
42| Pattern | Description |
43|---------|-------------|
44| `context_degradation` | Model loses track of information over long contexts |
45| `tool_confusion` | Model misunderstands tool capabilities or outputs |
46| `instruction_drift` | Model gradually deviates from original instructions |
47| `goal_abandonment` | Model stops pursuing the original goal |
48| `circular_reasoning` | Model repeats similar actions without progress |
49| `premature_conclusion` | Model concludes before completing the task |
50 
51## Usage Modes
52 
53### Mode 1: M2.1 Agent Debugging
54 
55Run a task through M2.1 and analyze its reasoning:
56 
57```python
58from reasoning_trace_optimizer import TraceCapture, TraceAnalyzer
59 
60capture = TraceCapture()
61trace = capture.run(
62    task="Search for Python tutorials and summarize them",
63    system_prompt="You are a research assistant.",
64    tools=[search_tool],
65    tool_executor=execute_search
66)
67 
68analyzer = TraceAnalyzer()
69analysis = analyzer.analyze(trace)
70 
71print(f"Score: {analysis.overall_score}/100")
72for pattern in analysis.patterns:
73    print(f"Found: {pattern.type.value} - {pattern.suggestion}")
74```
75 
76### Mode 2: Full Optimization Loop
77 
78Automatically iterate until the prompt is optimized:
79 
80```python
81from reasoning_trace_optimizer import OptimizationLoop, LoopConfig
82 
83config = LoopConfig(
84    max_iterations=5,
85    min_score_threshold=80.0,
86)
87 
88loop = OptimizationLoop(config=config)
89result = loop.run(
90    task="Analyze this codebase and suggest improvements",
91    initial_prompt="You are a code reviewer.",
92    tools=[read_file_tool, search_tool],
93    tool_executor=execute_tool
94)
95 
96print(f"Improved: {result.initial_score} → {result.final_score}")
97print(f"Final prompt:\n{result.final_prompt}")
98```
99 
100### Mode 3: Universal Session Analysis
101 
102Analyze any agent's previous thinking (works with Claude, GPT, etc.):
103 
104When this skill is activated in Claude Code, it can analyze the current session's thinking blocks to identify issues and suggest improvements.
105 
106```
107/reasoning-trace-optimizer analyze-session
108```
109 
110### Mode 4: Generate Shareable Skills
111 
112Convert optimization learnings into reusable Agent Skills:
113 
114```python
115from reasoning_trace_optimizer import SkillGenerator
116 
117generator = SkillGenerator()
118skill_path = generator.generate(
119    result=loop_result,
120    skill_name="web-search-best-practices",
121    output_dir="./skills"
122)
123```
124 
125## CLI Commands
126 
127```bash
128# Capture reasoning trace
129rto capture "Search for Python tutorials" -s "You are a helpful assistant."
130 
131# Analyze a task
132rto analyze "Debug this code" -o analysis.txt
133 
134# Run optimization loop
135rto optimize "Research AI papers" --max-iterations 5 --generate-skill
136 
137# Generate skill from artifacts
138rto generate-skill my-skill-name --artifacts-dir ./optimization_artifacts
139```
140 
141## Integration with Claude Code
142 
143### Auto-trigger on Failure
144 
145Add to your hooks to automatically analyze failures:
146 
147```json
148{
149  "hooks": {
150    "post_tool_error": {
151      "command": "rto analyze-session --last-error"
152    }
153  }
154}
155```
156 
157### On-demand Analysis
158 
159Use the slash command to analyze current session:
160 
161```
162/reasoning-trace-optimizer
163```
164 
165This will:
1661. Extract thinking blocks from the current session
1672. Identify patterns and issues
1683. Suggest prompt improvements
1694. Optionally update the system prompt
170 
171## Guidelines
172 
1731. **Preserve full context**: M2.1 requires full response history including thinking blocks for optimal performance
1742. **Use appropriate tools**: Define tools clearly with unambiguous descriptions
1753. **Set realistic convergence thresholds**: 5-10% improvement per iteration is typical
1764. **Review generated skills**: Auto-generated skills should be reviewed before sharing
1775. **Monitor token usage**: Each optimization iteration uses significant tokens
178 
179## Examples
180 
181### Before Optimization
182 
183```
184System: You are a helpful assistant.
185 
186Issue: Agent called wrong tools, lost track of goal after 3 turns
187Score: 45/100
188Patterns: tool_confusion, goal_abandonment
189```
190 
191### After Optimization
192 
193```
194System: You are a research assistant focused on finding accurate information.
195 
196IMPORTANT GUIDELINES:
197- Always verify search results before summarizing
198- If a tool returns an error, try an alternative approach
199- Keep track of your original goal throughout the task
200- Validate findings against multiple sources when possible
201 
202Issue: None
203Score: 85/100
204Patterns: None detected
205```
206 
207## References
208 
209- MiniMax M2.1 Documentation: https://platform.minimax.io/docs
210- Interleaved Thinking Guide: See `docs/interleavedthinking.md`
211- Agent Generalization: See `docs/agentthinking.md`
212 
213---
214 
215## Skill Metadata
216 
217**Created**: 2025-01-11
218**Author**: Muratcan Koylan
219**Version**: 0.1.0
220**Powered by**: MiniMax M2.1
221**Partnership**: Built in collaboration with MiniMax AI
222