commit skill

Commit Pipeline

Skill(git-commit:commit-message)

Do not start the pipeline before that skill is loaded.

Project Configuration

<git-commit-config>
<validator-args>
<flag name="require-trailers" value="Task"/>
</validator-args>

<extra-instructions>
Project-specific commit guidance goes here.
</extra-instructions>
</git-commit-config>

Read the project CLAUDE.md file before the pipeline starts. Then obey the two elements:

• <validator-args> — give each flag to the validator. <flag name="X" value="Y"/> becomes --X "Y" on the command line.
• <extra-instructions> — the guidance with the highest priority for this commit. Obey it in each step. It overrides the defaults of this skill.

Ground Rules

A permission prompt for git add or git commit in the middle of the pipeline shows that the grant expired. Invoke this skill again to restore it.

1. Am I in the commit pipeline?
2. Which step am I on?
3. Are the steps before it complete?

Name the step when you report your position. Write "resuming the Commit Loop at Self-Review". If you are not sure, read the staged changes again with git diff --cached.

When to Commit

Run this pipeline during the work. Do not save it for the end of the task.

• Plan the units before the work starts. This pipeline then takes one planned unit at a time.
• Commit each verified step. The next step then builds on a committed base.
• An uncommitted tree holds no unit. A reviewer cannot read it. git bisect cannot use it.
• A tree with many units at entry shows a planning fault. Interleaved work splits badly. Split what separates cleanly. Then plan the change list before the next task.
• The coding skill of the-coder gives the change list and the size checkpoint.

Pipeline

1. Survey Changes

Run these commands in the repository that gets the commit:

git status --short --branch              # staged, unstaged, and untracked files
git diff                                 # unstaged changes to tracked files
git diff --cached                        # staged changes
git log --all --oneline --no-merges -10  # the subject form of the history

The first status column shows the staged state. The second column shows the unstaged state. The ?? mark shows an untracked file. If the status shows no change, tell the user that there is nothing to commit. Then stop.

The two diff commands do not show an untracked file. Stage such a file with an explicit path. In a repo with no commits, all files are untracked.

Then find the separate units in the changes.

Two tests find the boundaries. Apply both:

• The split test. Cut the change into two pieces. Does each piece build and pass its tests? Then the change holds more than one unit. Commit the first piece. Apply the test again to the rest.
• The work-kind test. A unit does one kind of work, because a reviewer answers one question in each unit. New code and the wiring that integrates it are two units. A refactor and the feature it makes possible are two units. The split test misses both boundaries, because both pieces build and pass together.

These conditions show a boundary between two units:

• The files serve different purposes.
• The diff mixes format changes with logic changes.
• The diff mixes a refactor with new behavior.
• The diff holds more than one unrelated bug fix.
• The diff adds new code and also wires that code into its callers.
• One part of the diff builds and passes its tests alone.

2. Plan Units and Order

Give a type to each unit. Then commit the types in this order:

1. Style — format, whitespace, and names.
2. Refactor — structure changes that keep the behavior.
3. Fix — bug corrections.
4. Feature — new functions.
5. Docs, test, and chore — documentation, tests, build, and tooling. Commit these units at any position.

Commit the style units and the refactor units first. This keeps the commits that change behavior clean.

Dependency order has priority over type order. If a fix builds on a feature, commit the feature first. Put the tests of a unit in the commit of that unit. Do not make a separate test commit, with one exception. Characterization tests pin the behavior of committed code before a change. They are a unit of their own. Commit them before that change.

3. Quality Gate

1. Did the lint, test, or build commands run for the changed files in this session? If they ran and passed, start the Commit Loop.
2. If no check ran, run the checks that apply to this project. Limit them to the changed files when this is possible.
3. If a check fails, correct the problem first. Do not commit defective code.
4. If all checks pass, start the Commit Loop.

Read <pipeline-awareness> again after you return from the fixes. Then continue at the first step of the Commit Loop. Do not start the pipeline again. Do not skip a step.

