Analyzing Branches

Analyzing Branches

Overview

Analyze another branch's iteration journals to extract key findings, decisions, and insights from work that diverged from the current branch.

Core principle: Learn from parallel explorations. Extract valuable insights from any branch, regardless of success or failure.

When to Use

Use this skill when:

• User runs /analyze-branch command
• Want to review work from parallel experiment branch
• Need to extract lessons from concluded experiments
• Comparing approaches across different branches
• Looking for salvageable ideas from any branch

DO NOT use for:

• Analyzing current branch history (use /review-progress instead)
• Comparing file changes (use git diff directly)
• When branches have no autonomy iterations

Quick Reference

Process

Step 1: Parse Arguments

Extract branch name and search criteria from command arguments:

Arguments format: "[branch-name] [search-description]"
Example: "experiment-a pricing experiments and revenue optimization"

Parse:

• First argument: Branch name (e.g., "experiment-a")
• Remaining arguments: Search criteria as free text

Verify goal exists:

# Use Glob to find goal
pattern: "autonomy/*/goal.md"

If no goal found:

"No autonomy goal found in this project. Branch analysis requires an autonomy goal."

Stop here.

Extract goal name from path for use in later steps.

Step 2: Find Divergence Point

Use git to find where branches diverged:

# Get current branch name
current_branch=$(git branch --show-current)

# Find common ancestor between current and target branch
merge_base=$(git merge-base "$current_branch" "$target_branch" 2>&1)

# Check if command succeeded
if [ $? -ne 0 ]; then
  # Error handling - see Step 2a
fi

Step 2a: Handle Git Errors

If git merge-base fails, determine cause and prompt user:

Error: Branch not found

Error: Branch '$target_branch' does not exist.

Available branches:
$(git branch -a | sed 's/^..//; s/ -> .*//')

Please verify the branch name and try again.

Error: No common ancestor

Warning: Cannot find common ancestor between current branch and '$target_branch'.

This may mean:
- Branches have completely independent histories
- Branch was rebased and history was rewritten

Options:
1. Analyze entire branch history (may include duplicate work)
2. Specify iteration range manually
3. Specify common ancestor commit manually

Which would you like?

Use AskUserQuestion to let user choose:

• Option 1: Set merge_base="" and analyze all iterations
• Option 2: Prompt for iteration range, skip git operations
• Option 3: Prompt for commit hash, use as merge_base

Step 3: Extract Divergent Iterations

Find autonomy iteration tags on target branch after divergence:

# Get all autonomy iteration tags on target branch
if [ -n "$merge_base" ]; then
  # Analyze only divergent work
  commit_range="$merge_base..$target_branch"
else
  # Analyze entire branch (fallback)
  commit_range="$target_branch"
fi

# Extract iteration numbers from tags
iterations=$(git log "$commit_range" \
  --pretty=format:"%D" \
  | tr ',' '\n' \
  | grep "tag: autonomy/iteration-" \
  | sed 's/.*autonomy\/iteration-//' \
  | sort -n)

# Count iterations found
iteration_count=$(echo "$iterations" | wc -w)

If no iterations found:

No autonomy iteration tags found on branch '$target_branch' after divergence.

Possible reasons:
- Branch hasn't used autonomy plugin
- All iterations are before the divergence point
- Iterations exist but weren't committed with git integration

Would you like to:
1. Analyze entire branch (all iterations)
2. Specify iteration range manually

Use AskUserQuestion for recovery.

Step 4: Read Journal Files

For each iteration found, read the journal content:

# For each iteration number
for iter in $iterations; do
  # Find journal file with this iteration number
  # Format: iteration-NNNN-YYYY-MM-DD.md
  journal_file=$(git ls-tree -r --name-only "$target_branch" \
    "autonomy/$goal_name/" \
    | grep "iteration-$(printf '%04d' $iter)-")

  if [ -n "$journal_file" ]; then
    # Read file content from target branch
    journal_content=$(git show "$target_branch:$journal_file")

    # Store for analysis in next step
  fi
done

Build iteration data structure: For each iteration, extract:

• Iteration number
• Date (from filename)
• Beginning State section
• Iteration Intention section
• Work Performed subsections
• Ending State section
• Full content for searching

Step 5: Search and Filter

