Logging Tradeoffs

---
name: logging-tradeoffs
description: 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.
---

# 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.

## 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.