Commit Hygiene Skill
Load with: base.md
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 - No clear purpose - Hard to review/revert
❌ "Updates" - 15 files changed - Mix of features, fixes, refactors - Impossible to review properly
Splitting Large Changes Strategy 1: By Layer Instead of one commit with: - API endpoint + database migration + frontend + tests
Split into: 1. "Add users table migration" 2. "Add User model and repository" 3. "Add GET /users endpoint" 4. "Add UserList component" 5. "Add integration tests for user flow"
Strategy 2: By Feature Slice Instead of one commit with: - All CRUD operations for users
Split into: 1. "Add create user functionality" 2. "Add read user functionality" 3. "Add update user functionality" 4. "Add delete user functionality"
Strategy 3: Refactor First Instead of: - Feature + refactoring mixed
Split into: 1. "Refactor: Extract validation helpers" (no behavior change) 2. "Add email validation using new helpers" (new feature)
Strategy 4: By Risk Level Instead of: - Safe changes + risky changes together
Split into: 1. "Update dependencies" (safe, isolated) 2. "Migrate to new API version" (risky, separate)
PR Size Guidelines Optimal PR Size Metric Optimal Acceptable Too Large Files 1-10 10-20 > 20 Lines changed 50-200 200-400 > 400 Commits 1-5 5-10 > 10 Review time < 30 min 30-60 min > 60 min PR Size vs Defect Rate ┌─────────────────────────────────────────────────────────────────┐ │ RESEARCH FINDINGS (Google, Microsoft studies) │ │ ───────────────────────────────────────────────────────────── │ │ PRs < 200 lines: 15% defect rate │ │ PRs 200-400 lines: 23% defect rate │ │ PRs > 400 lines: 40%+ defect rate │ │ │ │ Review quality drops sharply after 200-400 lines. │ │ Large PRs get "LGTM" rubber stamps, not real reviews. │ └─────────────────────────────────────────────────────────────────┘
When PR is Too Large
Check PR size before creating
git diff main --stat git diff main --shortstat
If too large, consider:
1. Split into multiple PRs (stacked PRs)
2. Create feature flag and merge incrementally
3. Use draft PR for early feedback
Commit Message Format
Structure
[optional body - wrap at 72 chars]
[optional footer]
Types Type Use For feat New feature fix Bug fix refactor Code change that neither fixes nor adds test Adding/updating tests docs Documentation only style Formatting, no code change chore Build, config, dependencies Examples feat: Add email validation to signup form
fix: Prevent null pointer in user lookup
refactor: Extract PaymentProcessor class
test: Add integration tests for checkout flow
chore: Update dependencies to latest versions
Git Workflow Integration Pre-Commit Hook for Size Check
!/bin/bash
.git/hooks/pre-commit
MAX_LINES=400 MAX_FILES=15
FILES=$(git diff --cached --name-only | wc -l | tr -d ' ') STATS=$(git diff --cached --shortstat) 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))
if [ "$TOTAL" -gt "$MAX_LINES" ]; then echo "❌ Commit too large: $TOTAL lines (max: $MAX_LINES)" echo " Consider splitting into smaller commits." echo " Use 'git add -p' for partial staging." exit 1 fi
if [ "$FILES" -gt "$MAX_FILES" ]; then echo "❌ Too many files: $FILES (max: $MAX_FILES)" echo " Consider splitting into smaller commits." exit 1 fi
echo "✅ Commit size OK: $FILES files, $TOTAL lines"
Partial Staging (Split Large Changes)
Stage specific hunks interactively
git add -p
Stage specific files
git add path/to/specific/file.ts
Stage with preview
git add -N file.ts # Intent to add git diff # See what would be added git add file.ts # Actually add
Unstage If Too Large
Unstage everything
git reset HEAD
Unstage specific files
git reset HEAD path/to/file.ts
Stage just what you need for THIS commit
git add -p
Claude Integration Periodic Check During Development
Claude should run this check after every significant change:
Quick status
git diff --shortstat HEAD
Thresholds for Claude to advise committing:
Condition Claude Action
5 files changed Suggest: "Consider committing current changes" 200 lines changed Suggest: "Changes are getting large, commit recommended" 10 files OR > 400 lines Warn: "⚠️ Commit now before changes become unmanageable" Test just passed Suggest: "Good checkpoint - commit these passing tests" Refactoring complete Suggest: "Refactoring done - commit before adding features" Claude Commit Reminder Messages 📊 Status: 7 files changed, +180 -45 (225 total) 💡 Approaching commit threshold. Consider committing current work.
📊 Status: 12 files changed, +320 -80 (400 total) ⚠️ Changes are large! Commit now to keep PRs reviewable. Suggested commit: "feat: Add user authentication flow"
📊 Status: 3 files changed, +85 -10 (95 total) ✅ Tests passing. Good time to commit! Suggested commit: "fix: Validate email format on signup"
Stacked PRs (For Large Features)
When a feature is genuinely large, use stacked PRs:
┌─────────────────────────────────────────────────────────────────┐ │ STACKED PR PATTERN │ │ ───────────────────────────────────────────────────────────── │ │ │ │ main ─────────────────────────────────────────────────────────│ │ └── PR #1: Database schema (200 lines) ← Review first │ │ └── PR #2: API endpoints (250 lines) ← Review second │ │ └── PR #3: Frontend (300 lines) ← Review third │ │ │ │ Each PR is reviewable independently. │ │ Merge in order: #1 → #2 → #3 │ └─────────────────────────────────────────────────────────────────┘
Creating Stacked PRs
Create base branch
git checkout -b feature/auth-schema
... make changes ...
git commit -m "feat: Add users table schema" git push -u origin feature/auth-schema gh pr create --base main --title "feat: Add users table schema"
Create next branch FROM the first
git checkout -b feature/auth-api
... make changes ...
git commit -m "feat: Add authentication API endpoints" git push -u origin feature/auth-api gh pr create --base feature/auth-schema --title "feat: Add auth API endpoints"
And so on...
Checklist Before Every Commit Changes are for ONE logical purpose Tests pass (if applicable) Lint/typecheck pass < 10 files changed < 400 lines total Commit message describes ONE thing Before Creating PR Total lines < 400 (ideal < 200) All commits are atomic No "WIP" or "fixup" commits PR title describes the change Description explains why, not just what Red Flags (Stop and Split) ❌ Commit message needs "and" ❌ > 10 files in one commit ❌ > 400 lines in one commit ❌ Mix of features, fixes, and refactors ❌ "I'll clean this up later" Quick Reference Thresholds Files: ≤ 5 = 🟢 | 6-10 = 🟡 | > 10 = 🔴 Lines: ≤ 200 = 🟢 | 201-400 = 🟡 | > 400 = 🔴 Time: ≤ 30min = 🟢 | 30-60min = 🟡 | > 60min = 🔴
Commands
Quick status
git diff --shortstat HEAD
Detailed file list
git diff --stat HEAD
Partial staging
git add -p
Check before PR
git diff main --shortstat
Commit Now If ✅ Tests just passed ✅ > 200 lines changed ✅ > 5 files changed ✅ About to switch tasks ✅ Current state is "working"