The split test asserts that each unit builds and passes alone. This pipeline does not measure that assertion. A wrong split leaves a broken commit in the middle of the history, and git bisect finds it much later.

Two habits keep the risk low. Commit a unit before the unit that depends on it. Give more care to the split test when a unit removes code, changes a signature, or moves a symbol, because these three cases break the callers that a later unit corrects.

4. Commit Loop

Do the steps below for each unit, in the planned order.

4a. Stage

git add <files>

Give an explicit path for each file. Do not use git add -p: it opens an interactive prompt, and the Bash tool has no terminal to answer it.

To unstage the wrong file:

git restore --staged <file>

One file can hold two units. Do one of these two things:

• Remove one change with the Edit tool, commit the first unit, then write the change again.
• Accept the larger commit, and record both units in the message.

4b. Draft Message

Write the message of this unit. Obey the commit-message conventions. Save the message with the Write tool to a file in the temp directory of the system. A file gives git the multi-line message, the quotes, and the backticks without damage. Shell quoting damages them.

The Write tool overwrites an existing file without a warning. Two signs show that another writer uses the name:

• The first write reports that the file was updated, not created. Write the message again under a different name.
• The file changes after you write it, and you did not change it. Write the message again under a different name.

Leave the file of the other writer alone. Never commit a message file that holds text you did not write.

Write the reason first, in one paragraph. Then cut: delete each sentence that the diff shows, and each paragraph that walks the reader through the new procedure.

4c. Self-Review

git diff --cached

Verify each item before you continue:

• The staged diff holds only the intended unit. It has no debug code and no temporary file.
• The staged diff agrees with the drafted message.
• The staged diff has no sensitive data such as an .env file, a credential, or a secret.
• The message obeys the commit-message conventions: terse register, no session artifacts, a record and not documentation.

P1: keep -- <the fact that it records>
P2: cut -- shown by the diff
P3.1: keep -- <the fact that it records>
P3.2: cut -- inventory of the diff

A paragraph earns keep only when it records the cause of the change, or an item of the earns-its-lines list in the commit-message conventions.

A paragraph can hold a list, with one line for each behavior change. Audit such a paragraph line by line, as P3.1 and P3.2 above, against the list rules of the commit-message conventions.

A paragraph gets cut when it names a function, a call order, an empty case, a fallback, or a flag that gates the new code. Such a paragraph reports the procedure, and the staged diff shows the procedure. Move the fact into the artifact when the next maintainer needs it. Then delete the paragraph.

The number of paragraphs follows the number of reasons, never the size of the diff. Write the message file again after the deletions.

4d. Validate

node ${CLAUDE_PLUGIN_ROOT}/scripts/validate-commit-message.mts --file <message file>

• Add the flags from <validator-args> when the project config defines them.
• Read the output. The validator prescribes; it does not block. It exits with status 0 even when it prints an ERROR, so the exit status tells you nothing about the message.
• Correct each ERROR before you continue.
• A WARN is a recommendation. Correct it when the correction is reasonable.

The validator does not check the ASCII rule, the 72-character body wrap, the scope format, the register, or AI attribution. You own those.

4e. Commit

Show the full message to the user as a blockquote. Then commit:

git commit -F <message file>

A project hook can stop the commit or change the files. Read the output. A hook that exits with an error stops the commit, and the message file stays for the next attempt. A hook that reformats a file does not stage that reformat: the commit holds the content that you staged, and the reformat stays in the working tree as an unstaged change. Run git status after the commit and amend the commit when the reformat belongs to the same unit. Do not pass --no-verify.

5. Verify

Run each command in a separate Bash call after the last unit:

git log --stat -3    # -3 = the number of commits that you created

git status

Then show the new commits with their subjects, the state of the current branch, and the changes that are still not committed.

Breaking Changes

Prefer a migration series to one breaking commit when you can stage the break:

1. Add the new code. Keep the old code.
2. Move the callers to the new code.
3. Delete the old code in a later commit.