---
name: commit
description: Create atomic git commits following project conventions
---

# Commit

## When to use

Use this skill when asked to commit changes, group changes into commits, or prepare commits.

## Commit message rules

- Focus on **why** the change was made, not what changed — the diff shows the "what"
- First line: imperative mood, max 72 characters (e.g. "Ensure order draft flow in unit tests")
- Leave a blank line after the first line if adding a body
- Body (optional): explain motivation, context, or trade-offs — not a list of files changed
- Never mention AI tools, Claude, Claude Code, or assistants in commit messages
- Never mention skills, slash commands, or internal tooling in commit messages
- No "Co-Authored-By" lines
- Be precise about what technology/component is involved — don't say "previous upgrade" or "the tool", name the specific thing (e.g., "Rails gems", "activesupport")

## Atomic commits

- Each commit must leave the test suite green (`make test` must pass)
- Each commit must be releasable and deployable on its own: green tests and
  no half-wired user-facing behavior. Dormant code (a handler or process
  manager nothing triggers yet) is fine
- When building a feature with /new-feature, one slice = one commit: commit
  at the end of each slice instead of carving up a large finished diff
  afterward
- Group related changes together — a commit should represent one logical change
- Never commit generated or transient tool output (e.g. `.mutant/results/*.json`,
  coverage reports, logs, tmp files). Review untracked files in `git status`
  before staging — stage files explicitly instead of `git add .` / `git add -A`,
  and gitignore recurring artifacts
- If a change spans multiple files but serves one purpose, it belongs in one commit
- Order commits so each builds on the previous without breaking tests
- When splitting a large changeset into commits, verify each commit independently:
  1. Stage only the files for that commit
  2. Stash the rest (`git stash --keep-index`)
  3. Run tests (`make test`)
  4. Unstash (`git stash pop`)
  5. If tests pass, commit

## Process

1. Review all uncommitted changes (`git status`, `git diff`)
2. Identify logical groups of changes
3. Determine the right commit order (dependencies first)
4. For each commit:
   - Stage relevant files
   - Verify tests pass with only those changes
   - Draft a commit message following the rules above
   - Present the staged files and message for user approval
5. Wait for user confirmation before committing

## Examples of good commit messages

```
Ensure integration tests use proper order creation flow

Tests were creating orders via SecureRandom.uuid without going through
the draft flow, skipping the OfferDrafted event that read models depend on.
```

```
Add Deals read model for sales pipeline tracking
```

```
Replace defensive &. checks with find_by! in event handlers

Events always follow the real application flow, so records are
guaranteed to exist. Using find_by! surfaces bugs instead of hiding them.
```