The end of "Just ask Sarah"

> We’ve all been in that 30-minute meeting that could just as well have been a two-paragraph ADR, if anyone would have bothered writing the decision down as it happened. Organizations learned to run on oral tradition because the alternative required discipline that was hard to reward, and not documenting it properly rarely turned into a real problem - at least not immediately. With agents, on the other hand, the full cost of a missing paper trail is paid every time the session terminates.

I just think this is entirely wrong. Oral tradition is valuable because it's flexible in a way that written tradition struggles to be. Just a handful of oral-tradition decisions I routinely see that could never be written up as persistent documentation:

* The CEO said X is our top priority, but we think Y is more important and we can do it without compromising too much on X, so we're going to do both.

* Team A has a track record of quality and success, so their decisions are subject to less review and receive more deference

* Team B is sloppy and makes a lot of bad calls, so we don't trust their judgments when doing so might lead to an outage for us.

It requires surprisingly few lines of AGENTS.md to ensure before a line of code is patched, SPEC.md has the new target and a DEVLOG.md has a journal of why, then after the code tests OK, the commit carries not only the change but the motivation, and any DOCS.md is updated with new context.

It turns out wrapping the patch with these things makes the patch better. Plus, you have docs. All this goes in the PR.

Humans think docs cost/waste time. Agents not only don't care, but code better when doing SDLC (because once you get rid of the cult ceremonies, the core principles work). And so do humans.

Maybe Sarah can write it down, and maybe so can anyone that gets an answer from her, and maybe so can the LLM.

I can’t tell from the text if the first paragraph of your response is meant to be ironic or tongue-in-cheek, but it certainly works that way.

It feels hard to recognize that you agree with me from the following paragraph of your post > This is similar to asking Sarah why the team went for A over B, but without the imperfections of human memory, and available to agents as well. When an agent reads it, the decision isn’t an arbitrary historical fact - it’s the conclusion of an argument the agent can now evaluate and extend.

I definitely agree that human knowledge is imperfect, and that documentation is needed. But I just cannot get around the fact that the following sentence, out of context, can refer to football, American football, and basketball : ‘I passed to the center, and we scored’ and without more context, each of those can have multiple meanings even in each of the sports I named.

const hello = ‘world’

Is valid in so many programming languages that need more context.

No, the agents don’t ask Sarah, but maybe they should. And maybe I’m on this soap box because the thing is that I write internal line of business software and the technical stuff is easy. But when Sarah is the inside sales manager or the industrial engineer a continent away who speaks a different language, the reality of adequately capturing context for decisions that others have made that our software has to implement, and in a context rich enough for documentation to be succinct, is enough to make me frustrated with articles like yours that hand-wave that into ‘trivial to capture in documentation.’

This - oh, so much this!