bugs

Files (1)

• SKILL.md

SKILL.md (first lines)

# Bugs

`BUGS.md` at the project root holds exactly three things:

1. **What is open** — defects still true of the code, and the decisions the
   owner still owes (a redesign, a deliberate limit, a licence or product call).
2. **Things that were reported as defects and are not** — so the next audit
   does not re-report them.
3. **Long-term technical debt** — a structural cost the owner accepts for
   now, awaiting no decision (§ Long-term technical debt).

Nothing else. It is NOT a log of audits, reviews, sessions or sweeps: no
"Status — <date> — <what I checked>" blocks, no lead paragraphs describing a
review pass, no counts of what was verified. That narrative belongs in
the diary. A reader opens `BUGS.md` to learn what is broken, not what someone
did.

(Filename is uppercase `BUGS.md`. Some projects use lowercase — match what the
project already has.)

## Bug Triage Protocol — record, don't fix

WISDOM § Bug triage owns it: a bug found during any check is recorded here
and fixed only when the user asks.

## When NOT to record

- NEVER record when the user is currently driving a fix — just fix
- NEVER record trivial / one-shot issues a code comment covers
- NEVER record feature requests — those go in `TODO.md` or a new spec
- NEVER duplicate — when an open entry covers the same root cause, append
  context to it instead
- NEVER record what you did. An entry describes the defect, not the pass that
  found it. Provenance is at most one clause inside the entry (`CONFIRMED at
  HEAD <date>`), never a section.
- NEVER footnote a different repo's defect here — fix it, or file it
  (`/gh-issue`), at the repo that owns it

## Structure

Group by **subject** — the component or surface the defects live in — not by
when they were found:

```markdown
## Code bugs (in source/SQL, not the tests)
## Coverage gaps (edge cases / untested branches)
## <component or subsystem>
```

An existing section that fits takes the entry; only add a section when no
current one covers the subject. A defect dated in its own entry is enough —
the file needs no dated scaffolding around it.

## Entry format

One **bullet** per bug: bold UPPERCASE-KEBAB id, a `(SEVERITY, type)` tag, an
em-dash, then the body. An existing `BUGS.md` in another shape keeps it: ALWAYS
add entries in the file's own format, NEVER convert it, and NEVER ask to.

```markdown
- **COMPONENT-SHORT-NAME** (SEVERITY, type) — <what's broken>, at `file:line`;
  <why / failure mode>. **Fix:** <sketch>.
```

- **ID** — `COMPONENT-DESCRIPTIVE-NAME`, UPPERCASE-KEBAB, component-prefixed
  and self-describing (`ME-SNAPSHOT-NO-INDEX-DEDUP-REBUILD`,
  `GW-OUTBOUND-UNBOUNDED`), not a short opaque code.
- **SEVERITY** — `CRITICAL | HIGH | MED | LOW` (or `MED-HIGH`).
- **type** — one word for the class: `latency`, `correctness`, `docs`,
  `design`, `duplication`, `perf`, `ops`, `config`, `resource/DoS`,
  `hardening`, `traceability`.
- **body** — concrete `file:line` cites, the failure/why, and often a
  **Fix:** sketch. Multi-line prose is fine for a hard one.
- **test** — cites the failing test that proves it:
  `Measured: <file>::<test-name>`. Omit only for a carve-out type (see below).
- **status** — inline, as a clause: `CONFIRMED at HEAD <date>`,
  `open (record only)`, `deferred — <why>`, `needs sign-off`,
  `owner decision`. A fix that changes behaviour says so, with what was
  measured.
- A redesign proposal (new contract, changed control flow, cross-cutting) or
  any other call the owner owes is an entry whose status is `needs sign-off`
  or `owner decision`. ALWAYS give it `**Options:** (a) …; (b) …` and
  `**Default if nothing is decided:** …` — what applies until the owner
  answers, so the queue never stalls on silence. A gate the entry holds is
  one more clause: `blocks go-live`, `blocks publication`. The user signs off
  on the approach BEFORE it is built.

## Pin it with a failing test

Prose plus a `file:line` cite is a claim; a test the reader can run is
evidence. Every entry gets one, in the project's own test idiom — grep for an
existing ignored/skipped test and match it; never invent a second convention.

- ALWAYS write the test to assert the CORRECT behavior, not the buggy output,
  so it fails against today's code. Shape: a doc comment states the mechanism,
  the test drives the real code path (faking only external systems), and the
  skip reason restates why it currently fails.
- ALWAYS run it and watch it fail before the entry counts as recorded — a test
  that passes today proves nothing, recorded or not.
- ALWAYS mark it a known failure so the suite stays green: Rust
  `#[ignore = "..."]`, pytest `xfail`/`skip(reason=...)`, Go `t.Skip("...")`,
  or whatever this project already uses.
- ALWAYS put the entry id in the skip/ignore reason next to the mechanism
  (`"<ENTRY-ID>: <mechanism>"`) — either side greps straight to the other.
- NEVER let writing this test become writing the fix. The test asserts correct
  behavior and stays red; producing it is recording, exactly WISDOM § Bug
  triage's "record, don't fix" — the assertion, never the code that
  makes it pass.

**Carve-out — no test required:** `docs`, `ops`, `config`, `design`,
`duplication`, `traceability` entries, and a `perf`/`latency` finding that
needs production-scale data or infra a test suite can't construct. State the
carve-out inline in the body: `no test — <type>`.

## Not-a-defect section

A permanent section — the project may already name it `## Design invariants —
intentional, do not re-report` — holds one compressed line per ruling:
what was reported, and why it is correct behaviour. These are NEVER deleted;

From kronael/tools, Unlicense.

More from kronael/tools