The Comment That Got Deleted Six Months Before The Bug Came Back

Someone joins a team, opens a file, sees a weird conditional with no explanation, and "cleans it up." Six months later the bug that condition was preventing shows up again, in production, and no one on the team remembers why the code used to check for it.

This happens because most code comments explain what the code does, and you can already see that by reading the code. The comments that actually matter, the ones that stop this exact failure, explain why: why this order, why this magic number, why this workaround exists at all. Those are the comments that go missing, because writing them takes a kind of memory most engineers don't have time to reach for mid-sprint.

That's the gap Write the Missing "Why" Comments Before You Refactor is built for. Point it at a file before a refactor, and it hunts specifically for the load-bearing weirdness: the ordering dependency, the platform quirk, the deliberate deviation from the obvious approach. It won't narrate what the code does. If nothing in the file is actually surprising, it says so instead of inventing filler.

A worked example

Say you paste a payment webhook handler that, for no obvious reason, waits 400 milliseconds before writing the transaction to the database. Read on its own, that looks like a bug. Someone new to the team would probably delete it during a cleanup pass.

Run it through the prompt and it flags exactly that line, and writes something like:

// Stripe's webhook can arrive before the charge object is fully
// queryable via the API (confirmed with their support, ref case
// #48213). The 400ms delay avoids a race where we'd fetch a
// charge that returns 404. Don't remove without checking that
// ticket first.

That's a comment someone would have had to remember to write themselves, at the exact moment they fixed the race condition, with the ticket number still fresh in their head. Most people don't do that. They fix it, ship it, move on. The prompt reconstructs the "why" from the shape of the workaround itself, in the voice of someone who was actually there.

Where the value actually is

The time saved isn't in writing comments faster. It's in the incident that never happens. A workaround with no explanation gets removed sooner or later, usually by whoever has the least context on why it's there. The cost shows up weeks or months after the refactor ships, as a support ticket, a failed payment, a customer asking why something that used to work doesn't anymore. Catching that before the refactor, instead of debugging it after, is the entire trade.

It's also a good gate to run before handing a codebase to someone new, or before you yourself forget the context you currently have. Tribal knowledge only exists in someone's head until it's written down. This prompt is a way to write it down before the person holding it moves on, gets pulled onto another project, or just forgets.

How to use it

1. Pick a file you're about to refactor, or one that's due for a cleanup pass, and paste it in along with the language.
2. Read the output against the actual code. You know the codebase better than any prompt does, so treat flagged lines as a starting point for your own memory, not a final answer.
3. Commit the comments before you touch the logic. If the refactor breaks something later, the next person gets the context you already had.

Grab the full prompt here: Write the Missing "Why" Comments Before You Refactor.