zain__t

That day is now and the reason is that the documentation doesn't have to be written anymore. The conversation that led to the decision already exists — in your PR comments, Slack threads, and tickets. The reasoning is already there. It just needs to be extracted and structured automatically, not written from scratch. That's the shift that makes this viable in 2026 when it wasn't in 2020. LLMs can read the noise and surface the signal. Zero extra time from the developer.

Those comment templates are actually really well structured you've invented a mini decision record format without calling it that. The problem you're hitting is discoverability the why is there, but only if you happen to read that exact line. What if a new dev could ask 'why does this auth flow work this way?' and your comment was part of the synthesized answer along with the PR, the Slack thread, and the ticket that created it?

The Q&A doc you're maintaining is fascinating you've essentially hand-built the thing I'm trying to automate. The 'Why Kafka?' entry is exactly the kind of decision that disappears when you leave. The search problem you raised is the core of what I'm solving — not dumping commits into a .md, but extracting structured decisions from the conversation that surrounded the commit: the Slack debate, the PR review, the ticket context. Then making it queryable by the code it relates to. You said you're not sure your process scales what happens to that Q&A doc if you leave tomorrow?

This is the clearest articulation of the problem I've seen. You've basically described exactly what I'm building. The passive ingestion angle treating reasoning as a byproduct of work already being done rather than a separate documentation task is the core insight that makes this viable where ADRs failed. I'm in early development. Would you be open to a 15 min conversation? Your framing here is sharper than anything I've heard from the 20 engineers I've already talked to.

This is incredibly valuable context thank you. The career security point especially is something I hadn't fully articulated but explains why ADRs always die. Nobody wants to document themselves out of a job. The approach I'm exploring tries to remove the human writing step entirely passively capturing decisions from PRs, Slack threads, and tickets and auto drafting the rationale. The human just approves or dismisses in one click. The incentive problem flips instead of asking someone to document themselves, you're just asking them to approve something already written. Much lower friction. Curious from your 25 years on this do you think the passive capture angle addresses the incentive problem or does the resistance run deeper than just the writing effort?

Completely agree the manual capture is exactly where it breaks down every time. Curious, what's your current setup? GitHub + Slack or something different?

The git hook idea for enforcing doc updates is really interesting has that actually worked long term for your team or does it eventually get bypassed?

I am already working to automate the process