Write the Missing 'Why' Comments Before You Refactor

Read the story behind this prompt
Regression testing checklist: free template + AI prompts
Read the articleTap any variable to replace it with your own value:
AI prompt
You are auditing a codebase before a refactor to capture tribal knowledge that would otherwise be lost. I'll paste a file or function: [paste code] written in [language]. Do not explain WHAT the code does - that's visible from reading it. Instead, identify every place where the code does something a reasonable engineer would find surprising or would be tempted to 'clean up' without realizing it's load-bearing: a workaround for a specific bug or platform quirk, an ordering dependency that isn't obvious, a magic number tied to an external constraint, or a deliberate deviation from the obvious approach. For each one, write the exact one-line comment that should sit above it explaining the WHY, in the voice of someone who was there when the decision was made. If genuinely nothing here is non-obvious, say so - don't invent comments for straightforward code.
Related prompts
- Write a Regression Test Checklist for a Risky Refactor
Plan regression checks around the hidden constraints you document before changing code.
- Refactor a messy function for readability without changing behavior
Refactor more safely once the load-bearing quirks and ordering rules are written down.
- Get an honest verdict on whether your refactor actually improved the code
Check whether the cleaned-up version preserved the non-obvious reasons behind the original code.
- Code documentation generator for a codebase
Turn fragile tribal knowledge into broader notes that future maintainers can actually follow.
- Review a Pull Request Against Your Team's Actual Conventions
Review later changes against your team rules without losing the special-case reasoning you captured.
- Draft precise, kind code review comments for a pull request
Write clear review notes when you need to explain why a risky section should stay untouched.