Atomic Commits Skill

Create a small set of self-contained commits with descriptive messages and verified checks.

Workflow

Step 1: Analyze Changes

Gather information about the current state:

git status
git diff
git diff --staged
git log --oneline -10

# Clear staging area to ensure clean slate for atomic commits
git reset

Step 2: Plan Atomic Commits

Analyze the changes and group them into logical atomic commits. Each commit should:

• •Be self-contained and buildable
• •Contain logically related changes
• •Follow Conventional Commits format: <type>: <description>
• •Have a detailed body explaining the what and why

Grouping guidance:

• •Group by feature, not by file. If changes across multiple files implement a single feature, commit them together.
• •A "feature" typically includes: backend implementation, frontend wiring, and any related type/model changes.
• •Only split when changes are truly independent (e.g., a feature vs. its test updates vs. unrelated docs).
• •Avoid over-granular commits that split a single coherent change just because it touches many files.

Common commit types:

• •feat: - New feature
• •fix: - Bug fix
• •refactor: - Code refactoring (no behavior change)
• •chore: - Maintenance tasks, dependencies, config
• •docs: - Documentation changes
• •test: - Test changes
• •build: - Build system or dependency changes
• •perf: - Performance improvements

Step 3: Present the Plan

Before committing, present the planned commits to the user in a clear format:

Planned commits (N total):

1. [type]: brief description
   Files: path/to/file1, path/to/file2
   Details: explanation of what changes and why

2. [type]: brief description
   Files: path/to/file3
   Details: explanation of what changes and why

Ask for user confirmation before proceeding.

Step 4: Run All Checks ONCE (Before Creating Commits)

IMPORTANT: Run checks ONCE for all changes before starting to create commits. Pre-commit will run again during each git commit, so this catches issues upfront and avoids repeated runs.

# Run pre-commit on all files (catches linting, type-check, test issues)
pre-commit run --all-files

If this repo uses direnv, ensure it is allowed before running. Otherwise activate the dev env (often source .dev-env) before running Python tooling.

Why this approach:

• •Pre-commit already runs linting, type-checking, and tests
• •Running once before committing is more efficient than per-commit
• •Prevents the pre-commit hook from failing mid-commit sequence

Continue to Step 5 only after all checks pass.

Step 5: Resolve Issues

If pre-commit run --all-files fails:

1. •Fix the issues
2. •Re-run pre-commit run --all-files (not individual checks)
3. •Repeat until all checks pass
4. •CRITICAL: Do NOT proceed to create commits until all checks pass
5. •Only then proceed to Step 6

Step 6: Create Commits

GUARD: Only proceed here after ALL pre-commit checks have passed.

Create commits one at a time, staging only the files for each commit:

# For each planned commit:
git add <files-for-this-commit>

# CRITICAL: Verify what will actually be committed before committing
git diff --cached

Review the staged diff carefully:

• •Does it contain ONLY the changes described in this commit?
• •Are there unrelated changes bundled in? (especially if a file has multiple logical changes)
• •If wrong changes are staged, use git reset and re-stage more carefully
• •For files with multiple independent changes, consider using git add -p to stage specific hunks

Only AFTER verifying the staged diff matches the planned commit:

git commit -F - <<'EOF'
<type>: <brief description>

<detailed explanation of changes>

EOF

IMPORTANT:

• •Always verify with git diff --cached BEFORE committing
• •Always use HEREDOC syntax for commit messages to ensure proper formatting
• •Each commit must be created separately (never batch multiple logical commits)
• •Do NOT use git commit --amend - always create new commits
• •Do NOT push commits - the skill only creates them locally
• •Pre-commit hooks will run during each git commit (but should pass since you ran --all-files first)

Step 7: Verify and Report

After all commits are created:

# Show the commits created
git log --oneline -10
git status

Report to the user:

• •Number of commits created
• •Brief summary of each commit
• •Confirmation that tests passed
• •Reminder that commits are local and not pushed

Example Output

After completing, report to the user like this:

✓ Created 3 atomic commits:

  1. feat: add user authentication middleware
     - Added JWT token validation
     - Implemented login/logout endpoints
     - Added user session management

  2. refactor: extract validation logic to shared module
     - Moved validators to backend/app/api/v1/shared/
     - Updated all endpoints to use shared validators
     - Reduced code duplication

  3. docs: update API documentation for auth endpoints
     - Added authentication flow diagrams
     - Documented token refresh mechanism

All tests passed. Commits are ready locally (not pushed).

Important Notes

• •NEVER commit without verifying - Always run git diff --cached after staging and BEFORE committing to verify exactly what will be committed
• •Never skip tests - Always run the full test suite before committing
• •Never push - This skill only creates local commits
• •Always use HEREDOC for commit message formatting
• •Always create new commits - never amend existing ones
• •Group logically - Atomic commits should be self-contained units
• •Follow project style - Match existing commit message patterns