docs/SUBAGENT_WORKFLOW.md

@@ -91,3 +91,80 @@ OPEN → IN_PROGRESS (subagent claims it)
 
 - Research/docs: `docs/issue-{N}-{short-title}`
 - Fixes/tools: `fix/issue-{N}-{short-title}`
+
+## Branch Hygiene
+
+When branches are created incorrectly (e.g., from HEAD instead of main), they become contaminated with unwanted commits. This section provides a standard workflow for detecting and fixing this.
+
+### How Contamination Happens
+
+- Running `git checkout -b new-branch` (without explicit base) creates a branch from the current HEAD
+- If HEAD is not aligned with main (e.g., detached HEAD, or a different branch), the new branch inherits that history
+- The branch then contains commits that don't belong to the intended base
+
+### Detection
+
+**Symptom:** `git log` shows commits from a different/wrong branch at the start of the history.
+
+**Command to identify contamination:**
+```bash
+# Find commits that exist in wrong-branch but not in main
+git log main..wrong-branch --oneline
+
+# Check if a specific commit is contained in main
+git branch --contains <commit-id>
+# If empty output, the commit is NOT in main (contamination)
+
+# Or compare the first commit of your branch to main's tip
+git merge-base main your-branch
+# If this doesn't match the first commit on your branch, there's contamination
+```
+
+### Prevention
+
+**Always use explicit base when creating branches:**
+```bash
+# Correct - branch from main explicitly
+git checkout -b new-branch main
+
+# Incorrect - branch from current HEAD (may not be main)
+git checkout -b new-branch  # DANGEROUS if HEAD isn't main
+```
+
+### Fix Procedure
+
+If contamination is detected, use `git rebase --onto` to move the branch to the correct base:
+
+```bash
+# Syntax: git rebase --onto <new-base> <old-base> <branch-to-move>
+git rebase --onto main wrong-branch new-branch
+
+# Example:
+# - main is the correct base
+# - wrong-branch is the contaminated branch (the old base that was used incorrectly)
+# - new-branch is your current branch that has wrong commits
+
+# After rebase, verify with:
+git log --oneline main..
+git branch --contains <original-first-commit-id>  # Should be empty
+```
+
+### Force Push with Lease
+
+After rebasing, a force push is required. Use `--force-with-lease` for safety:
+
+```bash
+git push --force-with-lease origin new-branch
+```
+
+`--force-with-lease` is safer than `--force` because it will fail if someone else has pushed to the branch since you last fetched, preventing accidental overwrites.
+
+### Quick Reference
+
+| Scenario | Command |
+|----------|---------|
+| Create clean branch | `git checkout -b new-branch main` |
+| Detect contamination | `git log main..my-branch` (if non-empty, contaminated) |
+| Check commit presence | `git branch --contains <commit-id>` |
+| Fix contaminated branch | `git rebase --onto main wrong-base my-branch` |
+| Safe force push | `git push --force-with-lease origin my-branch` |