git-squash

What this skill does

# Git Squash Skill

**Purpose**: Safely squash multiple commits into one with automatic backup, verification, and cleanup.

## Parallel Initial Investigation

**OPTIMIZATION: Run initial git commands in parallel to reduce round-trips.**

Before starting any squash workflow, gather information concurrently:

```bash
# Run these commands in parallel (use & and wait)
git rev-parse HEAD &
git status --porcelain &
git log --oneline <base>..HEAD &
git diff --stat <base>..HEAD &
wait

# All results now available for workflow selection
```

This reduces the initial investigation from 4+ sequential commands to a single parallel batch.

## Safety Pattern: Backup-Verify-Cleanup

**ALWAYS follow this pattern:**
1. Create timestamped backup branch
2. Execute the squash
3. **Verify immediately** - no changes lost or added
4. Cleanup backup only after verification passes

## Read PROJECT.md Squash Policy

**Check PROJECT.md for configured squash preferences before proceeding.**

```bash
# Read squash policy from PROJECT.md
SQUASH_POLICY=$(grep -A10 "### Squash Policy" .claude/cat/PROJECT.md 2>/dev/null | grep "Strategy:" | sed 's/.*Strategy:\s*//' | head -1)

if [[ "$SQUASH_POLICY" == *"keep all"* || "$SQUASH_POLICY" == *"Keep all"* || "$SQUASH_POLICY" == *"keep-all"* ]]; then
  echo "⚠️ PROJECT.md configured for 'Keep all commits'"
  echo "Squashing will override this preference."
  echo ""
  echo "Options:"
  echo "  1. Proceed with squash (override PROJECT.md preference)"
  echo "  2. Cancel to preserve commits as configured"
  echo ""
  echo "To proceed, continue with this skill."
  echo "To honor PROJECT.md preference, abort the squash operation."
fi

if [[ "$SQUASH_POLICY" == *"single"* || "$SQUASH_POLICY" == *"Single"* ]]; then
  echo "📋 PROJECT.md configured for 'Single commit' squashing"
  echo "All commits will be squashed into one (not by type)."
fi

if [[ "$SQUASH_POLICY" == *"by-type"* || "$SQUASH_POLICY" == *"by type"* ]]; then
  echo "📋 PROJECT.md configured for 'Squash by type'"
  echo "Commits will be grouped by type prefix."
fi
```

## Workflow Selection

**CRITICAL: Choose workflow based on commit position.**

```bash
# Check if commits are at tip of branch
LAST_COMMIT="<last-commit-to-squash>"
BRANCH_TIP=$(git rev-parse HEAD)

if [ "$(git rev-parse $LAST_COMMIT)" = "$BRANCH_TIP" ]; then
    echo "Commits at tip → Use Quick Workflow (soft reset)"
else
    echo "Commits in middle of history → Use Interactive Rebase Workflow"
fi
```

## Planning Commit Pattern Detection

**Detect common "feature + planning STATE.md update" pattern.**

Before squashing, check if the commit sequence follows this pattern:
1. Implementation commit(s): `feature:`, `bugfix:`, `refactor:`, etc.
2. Final commit(s): `planning:` or `config:` with only `.claude/cat/issues/` changes

**Detection logic:**
```bash
# Get the last commit's type and files
LAST_COMMIT=$(git log -1 --format="%s" HEAD)
LAST_FILES=$(git diff-tree --no-commit-id --name-only -r HEAD)

# Check if last commit is planning-only
if [[ "$LAST_COMMIT" =~ ^planning: ]] && \
   [[ "$LAST_FILES" =~ \.claude/cat/issues/ ]] && \
   ! echo "$LAST_FILES" | grep -qv "\.claude/cat/"; then
    echo "PATTERN DETECTED: Final commit is planning-only STATE.md update"
    # This pattern indicates STATE.md should be preserved in squash
fi
```

**When pattern detected:**
- Extract final STATE.md content before squash
- After squash, ensure STATE.md reflects final state (not intermediate)
- Include planning changes in implementation commit per M076

## Quick Workflow (Commits at Branch Tip Only)

**Use ONLY when squashing the most recent commits on a branch.**

