# Git & Commit Message Reference Guide

This document contains detailed examples and rationales for the `ai-superpower` Git commit message standards. 

## The Core Philosophy

Commit messages describe **topics and goals**, not filenames and line edits. The Git UI already perfectly documents *which* files changed and *what* code was added or removed. The commit message's job is to explain *why* the change was made and *what* the high-level business or architectural intention was.

## Formatting Rules Deep Dive
- **Subject line**: Max ~72 characters, imperative mood ("Fix", "Add", "Remove" — not "Fixed", "Added").
- **Body**: Optional. Use only when the *intent* or *why* is not obvious from the diff.
- **Never list filenames**. Do not use "CHANGES:" headers or file-by-file breakdowns.
- **Translate technical changes into a high-level topic summarization.**
- **No speculative outcomes.** No "Expected:", "Result:", or "Impact:" sections.
- **Do not describe runtime behavior, incident narrative, or manual operations** in the commit message body.
- **Do not summarize or quote the exact content of text/description changes.** The diff shows the content; the message states the topic of the change.

## ✅ / ❌ Commit Message Patterns

### High-level Topics vs. Technical Steps
- ❌ `docs/ai-context.md: add homelab k3s target, domain pattern` *(Mentions filenames, reads like a technical log)*
- ✅ `document development environment and deployment context` *(Abstracts to the goal)*

### Bullet Points State Topics, Not Implementation
- ❌ `use MC_HOST_minio env var for direct S3 auth (no mc alias set)` *(Describes the exact code change)*
- ✅ `configure direct S3 authentication for MinIO` *(Describes the architectural goal)*

### No Runtime/Status Narratives
- ❌ `gitea failed on startup` *(Describes an incident, not the repo state change)*
- ❌ `Redis services cleaned up manually` *(Describes a manual ops task)*
- ✅ `disable external redis dependency` *(Describes what the commit actually does to the code)*

### No Quoting the Text Changes
- ❌ `Remove "harmless" framing, add operational guidance: daily return to 0 expected` *(Quotes the diff directly)*
- ✅ `update operational expectations for Ghost Blocks panel` *(States the topic of the documentation update)*

### Body Length and Verbosity Example

❌ **Too detailed** — describes files, code references, and technical mechanics:
```text
chore(minio): pin image to RELEASE.2025-10-15T17-29-55Z

Chart 5.4.0 bundles RELEASE.2024-12-18 which does not return Last-Modified
metadata on objects. Thanos compactor falls back to ULID creation time and
deletes valid blocks as stale partial uploads (>48h old).

Also add comment on thanos-sidecar image noting all Thanos containers
(compactor, blocks-exporter, init container, ghost cleanup job) share
this single image reference.
```

✅ **Correct** — states the high-level intent and reasoning clearly without itemizing files or specific code additions:
```text
chore(minio): downgrade minio version to fix object metadata loss

The newer chart release causes valid block deletion by the compactor due
to missing Last-Modified metadata on objects. Version is pinned to an
older stable release to prevent data loss.

Also clarified shared image dependencies for Thanos services in documentation.
```