Disclosure Is Not A Fix

Disclosure Is Not A Fix

Purpose

Writing down a known defect does not resolve it. Disclosure is a documentation act: it manages the reader's expectations but leaves the defect fully present. The trap is that a well-written caveat feels like diligence and quietly substitutes for the fix. When you're about to ship something with a "known limitation" note, the honest bar is one of two things: ship the cheapest available mitigation, OR record an explicit, reasoned decision NOT to mitigate — why, and what would change it. The disclosure itself is neither. "We disclosed it" is not a disposition.

When to use this skill

• The moment you reach for the words "known limitation", "known issue", "caveat", "we're aware", "for now", "not yet handled", or "advisory" in something you're about to ship.
• When a review, audit, or test surfaced a real defect and your instinct is to document it rather than fix it.
• When leaving a TODO/FIXME in code that is about to ship, or a "trap wanted"/"placeholder"/"not implemented" marker in a released artifact.
• Whenever an item is about to be closed on the strength of a note that describes the problem instead of resolving it.

When NOT to use

• The defect is already mitigated or already carries a written, dated decision-not-to-fix — this skill's job is done; don't re-litigate.
• Genuinely adjacent problems you were not asked to touch — those are scope-fence's flag list, not a defect in the thing you are shipping.
• Pure release notes / changelog entries that describe resolved behavior. Disclosure of a fixed thing is fine; this skill governs disclosure standing in for an unfixed thing.

The procedure

1. Name the defect and its real user-facing consequence — the unsoftened version. Not "the parser has some edge cases" but "malformed input silently produces wrong totals the user will act on."
2. Find the CHEAPEST mitigation. It is often far cheaper than the defect's cost: reword an ungradeable criterion, add a guard, put a one-line warning at the point of danger, disable the broken path, remove the live rule. Cost the mitigation against the cost of the defect biting a real user.
3. If mitigating now is viable, do it. The cheap fix beats the elegant note.
4. If not mitigating, write the explicit decision: why deferring is acceptable, who it affects, and the concrete trigger that would force the fix — dated. A deferral with no recorded reason and no re-trigger is not a decision; it's an unfixed defect wearing a caveat.
5. Put the disclosure where the defect BITES — the entrypoint, command, screen, or Quick Start where the hazard fires — not only in a distant NOTES/known-issues section the user won't reach in time.
6. Never let "we disclosed it" close the item. The item closes on a mitigation or a recorded decision. Disclosure alone leaves it open.