Oh man - I've created more than I can count at this point, but here's some of them:

- A chat-based web app for ad-hoc telemetry data visualization. - A firefox-extension meeting transcriber - A personal chief of staff - A web-based personal finance budgeting tool (no AI at runtime, obviously) - An iOS and Android app for solo work with a dead man switch if timely check-ins don't happen - A custom dotfile/machine config manager that works the way *I* want - A bookmarking tool/web clipper that puts together daily content-only collections from what I've been clipping and send them to my Kindle. This one I actually intended to make a SaaS, but meh. Being able to put together quite big projects by myself for myself in a reasonable amount of time is such a joy.

This - oh, so much this!

> They assume that documentation can provide enough context, and that human knowledge is not needed.

It's funny actually, because I fully agree with your reasoning. The only part were we differ is whether that's assumed, or even implied.

No documentation means running fully on tribal knowledge, or institutional knowledge if you prefer. Even if you capture your intent, imperfect and incomplete, in as little as 2 paragraphs, you'll get durable recorded memory, and intent you'll be able to reference. It does not eliminate ambiguity, but it adds framing, direction, and friction.

The examples are great, and they serve really well to prove another point that I intentionally left out: writing is not a one-shot activity. Documentation is living and should be treated as such. Unless it receives proper care continuously, it will wither and die. That could very well be the topic of a future post!

Thank you for reading and for providing thoughtful feedback!

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.’

I do agree with you both, but we need a wider view of what documentation means. I'm spending time this days reading the OpenBSD code and while the latter is really well written, I spent even more time reading the mailing list archives, the revision notes, the BSD4.4 book, some OS textbooks (Three Easy Pieces is great BTW), and various datasheets (Intel, USB,...). I would have a much easier time if I could find a dev to be my mentor and walk me through it.

All of this to say, tribal knowledge is valuable and rarely well captured. Even experts organize conferences and lectures instead of just sending each other papers. Written words is better than nothing, but knowledge is better transferred from the person that has it. If you lose that person, the only way forward is to train another one to replace it (either intentionally or not).

That feels more familiar than I'd care to admit - definitely been there, done that. I think what most fail to realize is that it eventually turns into a ball and chain, decreasing your mobility within the organization. So the consequences of running an org on tribal knowledge and Sarahs is far worse, and direct, than that it won't work very well with agents.

This might be the best article I’ve read in months. Thanks for sharing it!

Especially because it clearly showcases Garry Tan's (YC) grandeur delusions. Not only has he gone full state surveillance bullshit with Flock but also understands absolutely zero that he's vibe coding for 16 hours a day. And, shocker: it's pure slop!

thanks, glad you liked it! :)

Author here.

That sounds exhausting to say the least.

It’s very easy to turn into the Sarah - or the Brent if you prefer the Phoenix Project analogy. As exciting as it might initially be to be the go-to person, it’s also, as you so elegantly put it, “endless work, just enough authority to do current task, not enough respect/authority to solve the symptom”.

Best wishes! I hope you manage to turn it around.

Much appreciated! Thanks for the blog around ADR, I didn't know there was a full ecosystem for the approach and the AI tie in will help me sell the process

Because bug bounties are already dead.

have they though? i for one remember the "golden days" being much more about checking specific values for things you already know could happen than gathering telemetry to be able to ask questions you never would have even thought about asking at the time you set it up.

Out of curiosity, what relevance do you mean it would have for the specific topic I was writing about?

Author of the post here. I definitely agree with that assessment. Having multiple stacks monitor each other is a really good, albeit somewhat resource intensive, way to cover all of the *likely* cases. The cost of covering that last percent very quickly approaches the point of diminishing returns.

You start towards it in your post, but don't explicitly call it out: the central task is decreasing complexity.

A "dumb" heartbeat message, and a check for its absence, is reliable precisely because of its simplicity.

So if the question is "How do I monitor my complicated observability stack?" then the answer, to me, starts with "What is the simplest method of accomplishing the minimal version of my goals?"