git-commit-quality

# Git Commit Quality Standards ## Core Philosophy > **A Git commit message records the state change and its essential architectural rationale, not a development diary, proof-of-work ledger, or debugging scratchpad.** Default to a subject-only commit. Add a body only when the diff cannot convey a non-obvious invariant, business logic constraint, compatibility requirement, or issue reference. --- ## 1. Commit Format & Constraints - **Subject line:** - Imperative mood, present tense (`Add`, `Fix`, `Update`, `Refactor`, `Remove`), never `Added`, `Fixes`, or `Updating`. - Under 50 characters (hard ceiling: 72 characters). - Capitalize first letter; no trailing period. - No conventional commit prefixes (`feat:`, `fix:`, `chore:`) unless repository conventions require them. - **Subject-only default:** If the diff and subject make the change evident, omit the body entirely. - **Body:** - Separate from subject with a single blank line. - 1 to 4 lines maximum, hard-wrapped at 72 characters. - Focus strictly on *why* (non-obvious invariants, constraints, upstream quirks). - Include issue-closing trailers when applicable (`Fixes #123`). - **Granularity:** Split unrelated changes into distinct commits rather than writing a multi-paragraph body explaining multiple unrelated edits. --- ## 2. Commit Anti-Patterns ### 1. The Development & Debugging Diary - **Anti-Pattern:** Narrating the debugging journey, transient investigation findings, local benchmarks, or test run outputs (*"verified today on live instance"*, *"dummy DB had 76 orphaned rows"*, *"typed from live response"*). - ❌ ```text Fix deleteThing endpoint after testing deleteThing wraps /ajax/thing/delete/, verified today: it destroys the pool row, so every level sharing it loses the row, and a repeat call answers 404. Ran go test -race ./... locally and it passed in 1.2s. ``` - ✅ ```text Fix deleteThing endpoint wrapper Permanently deletes the shared pool record via /ajax/thing/delete/. ``` ### 2. Request Accounting & Internal Plumbing Bloat - **Anti-Pattern:** Explaining internal request counts, step-by-step pipeline routing, or unobservable backend minutiae. - ❌ ```text Cut the requests an item edit costs A named single-cell edit was four requests on a cold client. Passing poolId skips the lookup that finds the thing's pool, and verify: false drops the read-back, so the floor is now one request; a warm client pays two. ``` - ✅ ```text Optimize item edit request overhead Add poolId and verify options to bypass pool lookup and verification read-backs when updating items. ``` ### 3. Defensive Post-Mortems & Apologies - **Anti-Pattern:** Explaining why the author or model made an earlier mistake, hallucinated an API, or misunderstood existing code. - ❌ ```text Fix route handling in auth middleware My mistake on the earlier commit: I assumed Express stripped trailing slashes automatically like Actix does, which broke the callback URL. ``` - ✅ ```text Normalize trailing slashes in auth callback route ``` ### 4. Ghost Commentary & Tombstones - **Anti-Pattern:** Explaining what code used to do, why old deprecated functions were removed, or how the new approach differs from historical drafts. - ❌ ```text Update session store We no longer use Redis for session storage because memory costs were too high and DynamoDB provides TTL natively without custom maintenance jobs. ``` - ✅ ```text Migrate session store from Redis to DynamoDB Relies on native DynamoDB TTL for automatic session expiration. ``` ### 5. Absence Commentary & Omission Lists - **Anti-Pattern:** Listing hypothetical features or cleanup tasks deliberately not done (*"Did not touch older models...", "Left open for later..."*). - ❌ ```text Add user avatar upload Supports JPEG and PNG. I did not add WebP conversion or S3 upload logic because that should be handled in a background worker later. ``` - ✅ ```text Add JPEG and PNG user avatar upload ``` ### 6. AI Attribution & Watermarks - **Anti-Pattern:** Appending `Co-authored-by: Claude <...>`, `Signed-off-by` AI bots, or `_Generated by..._` trailers. - ❌ ```text Update database migration scripts Co-authored-by: Claude <noreply@anthropic.com> ``` - ✅ ```text Update database migration scripts ``` ### 7. Rule Compliance & Meta-Reporting - **Anti-Pattern:** Referencing instructions, linters, or skill compliance in commit text (*"Fix lint errors and remove all em dashes per guidelines"*). - ❌ ```text Clean up comments per skill guidelines ``` - ✅ ```text Remove obsolete comments and normalize docstring formatting ``` --- ## 3. Style, Punctuation & Precision - **Zero conversational dashes:** Never use em dashes (`—`), en dashes (`–`), or double hyphens (`--`) as conversational pauses. Use commas, colons, parentheses, or separate sentences. - **No hype or synthetic fillers:** Cut *crucial, seamless, robust, game-changer, pivotal, unlock*. - **No staged rhetoric:** Do not use throat-clearing, theatrical openings, rhetorical questions, defensive rebuttals, generic positive endings, punchy fragments, or antithesis to create emphasis. - **Preserve exact literals & uncertainty:** Keep exact identifiers, issue numbers, configuration flags, commands, and error codes. Do not turn conditional possibilities (*"may prevent timeout under load"*) into universal guarantees (*"guarantees zero timeouts"*). - **Keep formatting plain:** Avoid decorative formatting, emojis, and forced lists. Each sentence must state a concrete change, durable constraint, or issue reference. Rewrite the whole subject or body around its essential fact. Do not replace individual AI-sounding words while retaining the same padded structure. --- ## 4. Audit Findings Format When reviewing or auditing existing commit history, report findings in this structure: ````markdown ### Commit `<commit-sha>`: `<Subject line>` - **Original:** ```text <Exact original subject and body> ``` - **Anti-Pattern:** `<Name of violated anti-pattern(s)>` - **Issue:** `<1-sentence explanation of why it is low-signal or padded>` - **Replacement:** ```text <Clean proposed subject line> <Clean proposed body wrapped at 72 chars, or omit if subject-only> ``` ````