Branch Pairing - Watercooler

Branch pairing keeps your threads and code in sync by maintaining parallel branches in both repositories.

Concept

When working on a feature:

Code repo: feature/new-api branch
Threads repo: feature/new-api branch

Both branches evolve together, ensuring conversations about code stay connected to the code itself.

Benefits

Branch Context

Threads automatically associated with the right code version

Clean History

Merge threads and code together when feature is complete

Parallel Work

Multiple teams work on separate features without conflicts

Review Together

Review both code and conversation history in PRs

Setup

Step 1: Configure Repository Pair

Watercooler needs to know where both repos are. Create .watercooler/config.toml in your code repo:

[repository]
code_root = "."
threads_dir = "../threads"  # Path to threads repository

Or set environment variable:

export WATERCOOLER_THREADS_DIR="/path/to/threads"

Step 2: Verify Configuration

cd /path/to/code
watercooler check-branches

Output:

Branch Pairing Audit
============================================================

✅ Synchronized Branches:
  - main (code: a1b2c3d, threads: x9y8z7w)

Summary: 1 synced, 0 code-only, 0 threads-only

Workflow

Creating Paired Branches

Step 1: Create feature branch in code repo

cd /path/to/code
git checkout -b feature/new-dashboard

Step 2: Create matching branch in threads repo

cd /path/to/threads
git checkout -b feature/new-dashboard

Step 3: Start working

# In code repo: write code
cd /path/to/code
echo "// Dashboard component" > dashboard.tsx
git add dashboard.tsx
git commit -m "Add dashboard skeleton"

# In threads repo: document work
cd /path/to/threads
watercooler init-thread dashboard-design
watercooler say dashboard-design \
  --title "Initial design" \
  --body "Created basic dashboard layout with 4 widgets. Using Material-UI components."

git add dashboard-design.md
git commit -m "Document dashboard design"

Step 4: Verify sync

cd /path/to/code
watercooler check-branches

Output:

Branch Pairing Audit
============================================================

✅ Synchronized Branches:
  - main (code: a1b2c3d, threads: x9y8z7w)
  - feature/new-dashboard (code: e5f6g7h, threads: k4l5m6n)

Summary: 2 synced, 0 code-only, 0 threads-only

Detecting Drift

When branches exist in only one repo:

watercooler check-branches

Output:

Branch Pairing Audit
============================================================

✅ Synchronized Branches:
  - main (code: a1b2c3d, threads: x9y8z7w)

⚠️  Drift Detected:

Code-only branches (no threads counterpart):
  - feature/bug-fix (5 commits ahead of main)
    └─ Action: Create threads branch or delete if merged

Threads-only branches (no code counterpart):
  - feature/old-experiment (0 commits ahead of main)
    └─ Action: Safe to delete (fully merged)

Recommendations:
  - Create threads branch 'feature/bug-fix' to match code branch
  - Threads branch 'feature/old-experiment' is fully merged - safe to delete

Summary: 1 synced, 1 code-only, 1 threads-only

Merging Paired Branches

Step 1: Verify branches are synced

cd /path/to/code
watercooler check-branches

Step 2: Close open threads

Before merging, close any open threads on the feature branch:

cd /path/to/threads
git checkout feature/new-dashboard

# Close threads
watercooler set-status dashboard-design CLOSED
watercooler set-status dashboard-tests CLOSED

git add .
git commit -m "Close completed threads"

Step 3: Merge threads branch

watercooler merge-branch feature/new-dashboard

This:

Checks for OPEN threads (warns if found)

Switches to main in threads repo

Merges feature/new-dashboard to main

Uses --no-ff to preserve branch history

Output:

✅ Merged 'feature/new-dashboard' into 'main' in threads repo.

Step 4: Merge code branch

cd /path/to/code
git checkout main
git merge feature/new-dashboard --no-ff
git push origin main

Step 5: Clean up branches

# Delete code branch
cd /path/to/code
git branch -d feature/new-dashboard
git push origin --delete feature/new-dashboard

# Delete threads branch
cd /path/to/threads
git branch -d feature/new-dashboard
git push origin --delete feature/new-dashboard

Advanced Operations

Force Merge with Open Threads

If you need to merge despite open threads:

watercooler merge-branch feature/my-branch --force

Use --force carefully. Open threads will be moved to main, which may cause confusion about their context.

Archive Branch

Close all open threads, merge, and delete branch in one operation:

watercooler archive-branch feature/old-feature

This:

Finds all OPEN threads on the branch
Sets them to CLOSED
Commits the changes
Merges branch to main
Deletes the branch

With --abandon flag, marks threads as ABANDONED instead of CLOSED:

watercooler archive-branch feature/failed-experiment --abandon

Handle Merge Conflicts

Thread merge conflicts use append-only resolution:

watercooler merge-branch feature/my-branch

If conflicts occur:

⚠️  Merge conflict detected in 2 file(s):
  shared-topic.md, another-topic.md

Append-only conflict resolution:
  - Both entries will be preserved in chronological order
  - Status/Ball conflicts: Higher severity status wins, last entry author gets ball
  - Manual resolution may be required for complex conflicts

To resolve:
  1. Review conflicted files
  2. Keep both entries in chronological order
  3. Resolve header conflicts (status/ball) manually
  4. Run: git add <files> && git commit

Resolution strategy:

Entries: Keep both, sort by timestamp
Status: Higher severity wins (BLOCKED > OPEN > CLOSED)
Ball: Last entry’s author gets ball

Example:

<<<<<<< HEAD
## Entry 3 | 2026-03-01T10:00:00Z | Alice | planner

