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