commit-hygiene

Files (3)

• SKILL.md
• check_commit_msg.py · scripts/
• test_check_commit_msg.sh · scripts/

SKILL.md (first lines)

# Commit Hygiene

Guidelines and constraints for writing clear, structured, and reviewer-centric git commit messages. Every commit is a unit of structured information designed to optimize human comprehension and git history utility.

## Purpose

The goal of commit hygiene is not formatting for its own sake. The goal is a **clean, human-reviewable git history**.

A well-maintained history lets a human reviewer reconstruct the reasoning behind a codebase by reading `git log`. Every commit should answer: *what changed, why it changed, and where the logical boundary of that change is.* When history achieves this, it becomes a durable decision record — not just a log of file mutations.

This requires two things working together:

1. **Good commit messages** — clear, structured, motivated (covered by the formatting and communication rules below).
2. **Commits at logical boundaries** — each commit captures one coherent unit of change with a reviewable diff (covered by the Atomicity and Boundary Discipline section below).

Neither is sufficient alone. A perfectly formatted message attached to a 40-file spaghetti diff is useless. A clean single-file diff with a message that says "update stuff" is nearly as bad. Both disciplines are required, always — not only when a formal workflow like C.O.R.E. is active.

## Hard Constraints

All commit messages MUST satisfy these structural invariants:
1. **Header Line Limit:** The summary line MUST NOT exceed **50 characters**.
2. **Body Line Limit:** No line in the body or footer may exceed **72 characters**.
3. **Blank Line Separation:** A single blank line MUST separate the header from the body.

---

## Conventional Commits Structure

Commits must conform to the Conventional Commits v1.0.0 specification:

```
<type>(<scope>)[!]: <description>

[optional body]

[optional footer(s)]
```

### Breaking Changes

A breaking change must be indicated by:
- An exclamation mark `!` suffixing the type or scope in the summary header (e.g., `feat!: remove deprecated api` or `fix(parser)!: adjust breaking parser logic`).
- A `BREAKING CHANGE: <description>` footer entry.

### Allowed Types

- `feat`: Introduction of a new capability or feature.
- `fix`: Resolution of a bug or regression.
- `docs`: Additions or modifications to documentation.
- `style`: Formatting, whitespace adjustments, or cosmetic corrections (no functional change).
- `refactor`: Structural codebase changes that neither modify behavior nor add features.
- `perf`: Optimizations that improve execution speed or resource utilization.
- `test`: Addition, restructuring, or correction of tests.
- `build`: Modifications to build configuration, dependencies, or packaging (e.g. `Cargo.toml`, `package.json`, `go.mod`).
- `ci`: Alterations to CI pipeline or automation configurations.
- `chore`: Auxiliary tasks, infrastructure tooling updates, or miscellaneous maintenance.
- `revert`: Reversion of a previous commit.
- `merge`: Integration of one branch, pull request, or workstream into another.
  (On forge-hosted projects, merges follow the [forge discipline](../forge/SKILL.md):
  consent-to-merge, self-contained PR prose, review-on-record.)

### Merge Commits

Use `merge:` for any commit whose primary purpose is integrating a branch or
pull request:

```
merge: integrate the payment-retry branch
```

The same hard constraints apply: the header must not exceed 50 characters, a
blank line must separate header from body, and body lines must not exceed 72
characters. A body is encouraged when the integration is non-trivial — what
conflict was resolved, what design decision the merge closes.

**Distinction from the recorder convention.** The `.ledger/log/` flight-log uses
`log:` subjects for its own sketch commits. `log:` is a recorder-only convention
scoped to that sub-repository and does not appear in working-repository commits.
`merge:` is a working-repository type and does not appear in the recorder.

**Auto-generated merge subjects are not valid.** Git's default `Merge branch
'foo'` and `Merge pull request #N` subjects do not carry a conventional type and
will fail the validator. Replace them with a `merge:` header that names *what*
was integrated and *why* it landed when the merge was not self-evident.

### Summary Header Formatting

- **Imperative Mood:** Use active, imperative verbs ("add", "fix", "refactor", "remove") rather than past-tense or present-participle ("added", "fixing", "refactored", "removes").
- **No Trailing Period:** The header line must not end with a period.
- **Lower Case:** The description after the colon should start with a lowercase letter (unless referencing a proper noun or acronym).

---

## Human-Centric Communication

Commits are written for human reviewers, not systems. Prioritize cognitive clarity:

### Focus on "Why" and "What"

- **The "Why":** Explain the motivation behind the change. What problem is this resolving? What context is required to understand this design decision?
- **The "What":** Describe what was changed at a conceptual level. Avoid summarizing the raw code diff (which the reviewer can already see); instead, describe the logical transition of the system.
- **Explain the Tradeoffs:** If a non-obvious design pattern or workaround was employed, document it honestly.

### Self-Contained Messages — No Contextless References

Commit messages must be **self-contained**. A reviewer reading
`git log` has access to exactly two things: the repository's
committed history and the public internet. If a reference in a
commit message cannot be resolved from one of those two sources,
it is meaningless noise.

- **No Uncommitted Artifacts:** Planning documents, sketches,
  scratch files, and workstream trackers (`.ledger/`,
  `.scratch/`, agent scratch pads, etc.) are **never committed
  to history**. Referencing labels that originate from these
  artifacts — workstream items like "(P3)", sketch IDs, plan
  phase names, task-tracker shortcodes — is **prohibited**.
  These tokens carry zero information for any reader who did
  not have the ephemeral document open. Describe the *actual

From nrdxp/predicate, MIT.

More from nrdxp/predicate