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.

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.

4. Audit Findings Format

### 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>
  ```