forking-iteration

Forking Iteration

Overview

Create new autonomy branch forked from current commit or any iteration tag in git history. Enables "slime mold strategy" of parallel exploration.

Core principle: Branch creation is independent of iteration management. Fork creates branch, start-iteration begins work.

When to Use

Use this skill when:

• User runs /fork-iteration command
• User wants to create new exploration branch
• User wants to try alternative approach from past iteration
• User wants to bootstrap autonomy workflow from non-autonomy branch

DO NOT use for:

• Creating non-autonomy branches (use git directly)
• Starting iterations (use starting-an-iteration instead)

Quick Reference

Process

Step 1: Parse and Validate Arguments

Extract arguments from command args:

Format: [iteration] <strategy-name>

Parse:

If args contains only one word:
  iteration = None
  strategy_name = args
Else if args contains two words:
  iteration = first word
  strategy_name = second word
Else:
  Error: "Invalid arguments. Usage: /fork-iteration [iteration] <strategy-name>"

Validate strategy-name:

• Must be kebab-case (lowercase, hyphens, no special chars)
• Must not be empty
• Should be descriptive (warn if too generic like "test" or "new")

Normalize strategy-name:

# Convert to lowercase, replace invalid chars with hyphens
strategy_name=$(echo "$strategy_name" | tr '[:upper:]' '[:lower:]' | tr -cs '[:alnum:]-' '-' | sed 's/^-*//; s/-*$//')

Step 2: Check if Branch Already Exists

Validate that autonomy/<strategy-name> doesn't already exist:

# Check for existing branch (local or remote)
if git branch -a | grep -q "autonomy/$strategy_name\
quot;; then
  # Error: branch exists
fi

If exists:

Error: Branch 'autonomy/<strategy-name>' already exists.

To work on existing branch:
  git checkout autonomy/<strategy-name>

To create with different name:
  /fork-iteration [iteration] <different-name>

Available autonomy branches:
[List from git branch -a | grep autonomy/]

Stop here if branch exists.

Step 3: Resolve Fork Point

Determine what commit to fork from:

If iteration specified:

# Search for iteration tag in current branch history
matching_tags=$(git tag --merged HEAD | grep "iteration-$(printf '%04d' $iteration)\
quot;)

tag_count=$(echo "$matching_tags" | wc -l)

if [ "$tag_count" -eq 0 ]; then
  # Error: iteration not found
  echo "Error: Iteration $iteration not found in current branch history."
  echo ""
  echo "Most recent iterations in current branch:"
  git tag --merged HEAD | grep 'iteration-' | tail -5
  exit 1
elif [ "$tag_count" -eq 1 ]; then
  # Use the tag
  fork_point="$matching_tags"
else
  # Multiple matches (shouldn't happen with branch-namespaced tags, but handle it)
  echo "Multiple iteration tags found for iteration $iteration:"
  echo "$matching_tags"
  echo ""
  # Use AskUserQuestion to let user choose
  exit 1
fi

If iteration NOT specified:

# Fork from current HEAD
fork_point=$(git rev-parse HEAD)
fork_description="current commit (HEAD)"

Validate fork point exists:

if ! git rev-parse "$fork_point" >/dev/null 2>&1; then
  echo "Error: Fork point '$fork_point' not found in git history."
  exit 1
fi

Step 4: Create New Branch

Checkout fork point and create new autonomy branch:

# Checkout fork point (detached HEAD)
git checkout "$fork_point"

# Create and switch to new branch
git checkout -b "autonomy/$strategy_name"

# Confirm creation
current_branch=$(git branch --show-current)
if [ "$current_branch" != "autonomy/$strategy_name" ]; then
  echo "Error: Failed to create branch 'autonomy/$strategy_name'"
  exit 1
fi

On success:

• Branch created and checked out
• Working directory contains files from fork point
• Ready for /start-iteration

Step 5: Report Success

Announce successful branch creation:

✓ Branch `autonomy/<strategy-name>` created

Forked from: [tag or commit hash]
Current branch: autonomy/<strategy-name>

Next step: Run `/start-iteration` to begin work on this branch.

Important Notes

Branch Creation Only

This skill ONLY creates branches:

• Does NOT start iterations
• Does NOT modify journal files
• Does NOT determine iteration numbering
• start-iteration will handle iteration logic when user runs it

Works from Any Starting Point

Can fork from:

• Autonomy branches (e.g., autonomy/experiment-a)
• Non-autonomy branches (e.g., main, develop)
• Detached HEAD
• Any commit with autonomy iteration tags

No Merge Provisions

Autonomy branches NEVER merge:

• Each branch is independent exploration
• Branches learn from each other via /analyze-branch (read-only)
• No git merge operations
• No rebase operations
• Branches are peers, not hierarchical

Strategy Name Matters

Branch name becomes identity:

• Used in tag names: autonomy/<strategy-name>/iteration-NNNN
• Appears in branch listings
• Should describe exploration direction
• Can't easily change later (would require tag renaming)

Good names:

• usage-based-pricing
• cdn-optimization
• react-migration

Bad names:

• test (too generic)
• new (not descriptive)
• experiment1 (meaningless)

Iteration Numbering Continuity

When start-iteration runs on new branch:

• If forked from iteration tag: continues numbering (fork from 0015 → next is 0016)
• If forked from non-iteration commit: starts at 0001 (if goal exists)
• If no goal exists: user must run /create-goal first

Common Mistakes

After Forking

Once branch is created:

• User is on new autonomy/<strategy-name> branch
• Working directory contains files from fork point
• No iterations started yet
• User runs /start-iteration to begin work
• Iteration numbering determined by start-iteration skill