March 12, 2026
Commitment issues, dev edition
Contextual commits – An open standard for capturing the why in Git history
New “why” notes in code spark a fight: labels or plain English
TLDR: A developer proposes “Contextual Commits,” a simple label system to capture why code changes happen, so humans and AI can follow the reasoning. The community split fast: supporters love the structure; critics say it’s reinventing features and that clear, plain-language notes tied to business goals work better.
Software engineer Veselin Dimitrov wants every code change to include the why, not just the what. His idea, “Contextual Commits,” adds simple labels—like intent, decision, rejected, constraint, learned—right inside a commit message (the little note you write when you save your work in Git, a code history tool). The goal: help future you—and AI coding assistants—understand your thinking without digging through docs. Bold idea, right? The comments promptly turned into a family dinner debate.
One camp rolled their eyes: just write paragraphs. As teeray put it, why not explain it “like a human” in the message body? agateau echoed the same: does this beat clear, human-friendly text? Another faction argued this is reinventing the wheel. keybored pointed out Git already supports “trailers” (those metadata lines at the bottom of a message) and quipped that AI-era coding keeps reinventing coding.
Then came the product-minded critique: stephbook said “intent” like “users need social login” misses the real goal—lowering barriers to sign up to grow users—hinting that context should link to business outcomes, not just technical choices. Meanwhile, fans like evolve2k cheered the structure and shared a pro tip: drop links to the blogs, bug reports, and comparisons that influenced your choice.
The vibe? Half the room wants a tidy label system, half says write like a human—and everyone agrees your future teammates (and AI coworkers) need a breadcrumb trail.
Key Points
- •Veselin Dimitrov proposes “Contextual Commits,” a convention to record the reasoning behind changes in Git commit bodies.
- •The approach builds on Conventional Commits, adding structured tags (e.g., intent, decision, rejected, constraint, learned).
- •He tested extensive prompting and automation (Claude hooks, Git hooks, MCP tools, skills) but found forced capture reduced quality.
- •Insight: treat branches as sessions and commit history as progression; the commit body is the place to store evolving context.
- •He reports positive results using a simple agent skill to follow the specification when committing, improving context retention.