Codebase Reverse Engineering

Why source-first, not docs-first

READMEs and comments drift from what the code actually does the moment someone fixes a bug without updating them. Treat the code, its tests, its error-handling paths, and — where available — production logs and past incident reports as the ground truth. Documentation is a useful pointer to where to look, never evidence of what happens.

This matters most for the parts that are easy to skip past: behavior that lives in middleware rather than handlers, constraints enforced by a database index with no comment explaining why, edge cases that only show up in an error-handling branch nobody documented. These are exactly the things that get silently lost when someone works from memory or from docs instead of from source.

What to extract

Work through each area and write it into the matching doc as you go — don't try to hold it all in your head until the end.