creating-commits

What this skill does

# Creating Commits

Use before ANY commit - never skip for "simple" changes.

## MANDATORY FIRST STEP

**STOP: Create TodoWrite checklist BEFORE running any commands.**

**Correct pattern:**

1. Load this skill ✓
2. TodoWrite with 6 checklist items (see below) → FIRST response
3. Execute steps, updating todos (step 1 runs two operations in parallel)

**Wrong pattern (will fail):**

1. Load skill
2. Run git commands without TodoWrite
3. Forget a step
4. Hook blocks commit ❌

## Workflow Checklist

**Create these TodoWrite items as your FIRST action, ALL steps are required:**

1. ☐ Run `pnpm pre-commit` (if available) AND Read `docs/commit_specification.md` (PARALLEL)
2. ☐ Run `git diff` and analyze staging (see below)
3. ☐ `git add <files>` (stage atomic unit of related files)
4. ☐ `git diff --staged` (preview commit)
5. ☐ Write `.claude/.commit-state.json` (signals workflow completion)
6. ☐ `git commit -m "type(scope): description"`

**Parallel optimization:** Step 1 runs `pnpm pre-commit` (if the script exists) and reads `docs/commit_specification.md` simultaneously since they have no dependencies.

### Steps 2-3: Staging Analysis

Before running `git add`, check current staging state:

**Never stage files containing secrets** (`.env`, `credentials.json`, `*.pem`, `*_key`, etc.) - warn user if these appear in diff.

**Some files already staged?** User pre-selected - verify staged files form atomic unit.

**No files staged?** After reviewing `git diff`, evaluate what constitutes an atomic unit:

- If all changes form one logical unit → stage all files and proceed
- If multiple logical changes detected → use AskUserQuestion to ask which atomic unit to commit first, then suggest splitting rest into separate commits

**Multiple logical changes?** See Atomic Commits section below for how to identify and split.

### Step 5: Write Commit State File

Write this file after steps 1-4 and before step 6:

```bash
GIT_ROOT=$(git rev-parse --show-toplevel) && \
mkdir -p "$GIT_ROOT/.claude" && \
cat > "$GIT_ROOT/.claude/.commit-state.json" <<'EOF'
{
  "workflow_completed": true
}
EOF
```

**Important:** This command:
1. Gets the git repository root (fails safely if not in a git repo)
2. Creates `.claude/` directory if it doesn't exist
3. Writes the state file at the correct location regardless of working directory

This signals the pre-commit hook that you followed the workflow.
Considered stale after 5 minutes. If the commit fails (e.g., git's pre-commit hook rejects it), you can retry immediately without rewriting this file.

## Commit Message Format

`type(scope): description` - see [docs/commit_specification.md](../../docs/commit_specification.md)

**Focus on PURPOSE, not process:**

- ✅ "add creating-commits skill for git workflow"
- ❌ "create skill and refactor for efficiency"

Review FULL diff - message describes collective change, not just latest conversation.

## Atomic Commits

One logical change per commit.
If multiple concerns (mixed types, different scopes, unrelated files) → suggest splitting.

## Breaking Changes

If breaking backward compatibility → use `feat(api)!: description` and include `BREAKING CHANGE:` footer.

## Common Rationalizations (STOP)

**If you think any of these, STOP and follow checklist:**

- "Just a comment, skip checks" → Comments have syntax errors
- "User gave message, skip preview" → Can't see what's staged
- "Too simple for `pnpm pre-commit`" → Hooks fail on "simple" changes
- "One extra file won't hurt" → Breaks atomic commits

## When Checks Fail

**`pnpm pre-commit` fails on your changes?** Fix before committing.

**`pnpm pre-commit` fails on unrelated code?** Ask user:

1. Fix unrelated error first
2. Commit anyway (requires their decision)
3. Investigate error

Never assume "error is unrelated, skip check" - ask.

## Never Use `--no-verify`

Never use `git commit --no-verify` without **explicitly asking user permission first in bold text.**