reasoning-trace-optimizer

Files (63)

• README.md
• SKILL.md
• agentthinking.md · docs/
• interleavedthinking.md · docs/
• m2-1.md · docs/
• 01_basic_capture.py · examples/
• 02_tool_usage.py · examples/
• 03_full_optimization.py · examples/
• SKILL.md · generated_skills/comprehensive-research-agent/
• optimization_summary.json · generated_skills/comprehensive-research-agent/references/
• optimized_prompt.txt · generated_skills/comprehensive-research-agent/references/
• patterns_found.json · generated_skills/comprehensive-research-agent/references/
• final_prompt.txt · optimization_artifacts/
• analysis.txt · optimization_artifacts/iteration_1/
• optimization.txt · optimization_artifacts/iteration_1/
• optimized_prompt.txt · optimization_artifacts/iteration_1/
• trace.txt · optimization_artifacts/iteration_1/
• analysis.txt · optimization_artifacts/iteration_10/
• trace.txt · optimization_artifacts/iteration_10/
• analysis.txt · optimization_artifacts/iteration_2/
• optimization.txt · optimization_artifacts/iteration_2/
• optimized_prompt.txt · optimization_artifacts/iteration_2/
• trace.txt · optimization_artifacts/iteration_2/
• analysis.txt · optimization_artifacts/iteration_3/
• optimization.txt · optimization_artifacts/iteration_3/
• optimized_prompt.txt · optimization_artifacts/iteration_3/
• trace.txt · optimization_artifacts/iteration_3/
• analysis.txt · optimization_artifacts/iteration_4/
• optimization.txt · optimization_artifacts/iteration_4/
• optimized_prompt.txt · optimization_artifacts/iteration_4/
• trace.txt · optimization_artifacts/iteration_4/
• analysis.txt · optimization_artifacts/iteration_5/
• optimization.txt · optimization_artifacts/iteration_5/
• optimized_prompt.txt · optimization_artifacts/iteration_5/
• trace.txt · optimization_artifacts/iteration_5/
• analysis.txt · optimization_artifacts/iteration_6/
• optimization.txt · optimization_artifacts/iteration_6/
• optimized_prompt.txt · optimization_artifacts/iteration_6/
• trace.txt · optimization_artifacts/iteration_6/
• analysis.txt · optimization_artifacts/iteration_7/
• optimization.txt · optimization_artifacts/iteration_7/
• optimized_prompt.txt · optimization_artifacts/iteration_7/
• trace.txt · optimization_artifacts/iteration_7/
• analysis.txt · optimization_artifacts/iteration_8/
• optimization.txt · optimization_artifacts/iteration_8/
• optimized_prompt.txt · optimization_artifacts/iteration_8/
• trace.txt · optimization_artifacts/iteration_8/
• analysis.txt · optimization_artifacts/iteration_9/
• optimization.txt · optimization_artifacts/iteration_9/
• optimized_prompt.txt · optimization_artifacts/iteration_9/
• trace.txt · optimization_artifacts/iteration_9/
• summary.json · optimization_artifacts/
• pyproject.toml
• __init__.py · reasoning_trace_optimizer/
• analyzer.py · reasoning_trace_optimizer/
• capture.py · reasoning_trace_optimizer/
• cli.py · reasoning_trace_optimizer/
• loop.py · reasoning_trace_optimizer/
• models.py · reasoning_trace_optimizer/
• optimizer.py · reasoning_trace_optimizer/
• …and 3 more

SKILL.md (first lines)

# Reasoning Trace Optimizer

Debug 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.

## When to Activate

- Agent reasoning traces need debugging, analysis, or prompt optimization
- Agent task fails and user wants to understand why
- User mentions "context degradation", "tool confusion", or "instruction drift"
- Request to improve agent performance or reduce errors
- User wants to generate shareable learnings from debugging sessions
- After repeated failures on similar tasks

## Core Concepts

### Interleaved Thinking

Unlike standard reasoning models that think once at the start, interleaved thinking allows reasoning BETWEEN each tool interaction. This is critical because:

1. **Long-horizon tasks** require maintaining focus across many turns
2. **External perturbations** (tool outputs, environment changes) need real-time adaptation
3. **Debugging** requires seeing HOW decisions were made, not just WHAT was output

### The Optimization Loop

```
Execute Agent → Capture Traces → Analyze Patterns → Optimize Prompt → Re-run
                                                          ↑____________|
```

Each iteration improves the prompt based on detected patterns until convergence.

### Pattern Detection

Common failure patterns the analyzer detects:

| Pattern | Description |
|---------|-------------|
| `context_degradation` | Model loses track of information over long contexts |
| `tool_confusion` | Model misunderstands tool capabilities or outputs |
| `instruction_drift` | Model gradually deviates from original instructions |
| `goal_abandonment` | Model stops pursuing the original goal |
| `circular_reasoning` | Model repeats similar actions without progress |
| `premature_conclusion` | Model concludes before completing the task |

## Usage Modes

### Mode 1: M2.1 Agent Debugging

Run a task through M2.1 and analyze its reasoning:

```python
from reasoning_trace_optimizer import TraceCapture, TraceAnalyzer

capture = TraceCapture()
trace = capture.run(
    task="Search for Python tutorials and summarize them",
    system_prompt="You are a research assistant.",
    tools=[search_tool],
    tool_executor=execute_search
)

analyzer = TraceAnalyzer()
analysis = analyzer.analyze(trace)

print(f"Score: {analysis.overall_score}/100")
for pattern in analysis.patterns:
    print(f"Found: {pattern.type.value} - {pattern.suggestion}")
```

### Mode 2: Full Optimization Loop

Automatically iterate until the prompt is optimized:

```python
from reasoning_trace_optimizer import OptimizationLoop, LoopConfig

config = LoopConfig(
    max_iterations=5,
    min_score_threshold=80.0,
)

loop = OptimizationLoop(config=config)
result = loop.run(
    task="Analyze this codebase and suggest improvements",
    initial_prompt="You are a code reviewer.",
    tools=[read_file_tool, search_tool],
    tool_executor=execute_tool
)

print(f"Improved: {result.initial_score} → {result.final_score}")
print(f"Final prompt:\n{result.final_prompt}")
```

### Mode 3: Universal Session Analysis

Analyze any agent's previous thinking (works with Claude, GPT, etc.):

When this skill is activated in Claude Code, it can analyze the current session's thinking blocks to identify issues and suggest improvements.

```
/reasoning-trace-optimizer analyze-session
```

### Mode 4: Generate Shareable Skills

Convert optimization learnings into reusable Agent Skills:

```python
from reasoning_trace_optimizer import SkillGenerator

generator = SkillGenerator()
skill_path = generator.generate(
    result=loop_result,
    skill_name="web-search-best-practices",
    output_dir="./skills"
)
```

From muratcankoylan/Agent-Skills-for-Context-Engineering, MIT.

More from muratcankoylan/Agent-Skills-for-Context-Engineering