Capture the decision at commit-time, or lose it forever

How many times have you faced code nobody can explain anymore? A strange architectural choice. A cache TTL of 17 minutes that nobody can justify. A worker disabled with a // don't touch — breaks everything comment that doesn't say why . You go looking. You find nothing. The person who knew has left. The commits say fix , update , wip . Or worse: you find documentation. But it contradicts itself. One page says authentication goes through OAuth. Another, written six months later, talks about JWT.