retroactively - create Lightweight Architecture Decision Records (ADRs) by reconstructing key decisions from the available sources, then make it a habit to maintain them for all future changes.
The easiest is to add short info in comments, and longer info in some sort of document and reference the doc in comments.
Lightweight ADRs are a good recommendation. I've put similar practices into place with teams I've worked with. Though I prefer to use the term "Technical Memo", of which some contain Architectural Decisions. Retroactive documentation is a little misaligned with the term ADR, in that it isn't really making any sort of decision. I've found the term ADR sometimes makes some team members hesitant to record the information because of that kind of misalignment.
As for retroactively discovering why, code archeology skills in the form of git blame and log, and general search skills are very helpful.
Mitchell Hashimoto (2025-12-30):
"Slop drives me crazy and it feels like 95+% of bug reports, but man, AI code analysis is getting really good. There are users out there reporting bugs that don't know ANYTHING about our stack, but are great AI drivers and producing some high quality issue reports.
This person (linked below) was experiencing Ghostty crashes and took it upon themselves to use AI to write a python script that can decode our crash files, match them up with our dsym files, and analyze the codebase for attempting to find the root cause, and extracted that into an Agent Skill.
They then came into Discord, warned us they don't know Zig at all, don't know macOS dev at all, don't know terminals at all, and that they used AI, but that they thought critically about the issues and believed they were real and asked if we'd accept them. I took a look at one, was impressed, and said send them all.
This fixed 4 real crashing cases that I was able to manually verify and write a fix for from someone who -- on paper -- had no fucking clue what they were talking about. And yet, they drove an AI with expert skill.
I want to call out that in addition to driving AI with expert skill, they navigated the terrain with expert skill as well. They didn't just toss slop up on our repo. They came to Discord as a human, reached out as a human, and talked to other humans about what they've done. They were careful and thoughtful about the process.
Apart from the external person turning out having experience with zig and macos (but not on developing terminals and rendering stuff), this is a good imo example of what ai can be used well for: writing one-off code/tools for which it is enough that it is just working (even if not perfectly), but one does not really care about maintaining, because it is meant to be used only on a specific occasion/context. In this case, the external person was smart enough to use AI to identify the problems and not to produce "fixes" to send as a PR.
Imo, an issue is that the majority of people who submit AI slop as PRs have different motivations than this person (developing a PR portfolio whatever that may mean), or are much less competent and eager to do actual work themselves (which AI use can worsen).
"Between the late hours of January 2 and the early morning of January 3, 2026, unusually high activity was again observed at a Papa John's near the Pentagon. This coincided with the lead-up to the United States strikes in Venezuela.[15][16] Following the strikes, President Donald Trump announced the capture of Nicolás Maduro, and his wife, Cilia Flores, who were subsequently flown out of the country to face narcoterrorism charges. The surge in pizza orders preceded the official confirmation of the operation by several hours, during which Venezuelan Vice President Delcy Rodríguez reported the couple as missing.[17]"
+
"In a statement to Newsweek in 2025, the Department of Defense denied the theory, claiming that the Pentagon has numerous internal food vendors that are available to late-night workers. It criticized the accuracy of the timeline provided by the Pentagon Pizza Report.[18][19]"
What about the other thousands of surges in pizza orders that had nothing to do with military missions abroad?
That's why Wikipedia calls it an "informal observation" and quotes the "potential for confirmation bias", asking "When else do spikes occur? How often do they have absolutely nothing to do with geopolitics?"
> "For me personally, I have decided I will never be an Anthropic customer, because I refuse to do business with a company that takes its customers for granted."
The best pressure on companies comes from viable alternatives, not from boycotts that leave you without tools altogether.
reply