Disclosure Is Not A Fix
Skill2 starsChanged 4 months agoMITView on GitHub
Writing down a known defect does not resolve it. Activate when about to ship something with a "known limitation", "known issue", "caveat", "disclosed", "we're aware", "for now", "not yet handled", or "advisory" note; a TODO/FIXME left in shipped code; a review that found a defect you are documenting instead of fixing; or shipping with a noted-but-unfixed problem. Trigger signal: a well-written caveat is standing in for a mitigation. The honest bar - ship the cheapest mitigation, or record an explicit dated decision not to; disclosure is documentation, not resolution.
In this repository38 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- Adversarial VerifySkill
- Change ControlSkill
- Code ReconnaissanceSkill
- Correction PropagationSkill
- Debugging PlaybookSkill
- Deep DecompositionSkill
- Delegation DisciplineSkill
- Discovery LoopSkill
- Divergent IdeationSkill
- Effort CalibrationSkill
- Empirical ValidationSkill
- Error RecoverySkill
- Extract ApproachSkill
- Failure Mode AwarenessSkill
- ForesightSkill
- Frontier Workflow ModeSkill
- Human HandoffSkill
- Intent ClaritySkill
- Leverage FirstSkill
- Live State TruthSkill
- Memory HygieneSkill
- Open MandateSkill
- Output StructuringSkill
- Plan GateSkill
- Proactive RigorSkill
- Product ThinkingSkill
- Prompt EngineeringSkill
- Publish HygieneSkill
- Research MethodologySkill
- Ruthless EditorSkill
- Scope FenceSkill
- Security Pattern ReviewSkill
- Self-Improvement LoopSkill
- Session OrientationSkill
- Structured ReasoningSkill
- Verification DisciplineSkill
The file
We split this skill into the rules it gives an agent
4 rules. About 0 are common, 3 are distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 15
When a review, audit, or test surfaced a real defect and your instinct is to document it rather than fix it.
- Very specific: line 16
When leaving a TODO/FIXME in code that is about to ship, or a "trap wanted"/"placeholder"/"not implemented" marker in a released artifact.
- Distinctive: line 36
No shipped known-defect without either a mitigation or a written, dated decision-not-to-fix.
- Distinctive: line 39
If deferred: the note names who it affects and the trigger that reopens it.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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/FIXMEin 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
- 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."
- 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.
- If mitigating now is viable, do it. The cheap fix beats the elegant note.
- 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.
- 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.
- Never let "we disclosed it" close the item. The item closes on a mitigation or a recorded decision. Disclosure alone leaves it open.
Quality bar
- No shipped known-defect without either a mitigation or a written, dated decision-not-to-fix.
- The warning sits where the hazard is triggered, not only in a file the endangered user never opens in time.
- The cheapest mitigation was actually considered and costed against the defect — not skipped on the way to writing the caveat.
- If deferred: the note names who it affects and the trigger that reopens it.
Common failure modes
- Disclosure-as-absolution: a caveat in the README while the broken thing ships unchanged. The reader is warned; the defect is untouched.
- Warning in the wrong place: a root NOTES/known-issues entry while the dangerous Quick Start has no banner. The people who hit the hazard never saw the note.
- "We found one instance": documenting a single occurrence without sweeping the class — the same defect lives in the two rubrics/files you didn't check.
- Silent deferral: pushing the fix to "later" with no recorded reason and no re-trigger, so nothing ever reopens it.
- Disclosed-but-live: leaving a proven-ungradeable criterion or a broken rule active because it was disclosed — every user now reproduces the known noise you already knew about.
Works with sibling skills
scope-fencedefers adjacent issues you were not asked to fix; this skill governs a defect in the thing you ARE shipping — mitigate-or-decide, don't just note.failure-mode-awarenessidentifies risks at design time; this skill governs the disposition of a known one at ship time.adversarial-verifysurfaces the defect in finished work; this skill decides what shipping it honestly requires once it's surfaced.
Provenance and maintenance
Added 2026-07-09 after an audit found three instances of disclosure substituting for a fix: a public eval tool shipping a grading criterion its own study had proven ungradeable — disclosed in the study doc, but the criterion still live in two rubrics, so every user reproduced the known noise; a taxonomy repo whose entries said "trap wanted" for traps a sibling repo had already published; and an abandoned bot whose dangerous Quick Start had no do-not-run banner despite a root verdict condemning it. Re-verify: on the next "known limitation" you write, check whether a cheaper mitigation existed and whether the item was closed on disclosure alone.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

