regret

You can write a regret narrative by outlining the original decision, the hindsight, and concrete changes to avoid repeating the mistake. This produces a durable Markdown file with a non-blame narrative and optional links to the original decision document.

The best way to write a non-blame architectural retrospective is to focus strictly on the decision and its outcomes rather than individual actions. This approach anchors learning to documented history and outputs a standardized file to prevent relitigating the same call across projects.

You link a new lessons-learned doc to an original decision file by including optional references within the generated Markdown. This maintains traceability and connects the hindsight narrative directly to the historical architectural context.

You should save architectural decision review files in a dedicated docs/regrets directory. The file is automatically named using a date stamp and slug convention, ensuring durable storage and easy retrieval for future project reviews.

Yes, this approach works for capturing hindsight across different projects and vendors. It applies universally when documenting lessons learned from past architecture choices, standardizing how teams capture and review learnings regardless of the original vendor context.