Writing a workaround you can delete later

A workaround is a debt with no due date unless you write one. Five parts, all of them in the comment next to the code:

1. The mechanism, as far as you traced it. Where you stopped is part of the finding. Correct advice justified by a wrong "why" is an error, not a rounding error — the next person acts on the "why".
2. The tradeoffs you accepted, named individually. Anything you knowingly gave up.
3. An escape hatch, so that if the workaround itself fails the behaviour degrades instead of going silent.
4. The removal condition, phrased as something an outsider could check: remove once upstream does X.
5. Why your usage exposes it. Almost always the reason upstream cannot reproduce it.

Worked example