analyze-branch

name	analyze-branch
description	Use when analyzing another branch's iteration journals to extract findings, decisions, and insights from divergent work
user-invocable	true

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] |

---

 [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