# Logging Tradeoffs

Use when a deliberate shortcut is taken during a fix or feature, when investigating a...

- Repository: https://github.com/ccplugins/awesome-claude-code-plugins (991 stars)
- Category: Engineering
- License: Apache-2.0
- Last updated: 2026-08-12
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add ccplugins/awesome-claude-code-plugins --skill logging-tradeoffs -g -a claude-code -y`
Codex: `npx skills add ccplugins/awesome-claude-code-plugins --skill logging-tradeoffs -g -a codex -y`
Cursor: `npx skills add ccplugins/awesome-claude-code-plugins --skill logging-tradeoffs -g -a cursor -y`
Gemini CLI: `npx skills add ccplugins/awesome-claude-code-plugins --skill logging-tradeoffs -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add ccplugins/awesome-claude-code-plugins`

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

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

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

The rest: https://github.com/ccplugins/awesome-claude-code-plugins/blob/HEAD/plugins/craftsman/skills/logging-tradeoffs/SKILL.md