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:

cat > .claude/.commit-state.json <<'EOF'
{
  "workflow_completed": true
}
EOF

This signals the pre-commit hook that you followed the workflow. Expires in 5 minutes, auto-deletes after ANY

git commit

attempt (success or failure).

If commit fails/is blocked: Rewrite this file before retrying.

Commit Message Format

type(scope): description

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