3 files changed, 121 insertions, 0 deletions
diff --git a/claude-rules/todo-format.md b/claude-rules/todo-format.md
index 5c34966..55530de 100644
--- a/claude-rules/todo-format.md
+++ b/claude-rules/todo-format.md
@@ -33,6 +33,52 @@ When a project's `todo.org` lacks the section, add it before filing or
 grading further tasks — propose the priority semantics and tag set from the
 project's existing usage, and confirm with Craig.
 
+### Bug priority from severity × frequency (mandatory where a codebase exists)
+
+Some projects carry a codebase — source the project maintains under version
+control — even when the project isn't primarily a "code project." home and work
+both have one. Wherever a project has a codebase, a task representing a bug
+*against that codebase* does not get its priority argued: it is **dictated** by
+the severity × frequency matrix below. This is not opt-in. Features keep their
+per-project `[#A]`–`[#D]` roadmap judgment; codebase bugs do not.
+
+Two facts set a bug's priority:
+
+- **Severity** — how bad it is when it occurs (service down / data loss /
+  security or privacy leak at one end; a cosmetic nit at the other).
+- **Frequency** — how often a user hits it (every user every time → rare edge
+  case).
+
+```
+| 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       |
+```
+
+P-level → priority letter (fixed — not a per-project knob):
+
+- P1 → `[#A]`
+- P2 → `[#B]`
+- P3 → `[#C]`
+- P4 → `[#D]`
+
+Release vehicle is illustrative and project-dependent: P1 = current
+release/patch, P2 = next patch, P3 = next major, P4 = backlog. A project with no
+release train maps the letters and skips the vehicle. A "no open `[#A]` bugs"
+release gate therefore means "no open P1."
+
+Each project still defines, in its scheme header, what
+Critical/Major/Minor/Cosmetic and the frequency rows mean *for its own
+codebase* — the bands are concrete per codebase, but the matrix structure and
+the letter mapping are fixed.
+
+**Severity-alone carve-out:** privacy or security leaks, compliance violations,
+and safety issues are graded on severity alone — one occurrence with the right
+consequences is a showstopper no matter how rarely it would be hit.
+
 ## The Rule
 
 A todo entry has two parts:
diff --git a/docs/design/2026-06-27-bug-priority-matrix-cover-note.org b/docs/design/2026-06-27-bug-priority-matrix-cover-note.org
new file mode 100644
index 0000000..d6398e0
--- /dev/null
+++ b/docs/design/2026-06-27-bug-priority-matrix-cover-note.org
@@ -0,0 +1,5 @@
+#+TITLE: Cover note for the bug-priority-matrix-proposal.md just sent
+#+SOURCE: from emacs-wttrin
+#+DATE: 2026-06-27 23:57:30 -0400
+
+Cover note for the bug-priority-matrix-proposal.md just sent. WHAT: a Severity × Frequency bug-priority matrix (P1-P4) distilled from wttrin's priority scheme today. It derives a bug's priority from two facts (severity, frequency) instead of opinion, maps each cell to a release vehicle, and — for projects running the todo-format [#A]-[#D] scheme — has bugs derive their letter from the matrix while features keep their roadmap judgment. Includes a special-category rule (privacy/security/safety graded on severity alone) and a tie-in that makes a 'no open [#A]' release gate fact-based. WHY SEND: this is a generic defect-management pattern, not wttrin-specific, so it belongs upstream to distribute with any code-centric project (a claude-rule and/or a todo.org priority-scheme template snippet — your call on placement and whether it folds into todo-format.md or stands alone). TWO ASKS: (1) consider a companion NON-CODING matrix for work-product/ops/decision defects — the same frequency×severity shape likely generalizes beyond bugs; (2) treat this as a LIVING DOCUMENT — adjust bands and wording as projects use it until it's as mature as the coding matrix. SOURCING: the matrix is a standard industry pattern; I adapted a generic version and the wttrin worked-example. Nothing work-confidential is copied — please keep the upstream artifact generic and uncited to any private reference. wttrin keeps its local copy in todo.org as the stopgap until you distribute the canonical.
diff --git a/docs/design/2026-06-27-bug-priority-matrix-proposal.md b/docs/design/2026-06-27-bug-priority-matrix-proposal.md
new file mode 100644
index 0000000..4b49769
--- /dev/null
+++ b/docs/design/2026-06-27-bug-priority-matrix-proposal.md
@@ -0,0 +1,70 @@
+# 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.