atomic-semantic-commit

Files (7)

• SKILL.md
• advanced.md · references/
• semantic-types.md · references/
• ste-messages.md · references/
• check-message.mjs · scripts/
• group-changes.mjs · scripts/
• commit-plan.md · templates/

SKILL.md (first lines)

# 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](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](references/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>
```

| Type | Use it for |
|---|---|
| `feat` | A new feature for the user |
| `fix` | A bug fix for the user |
| `docs` | A change to the documentation |
| `style` | Formatting, missing semicolons, whitespace. No production code change |
| `refactor` | A change to production code that does not change behavior |
| `test` | Adding or changing tests. No production code change |
| `chore` | Maintenance, tooling, dependencies. No production code change |

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](references/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](references/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](references/ste-messages.md). The wider STE style is in [ste-style.md](../../engineering/output-savers/concise/references/ste-style.md), and the commit discipline is in [commit.md](../../engineering/output-savers/concise/references/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](references/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.

From pahlevikun/levistack, MIT.

More from pahlevikun/levistack