commit-message

# Commit Message Format

<scope>
These rules apply **only to git commit messages**. Do not apply line length limits, formatting
conventions, or structure requirements from this skill to other files (code, documentation, configs, etc.).
</scope>

A good commit message is a patch note read by colleagues, QA, and future you.

<mental-model>
Before writing, imagine:
- You're writing a patch note for users
- You're writing a task for QA to verify
- Someone will read this at 3am debugging production
</mental-model>

## What Makes a Good Message

<context-principle>
The best commit messages draw from three sources:

1. **The task** — what problem was being solved
2. **The implementation context** — why this approach was chosen
3. **The deliverable** — what was actually built

When all three are available, use them. The code shows WHAT exists; context reveals WHY.
When context is incomplete, describe what you can verify from the code and available information.
</context-principle>

### Factual, Not Promotional

<factual-principle>
Commit messages are **factual records**, not marketing copy.

**Subject line**: Strictly factual. Imperative mood. No judgment. Describes what was done, not how good it is.

**Body**: Can explain reasoning and trade-offs, but remains objective. Avoid promotional language.

The subject answers: "What did this commit do?"
Not: "Why is this commit amazing?"
</factual-principle>

## Structure

<format>
```
[scope] subject

body

trailers
```

**Subject**: What changed (max 72 chars, factual)
**Body**: Why it changed, how to verify
**Trailers**: Structured metadata (references, authorship)
</format>

## Subject Line

```
[scope] <verb> <description>    # with scope (monorepos)
<verb> <description>            # without scope (single-purpose repos)
```

<subject-rules>
- Max 72 characters total
- Imperative mood: "add" not "added"
- Lowercase after scope (except proper nouns)
- No period at end
- **Factual**: describe what, not how good
</subject-rules>