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

| Step | Action | Tool | |------|--------|------| | 1. Parse arguments | Extract branch name and search criteria | Manual | | 2. Find divergence | Use git merge-base to find common ancestor | Bash | | 3. Extract iterations | Get autonomy tags from divergent commits | Bash | | 4. Read journals | Read iteration files from target branch | Bash, Read | | 5. Search and filter | Find relevant content based on criteria | Manual | | 6. Generate report | Create markdown summary | Direct output |

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

| Mistake | Reality | |---------|---------| | "Branch is abandoned, so it failed" | NO. Don't assume status. Read journals for actual outcomes. | | "I'll modify the target branch" | NO. Read-only operations only. Never checkout or modify target. | | "Search found nothing, report empty" | NO. Offer to broaden search or show all iterations. | | "I'll analyze current branch" | NO. Use /review-progress for current branch analysis. | | "No common ancestor means I should fail" | NO. Offer alternatives: analyze all, manual range, manual ancestor. | | "Report should only include successes" | NO. Balanced view - show what worked AND what didn't. |

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