Write the Missing 'Why' Comments Before You Refactor

    Updated

    How to use it

    Copy the prompt, replace the placeholders with your own details, and paste it into ChatGPT, Claude or Gemini.

    Save and favourite prompts with a free account.

    Regression testing checklist: free template + AI prompts
    Read the story behind this prompt

    Regression testing checklist: free template + AI prompts

    Read the article
    Tap 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.

    Share this prompt