charles forson

A markdown note is not a commitment tracker

3 min read

Every autonomous session I run eventually says some version of the same sentence: here's a decision only you can make, here's an account I need you to create, here's a call I need you to have. For a long time, that sentence just sat at the end of a session transcript, and the actual obligation evaporated the moment the session closed. Nobody was tracking whether I'd ever gone back and done the thing the agent said it needed from me.

The instinct is to fix this with a note. Write the commitment to a markdown file, review the file periodically. I tried that, and it failed for a reason that should have been obvious sooner: a passive file only works if someone actually opens it on a schedule, and "someone should check this" is precisely the kind of convention that degrades under the same seventy percent adherence problem every other unenforced rule in this system runs into. A markdown note is a wish that someone remembers to look, not a commitment tracker.

The fix needed two separate things that I'd been conflating into one: a real tracker somewhere I actually see on my phone, not buried in a repo I only open at a desk, and a deterministic gate that refuses to let work merge without declaring its commitment linkage explicitly. Neither one alone solves it. The tracker without the gate is just a nicer markdown file, still relying on someone remembering to write to it honestly. The gate without a real tracker just enforces that a box got filled in, with no guarantee the thing inside it ever gets followed up.

So every unit of work now carries a small, structured block: what existing obligation this work advanced, what new obligation it created, and if it created nothing, an explicit statement of why not. A pull request without that block, unless it's pure automated output that carries no approval gate to begin with, simply cannot merge. Before this existed, "I'll remember to follow up" was doing a huge amount of unacknowledged load-bearing work in how this whole system stayed honest, and it was carrying weight it was never built for.

The part I underestimated going in was what happens when the real-time system genuinely can't be reached. Any dependency wired into an unattended pipeline eventually has an outage, and a gate that just fails hard the moment that dependency is down turns "the tracker is briefly unreachable" into "work silently stops getting done," which is a worse failure than the one I was trying to fix. The answer was an explicit fallback state: if the real tracker genuinely can't be reached after a reasonable retry, declare the obligation in that state rather than dropping it, and build a separate reconciliation pass that sweeps up anything left in that state and files it properly the next time it runs. Degrade visibly, never silently. That single design principle, borrowed from every reliability lesson I've relearned the hard way over the years, turned out to matter more here than the tracker choice itself.

What actually convinces me this works isn't the gate blocking a merge, which is the easy, satisfying part to watch happen. It's the reconciliation pass running quietly every morning, checking whether any commitment has gone stale, ageing anything that's sat open too long, and surfacing only the small number that genuinely need my judgement into one short morning list instead of scattering them across dozens of session transcripts I'd never think to reopen. The gate stops the obligation from being lost at the moment of creation. The reconciliation pass stops it from being lost afterwards, quietly, the way most good intentions actually die: not in one dramatic failure, but in the gap between when something was said and whenever, if ever, someone thought to check back.

Building the same things I write about — see what I'm working on in Projects, or get in touch.