```bash
# 1. Verify commits are at tip
git log --oneline -1  # Should show <last-commit-to-squash>

# 2. Create backup
BACKUP="backup-before-squash-$(date +%Y%m%d-%H%M%S)"
git branch "$BACKUP"

# 3. Verify clean working directory
git status --porcelain  # Must be empty

# 4. Check for unintended deletions (M238)
# If base branch has files your branch doesn't, soft reset will stage deletions!
echo "Files on base but not in branch (will be DELETED if you proceed):"
git diff --name-status <base-commit>..HEAD | grep "^D" | cut -f2
# If any unexpected files shown, sync with base first:
#   git checkout <base-commit> -- <path-to-restore>

# 5. Soft reset to base (parent of first commit to squash)
git reset --soft <base-commit>

# 6. Verify no UNINTENDED changes (check for unexpected deletions!)
git diff --stat "$BACKUP"  # Must be empty
git diff --name-status HEAD | grep "^D"  # Review any deletions!

# 7. Create squashed commit (see git-commit skill for message guidance)
git commit -m "Unified message describing what code does"

# 8. Verify result
git diff "$BACKUP"  # Must be empty
git rev-list --count <base-commit>..HEAD  # Must be 1

# 9. Cleanup backup
git branch -D "$BACKUP"
```

## Interactive Rebase Workflow (Commits in Middle of History)

**Use when commits to squash have other commits after them.**

```bash
# 1. Create backup of current branch
BACKUP="backup-before-squash-$(date +%Y%m%d-%H%M%S)"
git branch "$BACKUP"

# 2. Create sequence editor script
FIRST_COMMIT="<first-commit-to-squash>"  # Keep this one, squash others into it
COMMITS_TO_SQUASH="<second-commit> <third-commit> ..."  # These get squashed

cat > /tmp/squash-editor.sh << EOF
#!/bin/bash
$(for c in $COMMITS_TO_SQUASH; do echo "sed -i 's/^pick $c/squash $c/' \"\$1\""; done)
EOF
chmod +x /tmp/squash-editor.sh

# 3. Create commit message editor script
cat > /tmp/msg-editor.sh << 'EOF'
#!/bin/bash
cat > "$1" << 'MSG'
<your unified commit message here>
MSG
EOF
chmod +x /tmp/msg-editor.sh

# 4. Run interactive rebase
# NOTE: Use GIT_EDITOR (not EDITOR) - git uses GIT_EDITOR for commit messages during rebase
BASE_COMMIT="<parent-of-first-commit>"
GIT_SEQUENCE_EDITOR=/tmp/squash-editor.sh GIT_EDITOR=/tmp/msg-editor.sh git rebase -i $BASE_COMMIT

# 5. Verify no changes lost
git diff "$BACKUP"  # Must be empty

# 6. Cleanup
git branch -D "$BACKUP"
rm /tmp/squash-editor.sh /tmp/msg-editor.sh
```

## Critical Rules

### Check for Unintended Deletions (M238)

**CRITICAL: Worktrees may be out of sync with base branch updates.**

When using `git reset --soft <base>`, the index reflects your working tree state. If the base
branch has files your branch never received (e.g., new files added to base after your branch
diverged), the soft reset will stage those files as DELETIONS.

**Before committing after soft reset:**

```bash
# Check what will be deleted relative to base
git diff --name-status HEAD | grep "^D"

# If unexpected deletions appear, restore from base:
git checkout <base> -- <path-to-unexpected-deleted-file>

# Then amend the commit
git commit --amend --no-edit
```

**Why this happens:**
1. Branch created from older base commit
2. New files added to base branch later
3. Worktree never received these files (no merge/rebase from base)
4. Soft reset stages "delete files that exist on base but not in working tree"

### Preserve Commit Type Boundaries When Squashing

**CRITICAL: Follow commit grouping rules from [commit-types.md](../../concepts/commit-types.md).**

Key rules when squashing:
- **Task STATE.md** → same commit as implementation (M076)
- **Different commit types** (`feature:` vs `docs:`) → keep separate
- **Related same-type commits** → can combine

**Before squashing, analyze commit types:**

```bash
# List commits with their types
git log --oneline <base>..HEAD | while read hash msg; do
    type=$(echo "$msg" | cut -d: -f1)
    echo "$type: $hash ${msg#*: }"
done | sort -t: -k1

# Group by type to determine squash strategy
git log --format="%s" <base>..HEAD | cut -d: -f1 | sort | uniq -c
```

### Automatic STATE.md Preservation

**CRITICAL: Preserve final STATE.md state when squashing planning commits.**

When squashing commits that include STATE.md updates:

1. **Before squash:** Record the final STATE.md content
   ```bash
   # Store final state before squash
   TASK_STATE=".claude/cat/issues