# Bug Priority — Severity × Frequency Matrix (proposed rule for code projects)

Applies to: code-centric projects (a `:bug:`-tracking `todo.org`, an issue tracker, or any defect backlog).

Status: proposed. Distilled from wttrin's priority scheme on 2026-06-27. Generic defect-management pattern — adapt the bands per project. Treat as a living document; refine the wording and bands as projects use it, the way wttrin's matrix will mature in use.

## The problem

Without a systematic scheme, bugs get prioritized by who's loudest, who has the most authority, or who's most frustrated. Most bugs drift to "medium," and no one can say what medium means. Whether a bug is "high priority" stays a matter of opinion, so the release decision becomes a judgment call every time.

## The approach — derive priority from two facts

Priority should fall out of two relatively objective factors, not an argument:

1. Severity — how bad is it when the bug occurs? (Service down / data loss / security or privacy leak at one end; cosmetic nit at the other.)
2. Frequency — how often will a user hit it? (Every user every time at one end; rare edge case at the other.)

Put severity on one axis and frequency on the other. Each cell maps to a priority level; each level maps to a release vehicle.

```
| Frequency / Severity   | Critical | Major | Minor | Cosmetic |
|------------------------+----------+-------+-------+----------|
| Every user, every time | P1       | P1    | P2    | P3       |
| Most users, frequently | P1       | P2    | P3    | P4       |
| Some users, sometimes  | P2       | P3    | P3    | P4       |
| Rare edge case         | P2       | P3    | P4    | P4       |
```

Response per level:

- P1 / Critical — fix in the current release or patch. Blocks a release.
- P2 / High — next patch release.
- P3 / Medium — next major release.
- P4 / Low — backlog, fix when convenient.

(A P0 / showstopper tier — all hands, emergency release — sits above P1 for projects that need it.)

## Adapt the bands per project

The axis labels are generic; each project defines what Critical/Major/Minor/Cosmetic and the frequency rows mean in its own terms. wttrin's worked example:

- Critical: no weather at all on the common path (crash, hard error), wrong weather shown as if correct (silent data error), or a privacy/security leak.
- Major: a feature broken but with a workaround.
- Minor: degraded but usable.
- Cosmetic: a pure visual nit.
- Frequency rows map to default-config-every-time → common-action → feature/config-specific → unusual-input/environment.

## Special category — severity alone

Some defects don't correlate with frequency: privacy/security leaks, compliance violations, safety issues. Grade these on severity alone — one occurrence with the right consequences is a showstopper no matter how rarely it'd be noticed. (wttrin's worked case: a home address leaked into public git history — Critical on severity alone, scrubbed 2026-06-26.)

## Integrating with a project's `[#A]`–`[#D]` priority scheme

Projects that already run a letter-priority scheme (the rulesets `todo-format.md` convention) keep it for features — deciding feature X is more urgent than feature Y is a legitimate roadmap judgment. Bugs are different: their letter should be derived, not argued.

Rule: a `:bug:`'s letter comes from the matrix, not a choice.

- P1, P2 → `[#A]` (release-gating)
- P3 → `[#C]` (scheduled fix, has a workaround)
- P4 → `[#D]` (backlog)

(The exact letter mapping is a per-project knob; this is wttrin's.) Features keep their `[#A]`–`[#D]` judgment as a roadmap call; only bugs derive their letter from the matrix.

## Tie-in to release criteria

When a project gates a release on a soak or a "no open [#A]" rule, the matrix makes that gate fact-based: "no open [#A] bugs" becomes "no open P1/P2," which the matrix produces. A severity-graded soak follows naturally — a P1/P2/P3 found in the window resets the clock and must be fixed; a P4 logs to backlog without resetting.

## The payoff

Once each priority maps to a release vehicle, you've pre-decided most issues and only discuss the genuine edge cases. The release decision stops being a soul-search and becomes arithmetic. When there's disagreement on a bug's priority, the matrix wins.