[verdverm]

just put the markdown next to the code and in git, humans should read something like this before letting a "new developer decide to migrate the billing system database" (this sounds completely fabricated by the way, and if real, you have problems most people don't)

why do I want all this extra stuff?

with markdown in the repo and agents available everywhere... what makes this approach better? (ps, the practice of coding has fundamentally changed forever, we are at the beginning of a paradigm shift, the 4th wave for any Toffler fans)

[iamalizaidi]

Thanks for the pushback — genuinely fair.

This is still just markdown in the repo. The Action doesn’t replace ADRs, it just surfaces the relevant ones automatically in PRs so reviewers don’t have to remember to look for them.

In teams where people consistently check ADRs, this probably isn’t useful.

In teams where the ADR exists but nobody remembers it during review, this helps reduce that friction.

And yeah — the Mongo example was dramatized. The real version was just re-explaining a past decision in a design doc. Not catastrophic, just wasted cycles.

Appreciate the sanity check.