Skip to content
Nerdy beta

Risk-Aware Commit Notation

Add to Space
 Engineering AI

A log full of "fix stuff" and "WIP" makes every reviewer re-derive what the author already knew. Risk-Aware Commit Notation packs that knowledge into the first three characters of the commit summary, so history reads at a glance.

Overview

Arlo Belshee’s notation prefixes every commit summary with a risk marker and an intent letter: <risk> <intent> <summary>. Two characters answer the two questions a reviewer asks of every commit: how dangerous is this, and what was it trying to do?

MarkerRiskWhat the author attests
.Proven safeA tool made the change, or it cannot reach users
^ValidatedTests cover the change and the surrounding behavior
!RiskyIt works, but known risks stay unverified
@BrokenNo attestation. A savepoint.
LetterIntentBehaviors changed
FFeatureExtends one behavior
BBugfixRepairs one behavior
rRefactoringZero. Implementation only
dDocumentationZero. Communicates to the team

Casing carries the meaning: uppercase intends to change exactly one behavior, lowercase intends zero. That is why refactorings and documentation ship lowercase, and why a log reads as a risk profile:

. r Rename PriceQuote to Quote (IDE rename)
^ B Reject empty email addresses on signup
! F Add the contact CTA to the workshop pages
@ F Savepoint: checkout flow half-wired

The reviewer skims the . and ^ lines and spends their attention on the !. M. Scott Ford calls the safe end of the scale “provable commits”: a . r provably changes nothing, so even a change review board can wave it through. And because the prefix is only honest when the commit does one thing, the notation forces small commits as a side effect. Review effort finally lands where the risk lives.

That property compounds with agents. An agent that must attest risk on every commit is pushed into small, provable steps, the discipline worth encoding as Engineering Skills. Each intent letter is also a payment against intent debt: the reasoning travels with the change instead of evaporating when the session ends. We run the notation on the repo behind this site, with a hook that rejects any commit whose summary lacks a valid prefix. This page landed as ! F Add the Risk-Aware Commit Notation tool page. The hook checks structure, not honesty. Honesty stays with the author, human or not.

Resources