Where do you write down the reasoning behind old migrations and managers?
I have been on the same Django project since 2018, and what slows me down now is that most of the non-obvious lines have a reason that lives outside the repo. Coming back to an app I have not touched in months means reconstructing that reason before I can change anything.
Data migrations are the sharpest version of this. A RunPython backfill encodes a rule about how existing rows should be interpreted, it runs once, and then it sits there as the only written record of a decision nobody remembers making. Custom managers are close behind. Someone narrowed the default manager years ago and everything that goes through objects has inherited that filter ever since without announcing itself. git blame gets me to a commit called "fix dashboard timeout" and stops.
So I have started writing two or three sentences of why into a docstring at the top of the migration instead of the PR description, on the theory that migration files are the last thing anyone deletes, squashes aside. I write them while the migration is still in front of me, in the same session as whatever assistant I have open, currently verdent, which carries memory across sessions. A decisions doc went stale inside a month. The docstring has held up better, mostly because it turns up in the diff.
Where do other people put this? A docstring on the model, a per-app notes file, the commit body, or do you just redo the archaeology every time?