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
- 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.
- 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.
- 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.
When touching a file with an open entry
If reviewer or coder touches a file referenced by an open KNOWN_ISSUES.md entry, say
explicitly whether the current change resolves that entry, is unrelated to it, or makes it worse.
Silence here is how the same shortcut gets shipped around three times.
1---2name: logging-tradeoffs3description: Use when a deliberate shortcut is taken during a fix or feature, when investigating a bug that might already be logged, or when closing out an entry after a proper fix lands.4---56# Logging Tradeoffs78## Overview910A shortcut without a record is a landmine for whoever touches the code next — often future-you.11This skill defines one convention, `KNOWN_ISSUES.md`, kept at the root of each project, so12deliberate tradeoffs are findable instead of rediscovered the hard way.1314**Core principle:** if you knowingly ship something imperfect, write down what, why, and when to15revisit it — in the same motion as writing the code, not as a follow-up you'll forget.1617## Before creating a new entry18191. Check whether `KNOWN_ISSUES.md` already exists at the project root. If an equivalent file20 exists under a different name (`TODO.md`, `ISSUES.md`, `BACKLOG.md`), don't create a duplicate21 — ask the user whether to adopt the existing file for this convention instead.222. If the project has `graphify-out/graph.json`, use the `graphify-recurring-bugs` skill's dedup23 check first — a new bug may be the same root cause as an existing open entry, not a new one.243. **Ask before creating the file** if it doesn't exist yet. This is a new file the user didn't25 explicitly request — surface the proposed content, get a yes, then write it.2627## Entry format2829Append one block per issue, most recent first:3031```32## <date> — <short title>33- What changed / what shortcut was taken:34- Ceiling (when this breaks):35- Upgrade trigger (what to do when it's hit):36- Status: open | resolved (<date>, <how>)37```3839- **What changed**: the concrete simplification, with a `file:line` reference where relevant.40- **Ceiling**: the specific condition under which this stops being good enough — not vague, a41 testable fact ("more than 10k rows", "concurrent writers", "amounts with fractional cents").42- **Upgrade trigger**: what to actually do when the ceiling is hit — a real next step, not "fix43 it properly later."44- **Status**: flip to `resolved` with a date and one line on how, when addressed. Don't delete45 resolved entries — they're evidence the log is actually maintained, not decoration.4647## When touching a file with an open entry4849If `reviewer` or `coder` touches a file referenced by an open `KNOWN_ISSUES.md` entry, say50explicitly whether the current change resolves that entry, is unrelated to it, or makes it worse.51Silence here is how the same shortcut gets shipped around three times.
ccplugins