Contextual Commit Messages

Contextual Commits

You write commits that carry development reasoning in the body — the intent, decisions, constraints, and learnings that the diff alone cannot show.

The Problem You Solve

Standard commits preserve WHAT changed. The diff shows that too. What gets lost is WHY — what the user asked for, what alternatives were considered, what constraints shaped the implementation, what was learned along the way. This context evaporates when the session ends. You prevent that.

Commit Format

The subject line is a standard Conventional Commit. The body contains action lines — typed, scoped entries that capture reasoning.

type(scope): subject line (standard conventional commit)

action-type(scope): description of reasoning or context
action-type(scope): another entry

Subject Line

Follow Conventional Commits exactly. Nothing changes here:

• feat(auth): implement Google OAuth provider
• fix(payments): handle currency rounding edge case
• refactor(notifications): extract digest scheduling logic

Action Lines

Each line in the body follows: action-type(scope): description

scope is a human-readable concept label — the domain area, module, or concern. Examples: auth, payment-flow, oauth-library, session-store, api-contracts. Use whatever is meaningful in this project's vocabulary. Keep scopes consistent across commits when referring to the same concept.

Action Types

Use only the types that apply. Most commits need 1-3 action lines. Never pad with noise.

intent(scope): ...

What the user wanted to achieve and why. Captures the human's voice, not your interpretation.

• intent(auth): social login starting with Google, then GitHub and Apple
• intent(notifications): users want batch notifications instead of per-event emails
• intent(payment-flow): must support EUR and GBP alongside USD for enterprise clients

When to use: Most feature work, refactoring with a purpose, any change where the motivation isn't obvious from the subject line.

decision(scope): ...

What approach was chosen when alternatives existed. Brief reasoning.

• decision(oauth-library): passport.js over auth0-sdk for multi-provider flexibility
• decision(digest-schedule): weekly on Monday 9am, not daily — matches user research
• decision(currency-handling): per-transaction currency over account-level default

When to use: When you evaluated options. Skip for obvious choices with no real alternatives.

rejected(scope): ...

What was considered and explicitly discarded, with the reason. This is the highest-value action type — it prevents future sessions from re-proposing the same thing.

• rejected(oauth-library): auth0-sdk — locks into their session model, incompatible with redis store
• rejected(currency-handling): account-level default — too limiting for marketplace sellers
• rejected(money-library): accounting.js — lacks support for sub-unit (cents) arithmetic

When to use: Every time you or the user considered a meaningful alternative and chose not to pursue it. Always include the reason.

constraint(scope): ...

Hard limits, dependencies, or boundaries discovered during implementation that shaped the approach.

• constraint(callback-routes): must follow /api/auth/callback/:provider pattern per existing convention
• constraint(stripe-integration): currency required at PaymentIntent creation, cannot change after
• constraint(session-store): redis 24h TTL means tokens must refresh within that window

When to use: When non-obvious limitations influenced the implementation. Things the next person working here would need to know.

learned(scope): ...

Something discovered during implementation that would save time in future sessions. API quirks, undocumented behavior, performance characteristics.

• learned(passport-google): requires explicit offline_access scope for refresh tokens, undocumented in quickstart
• learned(stripe-multicurrency): presentment currency and settlement currency are different concepts
• learned(exchange-rates): Stripe handles conversion — do NOT store our own rates

When to use: "I wish I'd known this before I started" moments. Library gotchas, API surprises, non-obvious behaviors.

Before You Write the Commit

Determine the commit scope, then compose action lines:

1. Check for staged changes first — run git diff --cached --stat.
   • If staged changes exist: these are the commit scope. Do not consider unstaged or untracked files — the user has already expressed what belongs in this commit by staging it.
   • If nothing is staged: consider all unstaged modifications and untracked files as candidates. Use session context and the diff to decide what to stage and commit.
2. Identify what you have session context for — changes you produced, discussed, or observed reasoning for during this conversation.
3. Identify what you don't — files or changes from a prior session, another agent, or manual edits outside this conversation.
4. Write action lines accordingly:
   • For changes you have context for: full action lines from session knowledge.
   • For changes you don't: apply the "When You Lack Conversation Context" rules below — write only what the diff evidences.

The commit message must account for ALL changes in the commit scope, not just the ones you worked on. Ignoring changes you didn't produce is worse than writing thin action lines for them.