Apply search criteria to find relevant iterations and content:

Search strategy:

# Convert search criteria to grep pattern
# Example: "pricing experiments" → "pricing|experiments"
search_pattern=$(echo "$search_criteria" | tr ' ' '|')

# For each iteration's content
# Score by relevance (number of search term matches)
# Prioritize sections: Key Decisions, Ending State, Reasoning & Strategy

Extract relevant sections:

• Key Findings: Extract from Ending State + Work Performed
• Decisions: Extract from Key Decisions Made subsection
• Ideas/Experiments: Extract from Reasoning & Strategy Changes
• Outcomes: Extract from Ending State

If search finds nothing:

No iterations matched search criteria: "$search_criteria"

Analyzed $iteration_count iterations on '$target_branch'.

Would you like to:
1. Broaden search (show all iterations)
2. Refine search criteria

Use AskUserQuestion to offer alternatives.

Step 6: Generate Report

Produce markdown report formatted for journal inclusion:

## Analysis of Branch: $target_branch

**Analyzed range:** Iterations $first_iter-$last_iter (diverged from iteration $divergence_iter)
**Search focus:** $search_criteria
**Common ancestor:** $merge_base
**Branch status:** [Active/Merged/Concluded - from latest iteration if stated]

---

### Key Findings

[For each significant finding extracted from journals:]
- **Iteration NNNN:** [Finding or insight]
  - **Context:** [What problem was being addressed]
  - **Approach taken:** [How it was implemented or explored]
  - **Outcome:** [Results from Ending State]
  - **Reference:** `$target_branch @ iteration-NNNN`

---

### Decisions and Rationale

[For each major decision from Key Decisions Made:]
- **Iteration NNNN:** [Decision]
  - **Rationale:** [Why this choice was made]
  - **Outcome:** [Result - success/failure/inconclusive/ongoing]
  - **Takeaway:** [What this tells us]

---

### Ideas and Experiments

[For each experimental approach from Reasoning & Strategy Changes:]
- **Iteration NNNN:** [What was tried]
  - **Results:** [What was learned]
  - **Status:** [Validated/Invalidated/Needs more testing/Inconclusive]
  - **Applicability:** [Could this apply to current branch?]

---

### Timeline of Branch Activity

| Iteration | Date | Summary | Status |
|-----------|------|---------|--------|
| NNNN | YYYY-MM-DD | [From Iteration Intention or Ending State] | [From Ending State] |
| NNNN | YYYY-MM-DD | [Summary] | [Status] |

---

**Analysis Summary:** [Neutral assessment of what was learned, key patterns, notable outcomes]

Output to user: Display the complete report. User can copy relevant sections into their current journal's "External Context Gathered" section.

Important Notes

Neutral Framing

Do NOT assume branch status:

• Branch may be active, merged, concluded, or abandoned
• Don't label as "failed" unless journal explicitly states that
• Let the journal entries speak for themselves
• Use neutral language: "findings", "outcomes", not "failures"

Git Safety

Read-only operations:

• Never checkout or switch branches
• Use git show to read historical files
• Don't modify target branch
• Don't create commits

Search Flexibility

Interpreting search criteria:

• Free-text is intentionally loose
• Don't require exact matches
• Look for semantic relevance
• Prioritize iteration sections mentioned in criteria

If criteria is very specific:

• "pricing tier experiments" → Focus on those specific words
• "revenue optimization" → Include related terms (profit, MRR, monetization)

If criteria is broad:

• "general findings" → Show all significant content
• "lessons learned" → Focus on Ending State assessments

Report Quality

Characteristics of good report:

• Self-contained: Readable without accessing original branch
• Actionable: Clear what to do with findings
• Referenced: Links to specific iterations for deep dives
• Concise: Extract signal, avoid noise
• Balanced: Show successes and failures equally

Performance Considerations

For branches with many iterations:

• Reading 50+ iterations may be slow
• Consider limiting to most recent N iterations if search is broad
• User can refine criteria to narrow scope

Common Mistakes

After Analyzing

Once analysis is complete:

• Report displayed to user
• User copies relevant sections into current journal
• No files created or modified by this skill
• Can analyze multiple branches in same conversation
• Skill usage logged in journal's "Skills & Workflows Used" section