git-commit-message

---
name: git-commit-message
description: 'Writing conventions for Git commit messages in slf4j-toys — content only, not staging or pushing. Use whenever composing a commit message: the Conventional Commits header format (type(scope): summary), body structure, commit types and scopes, test-coverage mention, and AI attribution trailer. For staging/push/force-push mechanics and when to commit, see `trunk-based-development`; for passing a multi-line message through PowerShell, see `powershell`.'
---

# Git Commit Message Guidelines for slf4j-toys

This skill covers only the *content* of a commit message — not how to stage, commit, or push (see `trunk-based-development`) and not PowerShell string mechanics for passing a multi-line `-m` argument (see `powershell`). A well-structured commit message lets someone reconstruct why a change was made from `git log` alone, without re-reading the diff.

## Format

Commit messages **must** follow [Conventional Commits](https://www.conventionalcommits.org/):

```
<type>(<scope>): <summary>

<detailed body explaining what changed and why>

<test coverage information>

Co-Authored-By: <Assistant Name> <Model> <contact address>
```

- **Header** — `<type>(<scope>): <summary>`, summary in imperative mood ("implement", not "implemented"). Keep it a single scannable line; there's no strict character cap enforced in this project (`type(scope):` prefixes routinely push real headers here past 70 characters), but tighten the wording if you're running long without adding meaning. See Types and Scopes below.
- **Body** — a high-level paragraph of what changed and why, then a `Changes:` bullet list of technical changes. Group related changes, include quantitative detail ("86 test cases", "4 tests updated"), name specific classes/methods for traceability. Wrap body text at 72 characters.
- **Test coverage line** — state what was actually run and its result (e.g., "All 1710 Meter tests pass, confirming backward compatibility"). Don't write this from assumption — run the relevant tier from `run-test` first.
- **Attribution** — required on every AI-generated commit; see AI attribution below.
- **Scope discipline** — one concern per commit. Split unrelated changes into separate commits rather than bundling them.

## Commit Types

| Type | When to use |
|---|---|
| `feat` | New functionality, capability, or API |
| `fix` | Fixing a defect or incorrect behavior |
| `refactor` | Restructuring code without changing behavior |
| `perf` | Optimizing performance or resource usage |
| `test` | Adding/updating tests, no production code change |
| `docs` | Documentation, comments, README |
| `style` | Formatting/whitespace, no logic change |
| `chore` | Build scripts, dependencies, tooling |
| `ci` | GitHub Actions, build pipelines, automation |
| `revert` | Undoing a previous commit |

## Scopes

Common scopes in this project: `meter`, `watcher`, `reporter`, `logger`, `test`, `build`, `ci`.

## AI attribution

Name the actual assistant and model that generated the commit in the trailer shown in Format above — not a fixed placeholder tool name. For Claude Code, that's the harness default: `Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>`. If the commit is generated by GitHub Copilot specifically, follow `.github/copilot-instructions.md`'s override instead (`Co-authored-by: GitHub Copilot using <model name>`). Apply the same convention consistently to any PR description opened for this commit (see `git-pull-request`).

## Complete example

```
feat(meter): implement idempotent termination behavior

Meter termination methods (ok, reject, fail) now properly handle repeated
termination attempts by preserving the first termination state.

Changes:
- MeterValidator.validateStopPrecondition() now returns boolean instead of void
  - Returns false when meter already stopped (blocks re-termination)
  - Returns true otherwise (allows termination with warnings)
- Meter.commonOk(), reject(), fail() methods now check validation result
  - Early return when meter already stopped, preserving first termination
- Updated 86 test cases to verify idempotent behavior
  - MeterValidatorTest: 4 tests updated to capture boolean return
  - MeterLogBugTest: 6 tests updated for exception handling

All 1710 Meter tests pass, confirming backward compatibility.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
```

## Related Documentation

- `git-pull-request` skill — PR title/description conventions for the same change
- `trunk-based-development` skill — staging, pushing, force-push rules, and when to commit
- `powershell` skill — passing multi-line commit messages through PowerShell
- [Conventional Commits Specification](https://www.conventionalcommits.org/)
- [AGENTS.md](../../../AGENTS.md) — project AI agent guidelines
- [.github/copilot-instructions.md](../../../.github/copilot-instructions.md) — AI attribution standards