Atomic commits

One commit has one purpose and one context. The message is a semantic commit written in Simplified Technical English (STE): short, exact, and easy to scan.

Uses semantic commit types, STE message rules, a guide for descriptive subjects and bodies, and two helper scripts.

Rules

1. One purpose per commit. If the subject needs the word "and", split the commit.
2. One context per commit. One module, package or layer. Put the tests, types and docs for a change in the same commit as the change.
3. Every commit works alone. It builds, and the tests for its context pass.
4. Prepare first, change second. Refactor in one commit. Change behavior in the next.
5. Keep formatting apart. A style-only change gets its own commit.
6. Describe the effect. The subject says what changed for the reader and under which condition. add plus a name is not enough. The body says why.
7. Commit only when the user asks. Do not push unless asked. Add no trailers (Co-authored-by, Generated with) unless the user's rule requires them.

Workflow

1. Look. Run git status --short and git diff --stat. Then run node scripts/group-changes.mjs for a starting grouping. It is a hint, not a plan.
2. Plan. Fill in templates/commit-plan.md: the commits in order, each with type(scope), a subject, its files or hunks, and how to verify it. Show the plan before you commit if it has more than two commits or the user asked to see it first.
3. Stage exactly. Use git add <paths>, or git add -p when one file holds two purposes. Run git diff --cached --stat. The staged files must match the plan.
4. Verify. Run the focused test for the staged context. If the test needs unstaged changes, say so and stage them or split differently.
5. Write the message. First read the staged diff and answer three questions: what is different for the user or caller, why was it needed, and under which condition does it apply. Write the subject from the effect and the condition. Write the body from the reason (see descriptive-messages.md). Then follow the format and the STE rules below. Run node scripts/check-message.mjs --diff-lines=<changed lines> "<message>" and fix every error and every warning you agree with.
6. Commit. Run git commit -m "<subject>" -m "<body>". Write a body for any change of 40 lines or more, a bug fix, a migration, a security fix, a revert or a breaking change.
7. Repeat from step 3 until git status shows a clean tree, or only the changes the user wants to keep.
8. Report. Run git log --oneline -n <count> and show the new commits.

Message format

<type>(<scope>): <subject>

<body, only when needed>

These seven are the base. Use perf, build, ci or revert only when the repository already uses them. How to choose a type, how to name a scope, and breaking changes: semantic-types.md.

Write the message in STE

• Subject: imperative, present tense: add, fix, remove. Not added, adds, adding.
• Effect, not object. Pick the verb that names the effect (reject, retry, cache, show, cap, stop), and add the condition when it matters. feat: add retry becomes feat(sync): retry upload up to 3 times on timeout. Use add only when you also say what it is for. The verb ladder and 12 rewrites: descriptive-messages.md.
• Length: aim for 60 characters. The hard limit is 72. No period at the end. Lowercase after the colon, unless the repository does otherwise.
• One idea. Name the thing that changed, the action and the condition. Do not list files.
• Common words, one meaning. Use remove, fix, rename, move, replace, extract and the verbs in the ladder. Avoid improve, enhance, update stuff, various, misc, minor changes.
• Body: explain why, not what. Use active voice. Use 20 words or fewer per sentence. One topic per paragraph. Wrap at 72 characters.
• Punctuation: no em dash, no en dash, no semicolon. Use a period or a colon.
• Exact names. Keep code, identifiers, commands and error text unchanged.

Full rules, a vocabulary list and before and after examples: ste-messages.md. The wider STE style is in ste-style.md, and the commit discipline is in commit.md.

Order of commits

Dependency order wins. A commit that another commit needs comes first. Otherwise use this order:

1. build or chore: a new dependency or tool that later commits use.
2. refactor: preparation that does not change behavior.
3. fix: independent corrections.
4. feat: the main change, with its tests.
5. test: tests that cover code that already exists.
6. docs: documentation.

Do not put a test before the code it tests. That commit would fail on its own.

Example

Changes: a login page, an avatar bug, a README note, and new tests for the login page.

fix(avatar): pick the source size from the device pixel ratio
feat(login): reject sign-in with an empty password   # includes its tests
docs(readme): explain how to set up the login provider

The login tests go with the login page, so the page commit passes on its own. The avatar fix and the README note do not depend on it, so they are separate.

With a body, when the reason is not obvious:

fix(avatar): pick the source size from the device pixel ratio

The image used the CSS pixel size. Retina screens showed it blurry.
Use the device pixel ratio to pick the source size.

Checked on a 2x and a 3x simulator.

Language

Write in English by default. If the repository history is in another language, write in that language and keep the type words in English. Then use polyglot-copywriter: its references/simple-prose.md for the vocabulary and grammar bar, and its language pack for the register.

Boundaries

• Do not rewrite commits that are already pushed. No force push.
• Interactive rebase is not available in this environment. For unpublished commits, and only if the user asks, use git commit --fixup <sha> and then GIT_SEQUENCE_EDITOR=true git rebase -i --autosquash <base>.
• Do not use git worktree. Work in the current checkout.
• Do not stage files the user did not mean to commit (.env, build output, secrets). Name them and stop.
• More advanced patterns: advanced.md.

Related skills

• verify: prove the gates pass before you commit.
• write-mr-description: the commits are ready and you need the MR.
• code-review: review the diff before you open the MR.
• polyglot-copywriter: polish commit wording for people.

Done when

• Every change is in a commit, or the user said to leave it.
• Each commit has one purpose and one context, and passes its own tests.
• check-message.mjs reports no errors for any message.
• The user has the list of new commits.