Logging Tradeoffs

Overview

A shortcut without a record is a landmine for whoever touches the code next, often future-you. This skill defines one convention, KNOWN_ISSUES.md, kept at the root of each project, so deliberate tradeoffs are findable instead of rediscovered the hard way.

Core principle: if you knowingly ship something imperfect, write down what, why, and when to revisit it, in the same motion as writing the code, not as a follow-up you'll forget.

Before creating a new entry

1. Check whether KNOWN_ISSUES.md already exists at the project root. If an equivalent file exists under a different name (TODO.md, ISSUES.md, BACKLOG.md), don't create a duplicate, ask the user whether to adopt the existing file for this convention instead.
2. If the project has graphify-out/graph.json, use the graphify-recurring-bugs skill's dedup check first, a new bug may be the same root cause as an existing open entry, not a new one.
3. Ask before creating the file if it doesn't exist yet. This is a new file the user didn't explicitly request, surface the proposed content, get a yes, then write it.

Entry format

Append one block per issue, most recent first:

## <date>, <short title>
- What changed / what shortcut was taken:
- Ceiling (when this breaks):
- Upgrade trigger (what to do when it's hit):
- Status: open | resolved (<date>, <how>)

• What changed: the concrete simplification, with a file:line reference where relevant.
• Ceiling: the specific condition under which this stops being good enough, not vague, a testable fact ("more than 10k rows", "concurrent writers", "amounts with fractional cents").
• Upgrade trigger: what to actually do when the ceiling is hit, a real next step, not "fix it properly later."
• Status: flip to resolved with a date and one line on how, when addressed. Don't delete resolved entries, they're evidence the log is actually maintained, not decoration.