history-analysis

name	history-analysis
description	Use to systematically analyze the full evolution history without output truncation — produces a structured summary of what matters for the current iteration

History Analysis

Overview

As iterations accumulate, the output of evo-dag show history grows too large to read in a single terminal command. Naively piping through head -200 or tail -200 discards critical information — early iterations' lessons are lost with tail, and recent results are lost with head. This skill provides a structured methodology to analyze the complete history using targeted CLI commands, producing a focused summary of what matters for the current iteration.

When to Use

At the start of every session (Session 0, 1, and 2) before any other work. The history analysis provides the context needed for informed decisions — skipping it leads to repeated mistakes, redundant patches, and missed lessons.

The Problem with Truncation

Do NOT pipe evo-dag show history through head, tail, or any truncation command. This loses information:

• head -N: Loses all recent iterations' results and reflections
• tail -N: Loses early iterations' foundational lessons and patterns
• Increasing the number (head -300, tail -500) is a losing battle — the history grows every iteration

History Analysis Procedure

Step 1: Quick Orientation

Start with small, complete outputs to establish context:

# DAG topology and best candidate (always small output)
evo-dag summary

# DAG lineage visualization (always small output)
evo-dag show lineage

From this, note:

• How many iterations have been run
• Which candidate has the best dev score
• The current lineage path

Step 2: Full History via File Redirect

Redirect the full history to a temporary file and read it with file tools. This avoids terminal output truncation entirely:

evo-dag show history > /tmp/evo_history.txt

Then read the file in sections using file reading tools (e.g., cat with line ranges, or IDE file reading). This lets you see the complete history regardless of length.

Read the file in manageable sections:

• Start from the beginning to understand early foundational changes
• Read the end to see the most recent iterations
• Search for specific patterns or scenario IDs as needed

As you read, classify each iteration's patch into one of:

1. Good patch (✓ good patch): Note the iteration, approach, files changed, and which scenarios were fixed. These are patches to preserve.
2. Regression patch (✗ regression): Note the iteration, exact diff that caused harm, which scenarios regressed, and whether the regression persists. These are patches to revert.
3. Ineffective patch (✗ ineffective): Note what was tried and why it failed — to avoid repeating the same approach.

For each regression or good patch, also check the actual code diff in the history output. The diff shows exactly what lines were added/removed in which files — this is essential for knowing what to revert or protect when combining candidates.

Step 3: Targeted Deep Dives

For specific information, use targeted commands that produce focused output:

# Specific scenario's full history (root causes, attempted fixes)
evo-dag show scenario <scenario_id>

# Specific candidate's details (scores, intent, verdict)
evo-dag show node <idx>

# Specific edge's diff and impacts
evo-dag show edge <parent_idx> <child_idx>

# Current mini-batch context
evo-dag show current-batch

Use evo-dag show edge <parent> <child> to inspect the full diff of a specific patch when the diff in show history is truncated. This gives the complete code diff, files changed, and per-scenario impacts (fixed, regressed, still_failing, still_passing).

Step 4: Produce a Structured Summary

After reading the full history, produce a summary organized by these categories. The specific focus depends on the current session:

For Session 0 (Candidate Selection):

The goal is to classify every patch as revert vs. preserve so you can select the best candidate or combine candidates optimally:

• Patches to revert: Which patches caused regressions? For each, note the iteration, candidate index, exact files/diffs that caused harm, the scenarios that regressed, and whether the regression persists in the current lineage.
• Patches to preserve: Which patches drove the largest dev score gains? Which fixes were durable (stayed fixed in subsequent iterations)? Which generalized well beyond the target mini-batch? Note the files and patterns involved so you know what to protect.
• Cross-candidate complementarity: Do different candidates have non-overlapping strengths (e.g., one fixed email tools, another fixed calendar tools)? If so, their preserved patches can be combined.
• Lineage health: Is the current lineage accumulating regressions faster than fixes? If so, switching parent may be better than surgical revert.

This classification directly drives the selection decision:

• Continue from latest: Revert the harmful diffs while keeping the beneficial ones.
• Switch parent: If too many regressions have accumulated, switch to the best candidate and cherry-pick the preserved patches.
• Combine candidates: If different candidates have complementary preserved patches, combine them.

For Session 1 (Diagnose + Patch):

The goal is to inform diagnosis and patching — avoid repeating failed approaches and build on proven strategies:

• Relevant good/bad patterns: Which patterns from the history apply to the current mini-batch's failing scenarios?
• Prior attempts on target scenarios: For each failing scenario, use evo-dag show scenario <id> to check what was tried before, what worked, and what failed. Do not re-attempt approaches that already failed.
• Proven patch strategies: Which types of patches (tool fixes, docstring changes, hooks, prompt rules) have historically generalized well to the dev set?
• Regression-prone areas: Which files or components have historically caused regressions when modified? Take extra care with these.

For Session 2 (Reflection):

The goal is to write meaningful reflections that add new information beyond what prior iterations already captured:

• Historical context for each scenario: For each scenario in the mini-batch, what is its full history? How many times has it been attempted? Use evo-dag show scenario <id> for each.
• Pattern evolution: Are there emerging patterns (recurring root causes, files that keep causing problems) not yet captured in the history's good/bad patterns?
• Dev score attribution: For prior patches, which ones improved/hurt dev accuracy and why? Use this to write informed --generalization-note on reflections.

Key Principles

1. Never truncate: Use file redirect + file reading instead of pipe truncation
2. Start broad, then narrow: Summary → lessons → full history → targeted queries
3. Focus on relevance: Not all history matters equally for the current iteration — prioritize recent iterations, target scenarios' history, and accumulated lessons
4. Produce actionable output: The summary should directly inform the next step — candidate selection, diagnosis, or reflection writing