contextual-commit

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.