James Coleman
46d47f9047
- Require scoped Conventional Commit headers and semantic bodies that explain behavior and compatibility changes. - Allow known changes or sufficient summaries to replace redundant worktree and staged diff reviews.
109 lines
4.3 KiB
Markdown
109 lines
4.3 KiB
Markdown
---
|
|
name: git-commit
|
|
description: Use whenever preparing, reviewing, amending, rewording, or executing a git commit. Enforces Conventional Commits with a scoped header and a semantic diff-backed body.
|
|
---
|
|
|
|
# Git commit message protocol
|
|
|
|
Use this skill before staging files or drafting a commit message. Override the
|
|
default preference for brief commit messages. The message must explain the
|
|
change well enough to understand the commit without opening its diff.
|
|
|
|
## Inspect before staging
|
|
|
|
Always run the following before `git add`:
|
|
|
|
```sh
|
|
git status --short --branch
|
|
git diff --check
|
|
git log --oneline -10
|
|
```
|
|
|
|
If the current context does not already describe every worktree change well
|
|
enough to prepare the commit, also run `git diff --stat` and `git diff`.
|
|
`git diff` does not include untracked files, so read every untracked path shown
|
|
by `git status`. A summary may substitute for the actual changes when it
|
|
provides enough context to prepare the commit. Do not re-read changes that are
|
|
already known from the current context.
|
|
|
|
Treat this inspection as a semantic diff check. Identify:
|
|
|
|
- The user-visible or operational behavior that changed.
|
|
- The reason the old behavior was unsafe, incorrect, or insufficient.
|
|
- The formats, protocols, persistent data, or external interfaces affected.
|
|
- Tests and compatibility handling that define the new contract.
|
|
- Unrelated changes that require a separate commit, unless the user explicitly
|
|
requests one commit containing everything.
|
|
|
|
Do not stage until this check is complete. Never infer the commit body from
|
|
the task description alone.
|
|
|
|
## Message structure
|
|
|
|
Use this exact shape:
|
|
|
|
```text
|
|
<type>(<scope>): <imperative description>
|
|
|
|
- <why this change is needed and what behavior now differs>
|
|
- <another concrete behavior, contract, or compatibility detail>
|
|
```
|
|
|
|
The header is mandatory and follows Conventional Commits:
|
|
|
|
- `type` is one of `feat`, `fix`, `refactor`, `perf`, `test`, `docs`, `build`,
|
|
`ci`, `chore`, or `revert`.
|
|
- `scope` is mandatory. Use the narrowest stable subsystem that describes the
|
|
whole commit, such as `mirror`, `server`, `config`, or `release`. Use a
|
|
project-level scope only when no subsystem is honest.
|
|
- The description uses imperative mood, starts lowercase, has no trailing
|
|
period, and names the behavior rather than the files.
|
|
- Keep the header at 72 characters or fewer when practical. Never make it
|
|
vague to satisfy the limit.
|
|
|
|
The body is mandatory:
|
|
|
|
- Insert one blank line after the header.
|
|
- Use `- ` bullets.
|
|
- State WHY the change exists and WHAT behavior or contract changed.
|
|
- Name affected repository formats, protocols, configuration keys, failure
|
|
modes, or persisted state when they matter.
|
|
- Do not narrate implementation steps or list filenames.
|
|
- Do not add a generic test-results bullet. Include tests only when a fixture,
|
|
regression, or external compatibility case defines the behavior.
|
|
- Avoid vague text such as "update files", "fix bugs", "improve handling",
|
|
or "add support" without naming the exact support.
|
|
|
|
Use a `BREAKING CHANGE:` footer when the commit breaks a public contract. Add
|
|
issue footers only when an issue or ticket is known.
|
|
|
|
## Verify after staging
|
|
|
|
After staging, always run:
|
|
|
|
```sh
|
|
git status --short
|
|
git diff --cached --check
|
|
```
|
|
|
|
If the current context does not already describe the staged changes well
|
|
enough to verify the commit message, also run `git diff --cached --stat` and
|
|
`git diff --cached`.
|
|
|
|
Confirm that the staged semantic diff matches every claim in the message and
|
|
that every significant staged behavior appears in the body. Rewrite the
|
|
message when the staged diff and draft disagree.
|
|
|
|
Before committing, check recent history for repository-specific scope and
|
|
wording conventions. Repository convention may refine type or scope names,
|
|
but it does not remove the scoped header or body requirements in this skill.
|
|
|
|
## Example
|
|
|
|
```text
|
|
feat(mirror): verify repository OpenPGP signatures
|
|
|
|
- Reject RPM, Debian, and Arch metadata that fails the configured signature policy before its checksums or package paths are trusted.
|
|
- Preserve the last verified repository generation when signatures rotate inconsistently or required package files remain unavailable.
|
|
- Allow operators to pin signer keyrings or retrieve unknown issuers from configured keyservers, including archived GnuPG v1 RSA signatures.
|
|
```
|