Design approach A
=======
## Entry 3 | 2026-03-01T10:05:00Z | Bob | implementer

Design approach B
>>>>>>> feature/my-branch

Resolved (both kept, chronological order):

## Entry 3 | 2026-03-01T10:00:00Z | Alice | planner

Design approach A

## Entry 4 | 2026-03-01T10:05:00Z | Bob | implementer

Design approach B

Git Hooks

Install Hooks

Automate branch pairing validation:

cd /path/to/code
watercooler install-hooks

This installs:

pre-push: Validates paired branch exists before push
pre-merge: Checks for open threads before merge

Output:

✅ Installed 2 hook(s): pre-push, pre-merge

Hooks will validate branch pairing before git operations.
To disable, remove hooks from .git/hooks/

Hook Behavior

pre-push Hook

git push origin feature/my-branch

If threads branch doesn’t exist:

⚠️  Branch pairing check failed!
Code branch 'feature/my-branch' has no matching threads branch.

Create threads branch:
  cd /path/to/threads
  git checkout -b feature/my-branch

Or skip this check:
  git push --no-verify

pre-merge Hook

git merge feature/my-branch

If threads branch has open threads:

⚠️  Merge validation failed!
Threads branch 'feature/my-branch' has 3 OPEN threads.

Recommended actions:
  1. Close threads: watercooler set-status <topic> CLOSED
  2. Force merge: git merge --no-verify

Override Hooks

Skip hook validation:

git push --no-verify
git merge --no-verify

Best Practices

1. Always Create Paired Branches

# Only create code branch
git checkout -b feature/new-api

2. Close Threads Before Merging

# Review open threads
watercooler list --open-only

# Close completed threads
watercooler set-status topic-1 CLOSED
watercooler set-status topic-2 CLOSED

# Then merge
watercooler merge-branch feature/my-branch

3. Use Consistent Branch Names

Match branch names exactly:

Code: feature/auth-redesign
Threads: feature/auth-redesign ✅

Not:

Code: feature/auth-redesign
Threads: feature/auth ❌

4. Regular Drift Checks

Add to CI/CD:

# .github/workflows/branch-pairing.yml
name: Branch Pairing Check
on: [push, pull_request]

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Check branch pairing
        run: |
          pip install watercooler
          watercooler check-branches

5. Include Thread Links in PRs

Reference threads in PR descriptions:

## Summary
Implements new authentication flow.

## Related Threads
- auth-redesign: Design decisions and approach
- jwt-implementation: Implementation details
- security-review: Security audit results

## Branch
Threads branch: `feature/auth-redesign`

Troubleshooting

Branch Pairing Check Fails

If check-branches fails with “Unable to resolve code and threads repo paths”:

# Set threads directory
export WATERCOOLER_THREADS_DIR="/path/to/threads"

# Or create config file
cat > .watercooler/config.toml <<EOF
[repository]
code_root = "."
threads_dir = "../threads"
EOF

GitPython Not Available

If you see “GitPython not available”:

pip install GitPython

Merge Fails with Conflicts

Manually resolve:

cd /path/to/threads
git checkout main
git merge feature/my-branch

# Resolve conflicts in editor
vim shared-topic.md

# Complete merge
git add shared-topic.md
git commit

Integration with Memory Graphs

Branch pairing works seamlessly with memory graphs:

# Build graph for feature branch
cd /path/to/threads
git checkout feature/new-api

watercooler baseline-graph build \
  --threads-dir . \
  --branch feature/new-api

# Search only this branch's threads
watercooler baseline-graph search \
  --query "API design" \
  --threads-dir .

Entry nodes include code_branch field:

{
  "entry_id": "01H2K3M4N5P6Q7R8S9T0",
  "thread_topic": "api-design",
  "title": "REST vs GraphQL",
  "code_branch": "feature/new-api"
}

This enables branch-specific queries and analysis.

Next Steps

Memory Graphs

Build knowledge graphs with branch context

Multi-Agent Workflows

Design workflows that leverage branch pairing

Get Started

Core Concepts

Setup & Configuration

Guides

​Concept

​Benefits

Branch Context

Clean History

Parallel Work

Review Together

​Setup

​Workflow

​Creating Paired Branches

​Detecting Drift

​Merging Paired Branches

​Advanced Operations

​Force Merge with Open Threads

​Archive Branch

​Handle Merge Conflicts

​Git Hooks

​Install Hooks

​Hook Behavior

​pre-push Hook

​pre-merge Hook

​Override Hooks

​Best Practices

​1. Always Create Paired Branches

​2. Close Threads Before Merging

​3. Use Consistent Branch Names

​4. Regular Drift Checks

​5. Include Thread Links in PRs

​Troubleshooting

​Branch Pairing Check Fails

​GitPython Not Available

​Merge Fails with Conflicts

​Integration with Memory Graphs

​Next Steps

Memory Graphs

Multi-Agent Workflows

Build docs developers (and LLMs) love

Concept

Benefits

Setup

Workflow

Creating Paired Branches

Detecting Drift

Merging Paired Branches

Advanced Operations

Force Merge with Open Threads

Archive Branch

Handle Merge Conflicts

Git Hooks

Install Hooks

Hook Behavior

pre-push Hook

pre-merge Hook

Override Hooks

Best Practices

1. Always Create Paired Branches

2. Close Threads Before Merging

3. Use Consistent Branch Names

4. Regular Drift Checks

5. Include Thread Links in PRs

Troubleshooting

Branch Pairing Check Fails

GitPython Not Available

Merge Fails with Conflicts

Integration with Memory Graphs

Next Steps