Heuristics

Retroactively Document Foundational Decisions

Authors: Andrea Magnorsky, Andrew Harmel-Law, Kenny Schwegler

Submitter: Andrew Harmel-Law

How do we handle critical, undocumented decisions made in the project's past?

Reverse-engineer Architecture Decision Records (ADRs) for foundational decisions that were never formally documented. This makes implicit constraints explicit, clarifies historical context, and allows the team to re-evaluate them. It provides a clear baseline for new team members and future decisions.

One useful approach is to conduct an EventStorming and focus on domain events that highlight important past events and decisions made. That way, modelling a timeline of relevant information that led up to certain decisions. After the EventStorming you can then write these down in ADR’s.

Example

An architect offered to write down past decisions, like why a technology was chosen, creating ADRs to fill in the project’s history. This gave clarity on original constraints, such as not having enough people at the time.

 

Tags

Follow us

Read our latest news from Virtual DDD on any of these social networks!

Recent heuristics

Discussed content

Sorry, no results found!

Whoops... we couldn't find what you're looking for