/commit-hygiene

name: commit-hygiene
description: Atomic commits, PR size limits, commit thresholds, stacked PRs
when-to-use: When committing code, creating PRs, or when change set is growing large
user-invocable: false
effort: low

Commit Hygiene Skill

**Purpose:** Keep commits atomic, PRs reviewable, and git history clean. Advise when it's time to commit before changes become too large.

---

Core Philosophy

┌─────────────────────────────────────────────────────────────────┐
│  ATOMIC COMMITS                                                  │
│  ─────────────────────────────────────────────────────────────  │
│  One logical change per commit.                                  │
│  Each commit should be self-contained and deployable.            │
│  If you need "and" to describe it, split it.                     │
├─────────────────────────────────────────────────────────────────┤
│  SMALL PRS WIN                                                   │
│  ─────────────────────────────────────────────────────────────  │
│  < 400 lines changed = reviewed in < 1 hour                      │
│  > 1000 lines = likely rubber-stamped or abandoned               │
│  Smaller PRs = faster reviews, fewer bugs, easier reverts        │
├─────────────────────────────────────────────────────────────────┤
│  COMMIT EARLY, COMMIT OFTEN                                      │
│  ─────────────────────────────────────────────────────────────  │
│  Working code? Commit it.                                        │
│  Test passing? Commit it.                                        │
│  Don't wait for "done" - commit at every stable point.           │
└─────────────────────────────────────────────────────────────────┘

---

Commit Size Thresholds

Warning Thresholds (Time to Commit!)

| Metric | Yellow Zone | Red Zone | Action | |--------|-------------|----------|--------| | **Files changed** | 5-10 files | > 10 files | Commit NOW | | **Lines added** | 150-300 lines | > 300 lines | Commit NOW | | **Lines deleted** | 100-200 lines | > 200 lines | Commit NOW | | **Total changes** | 250-400 lines | > 400 lines | Commit NOW | | **Time since last commit** | 30-60 min | > 60 min | Consider committing |

Ideal Commit Size

┌─────────────────────────────────────────────────────────────────┐
│  IDEAL COMMIT                                                    │
│  ─────────────────────────────────────────────────────────────  │
│  Files: 1-5                                                      │
│  Lines: 50-200 total changes                                     │
│  Scope: Single logical unit of work                              │
│  Message: Describes ONE thing                                    │
└─────────────────────────────────────────────────────────────────┘

---

Check Current State (Run Frequently)

Quick Status Check

# See what's changed (staged + unstaged)
git status --short

# Count files and lines changed
git diff --stat
git diff --cached --stat  # Staged only

# Get totals
git diff --shortstat
# Example output: 8 files changed, 245 insertions(+), 32 deletions(-)

Detailed Change Analysis

# Full diff summary with file names
git diff --stat HEAD

# Just the numbers
git diff --numstat HEAD | awk '{add+=$1; del+=$2} END {print "+"add" -"del" total:"add+del}'

# Files changed count
git status --porcelain | wc -l

Pre-Commit Check Script

#!/bin/bash
# scripts/check-commit-size.sh

# Thresholds
MAX_FILES=10
MAX_LINES=400
WARN_FILES=5
WARN_LINES=200

# Get stats
FILES=$(git status --porcelain | wc -l | tr -d ' ')
STATS=$(git diff --shortstat HEAD 2>/dev/null)
INSERTIONS=$(echo "$STATS" | grep -oE '[0-9]+ insertion' | grep -oE '[0-9]+' || echo 0)
DELETIONS=$(echo "$STATS" | grep -oE '[0-9]+ deletion' | grep -oE '[0-9]+' || echo 0)
TOTAL=$((INSERTIONS + DELETIONS))

echo "📊 Current changes: $FILES files, +$INSERTIONS -$DELETIONS ($TOTAL total lines)"

# Check thresholds
if [ "$FILES" -gt "$MAX_FILES" ] || [ "$TOTAL" -gt "$MAX_LINES" ]; then
    echo "🔴 RED ZONE: Commit immediately! Changes are too large."
    echo "   Consider splitting into multiple commits."
    exit 1
elif [ "$FILES" -gt "$WARN_FILES" ] || [ "$TOTAL" -gt "$WARN_LINES" ]; then
    echo "🟡 WARNING: Changes getting large. Commit soon."
    exit 0
else
    echo "🟢 OK: Changes are within healthy limits."
    exit 0
fi

---

When to Commit

Commit Triggers (Any One = Commit)

| Trigger | Example | |---------|---------| | **Test passes** | Just got a test green → commit | | **Feature complete** | Finished a function → commit | | **Refactor done** | Renamed variable across files → commit | | **Bug fixed** | Fixed the issue → commit | | **Before switching context** | About to work on something else → commit | | **Clean compile** | Code compiles/lints clean → commit | | **Threshold hit** | > 5 files or > 200 lines → commit |

Commit Immediately If

• ✅ Tests are passing after being red
• ✅ You're about to make a "big change"
• ✅ You've been coding for 30+ minutes
• ✅ You're about to try something risky
• ✅ The current state is "working"

Don't Wait For

• ❌ "Perfect" code
• ❌ All features done
• ❌ Full test coverage
• ❌ Code review from yourself
• ❌ Documentation complete

---

Atomic Commit Patterns

Good Atomic Commits

✅ "Add email validation to signup form"
   - 3 files: validator.ts, signup.tsx, signup.test.ts
   - 120 lines changed
   - Single purpose: email validation

✅ "Fix null pointer in user lookup"
   - 2 files: userService.ts, userService.test.ts
   - 25 lines changed
   - Single purpose: fix one bug

✅ "Refactor: Extract PaymentProcessor class"
   - 4 files: payment.ts → paymentProcessor.ts + types
   - 180 lines changed
   - Single purpose: refactoring

Bad Commits (Too Large)

❌ "Add authentication, fix bugs, update styles"
   - 25 files changed
   - 800 lines changed
   - Multiple purposes mixed

❌ "WIP"
   - Unknown scope