“Why did we decide this?” - recovering lost engineering context
Sooner or later every engineer inherits a system whose strangest choices have no explanation on file. Before you “fix” what looks wrong, remember Chesterton's fence: a decision you can't explain is not the same as a decision without reasons. This is a playbook for finding those reasons - and for making sure your successors never need one.
Where lost context actually hides
The reasoning is rarely in the documentation - if it were, you wouldn't be digging. It hides in the exhaust of how the work happened: commit messages and the pull request threads around them, ticket comments where the real debate occurred, the design doc's rejected alternatives section, incident postmortems (systems are shaped by their scars), and old channel discussions. Each artifact holds a fragment; the explanation is the overlap.
The archaeology playbook
- Start from the code's history, not its present. git blame on the strange part, then read the pull request that introduced it - and the one before it. The commit that added a workaround usually names the thing it worked around.
- Follow identifiers across tools. Ticket keys in commit messages, PR links in tickets, doc links in PRs. The chain of references is the closest thing to a paper trail most teams have.
- Date-box the search. Find when the choice landed, then read what else happened that quarter - the incident, the deadline, or the migration that explains it. Decisions make sense in their moment, not in yours.
- Interview while you still can. People two jobs removed will still answer “do you remember why the reporting service got its own database?” Ask for the story, not the justification - stories carry the constraints.
- Write down what you find - immediately. The tragedy of engineering archaeology is doing the dig and leaving no map. Record the recovered reasoning as a decision record, dated and marked as reconstructed, so the next person starts from your findings instead of from zero.
What the dig costs
Reconstructing one decision this way takes hours to days, produces a probably-right answer, and repeats every time someone new hits the same wall. The cost compounds quietly: settled questions get relitigated because relitigating is cheaper than digging, and systems accrete workarounds to decisions nobody understands. The dig is sometimes necessary; needing it routinely is a choice.
Preventing the next one
The durable fix is making the record a byproduct of work instead of a separate chore - capture the why at the moment of decision, in the tools where the decision happens. That practice has an honest limit: humans don't notice every decision as it happens. Rationale exists for exactly this problem - it reads the artifacts your team already produces (tickets, docs, pull request discussions), finds the decisions inside them, and maintains a connected Decision Map of what was decided, why, and what superseded it - so “why did we decide this?” becomes a lookup, not an excavation.