Contextual Commits

Conventional Commits standardised WHAT changed. Contextual Commits add WHY.

A convention for embedding decision traces in git commit bodies. Every commit carries not just the code change, but the intent and reasoning that shaped it — structured as typed action lines that any tool can parse and any agent can query.

No new tools. No infrastructure. Just better commits.

Standard AI commit:

feat(auth): implement Google OAuth provider

Added GoogleAuthProvider class with passport.js integration.
Created callback route handler at /api/auth/callback/google.
Added refresh token logic with offline access scope.
Updated auth middleware to support multiple providers.

This restates what the diff already shows. Zero signal added.

Contextual commit:

feat(auth): implement Google OAuth provider

intent(auth): social login starting with Google, then GitHub and Apple
decision(oauth-library): passport.js over auth0-sdk for multi-provider flexibility
rejected(oauth-library): auth0-sdk — locks into their session model, incompatible with redis store
constraint(callback-routes): must follow /api/auth/callback/:provider pattern per existing convention
constraint(session-store): redis 24h TTL means tokens must refresh within that window
learned(passport-google): requires explicit offline_access scope for refresh tokens

The subject line tells you what. The body tells you why.

Motivation

AI coding tools are everywhere. Trust in their output isn't. The gap is context.

Every AI coding session produces three outputs:

1. Code changes — committed to git. Preserved.
2. Decisions — which approach was chosen, what was rejected, what constraints were found. Lost.
3. Understanding — deeper comprehension of how the system works and why. Lost.

Two-thirds of every session's value evaporates when the conversation window closes. Commit history is the one context source every AI coding tool can access out of the box — yet the standard AI-generated commit body restates what the diff shows. What agents can't get from the diff is why an approach was chosen, what constraints shaped it, or what was tried and rejected.

Git tracks branches, diffs, and history. The one thing it doesn't track is reasoning. The commit body has always been available for this.

The context that disappears

The agent proposes an approach you already tried and rejected last session — but the reasoning that ruled it out died with the conversation window. It writes a clean implementation that violates a constraint it has no way of knowing about, and discovers it by failing. Three months later, another session sees a pattern in the code that looks arbitrary — it wasn't, but the reason existed in a conversation that no longer exists.

Same problem, three forms. AI coding sessions prod...