Commit Hygiene

What the source does

• FilesystemNone observedNo reads or writes in the source
• NetworkNone observedNo outbound calls in the source
• ShellNone observedNo commands run in the source
• DependenciesPinnedNothing floats
• SecretsNone foundNo keys in source

Five audit layers

Gates applied: no behavioural pass.

Audit 0.4.1 · source sha ea59a0c53d79 · 14 Oct 2026Report an issue or request a re-scan

• Publisheralinaqi GitHub userOwner of the repository this skill is read from
• Source folderalinaqi/claude-bootstrap/skills/commit-hygieneThe exact folder we audited
• LicenceMITAs the repository states it
• Commit pinned for this verdictea59a0c53d79A new audit runs when the source changes
• Repository statusNot archivedPushed today
• Sandboxed runNot runSkills are read, not executed; layer L4 is skipped

Its description: Atomic commits, PR size limits, commit thresholds, stacked PRs

---
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

```bash
# 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

```bash
# 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

```bash
#!/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
   - N

Excerpt, first 6,004 characters of SKILL.md, verbatim from the audited commit. It is text from someone else’s repository, quoted so you can judge it before your agent reads it.

git clone https://github.com/alinaqi/claude-bootstrap
git -C claude-bootstrap checkout ea59a0c53d79

Works in

1. 2026-10-14
   ✓SAFE B 89 / 100

   first audit · source ea59a0c53d79

Questions about Commit Hygiene

• github.com/alinaqi/claude-bootstrap/tree/main/skills/commit-hygi — the audited source at commit ea59a0c53d79 and every finding aboveObserved · 14 Oct 2026

Spotted something wrong? Report a correction · Methodology