canon: software virtues tension matrix + observability extension + essay#192
Merged
Conversation
Canon Quality —
|
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
Autofix Details
Bugbot Autofix prepared a fix for the issue found in the latest run.
- ✅ Fixed: Circular
derives_frombetween principle and matrix- Removed the matrix from the tier-1 principle's derives_from to break the circular dependency, and added the 2018 Medium article URL as the actual upstream source.
Preview (82026af0f8)
diff --git a/canon/definitions/software-virtues-vocabulary.md b/canon/definitions/software-virtues-vocabulary.md
new file mode 100644
--- /dev/null
+++ b/canon/definitions/software-virtues-vocabulary.md
@@ -1,0 +1,132 @@
+---
+uri: klappy://canon/definitions/software-virtues-vocabulary
+title: "Software Virtues Vocabulary — Ten Quality Attributes That Compete for Priority"
+audience: canon
+exposure: nav
+tier: 2
+voice: neutral
+stability: stable
+tags: ["canon", "definitions", "software-virtues", "quality-attributes", "ilities", "prioritization", "tradeoffs"]
+epoch: E0008.4
+date: 2026-05-10
+derives_from: "https://medium.com/@klappy/what-are-software-virtues-and-how-to-prioritize-them-f0b583741afe (2018-09-09 — origin article)"
+complements: "canon/principles/quality-attributes-are-in-tension.md, canon/observations/quality-attribute-tension-matrix.md, odd/maturity.md"
+governs: "Vocabulary used across canon when discussing tradeoffs between competing software properties. 'Virtues' is the rhetorical/historical name; 'quality attributes' or 'ilities' is the operational synonym. Both are first-class."
+status: active
+---
+
+# Software Virtues Vocabulary — Ten Quality Attributes That Compete for Priority
+
+> Ten properties every software project optimizes for, in tension with each other: usability, originality, stability, urgency, efficiency, maintainability, versatility, interoperability, affordability, and reality. Each is a virtue (a thing worth pursuing) and a quality attribute (an "-ility" the engineering literature already names). Each stands in tension with others. Priority among them shifts by team, by project, and by lifecycle phase. The vocabulary is from a 2018 article that has stayed load-bearing for nearly a decade; this entry canonizes it for ODD. The ten are a canonical worked example, not an exhaustive set — the universe of quality attributes is far larger, and the principle holds across all of it.
+
+---
+
+## Summary — A Stable Naming for the Tradeoff Space
+
+Software has no single objective function. Every project optimizes for a bundle of competing properties, and every choice that advances one property tends to retreat from at least one other. The engineering literature names many of these properties — usually with the suffix "-ility" — and treats them as orthogonal axes. The 2018 source article reframed them as **virtues**: things worth pursuing, with intrinsic moral weight, that nevertheless conflict.
+
+This document defines the ten virtues that have proven generative across nearly a decade of use. The name "virtue" is preserved because the moral framing is load-bearing — these are not just metrics, they are values a team holds. The phrase "quality attribute" (or "-ility") is the operational synonym that integrates with industry vocabulary and ODD's existing language. Both names refer to the same set; canon documents may use either depending on register.
+
+The tensions among these virtues — which optimize against which, and under what conditions — are mapped at `canon/observations/quality-attribute-tension-matrix.md`. The principle that the tensions are real and irreducible is at `canon/principles/quality-attributes-are-in-tension.md`. The phase-by-phase shift in which virtues take priority is grounded in `odd/maturity.md`.
+
+---
+
+## The Ten Virtues
+
+Each virtue is named with its primary form first, followed by its companion synonym in the original article. The definition states what the virtue measures or rewards; the operational note states how it is observed in practice.
+
+### 1. Usability / Simplicity
+
+**Definition.** The degree to which the user can accomplish their intended task without unnecessary friction, training, or guesswork. Includes learnability (how quickly a new user becomes effective) and intuitiveness (how much the interface aligns with prior expectations).
+
+**Operational note.** Observed through user testing, time-to-task, error rates, and the volume of support requests asking how to do basic things. A product whose documentation is required to use it is failing on usability before the manual is opened.
+
+### 2. Originality / Innovation
+
+**Definition.** The degree to which the project does something not already done — a new approach, a new combination, a new affordance. Differentiation from existing alternatives; intrinsic novel value.
+
+**Operational note.** Observed through the question "what would have to be true elsewhere for this to be unnecessary?" If the honest answer is "nothing — there are five products that already do this," the project is not original.
+
+### 3. Stability / Reliability
+
+**Definition.** Two related properties often treated as one: stability (the system does not freeze, crash, or corrupt state) and reliability (when something goes wrong, the system recovers without losing the user's work). Either may dominate depending on the use case.
+
+**Operational note.** Observed through error rates, mean time between failures, recovery times, and the question "if a user trusts this with their work, will the trust be repaid?"
+
+### 4. Urgency / Timeliness
+
+**Definition.** The degree to which the project ships in time to serve its purpose. Urgency is not speed for its own sake; it is the temporal fit between the delivery and the window in which delivery still matters. Late software solving a no-longer-urgent problem has failed on this virtue.
+
+**Operational note.** Observed through schedule fit, market timing, and the question "if we ship six months from now, do users still need this?"
+
+### 5. Efficiency / Scalability
+
+**Definition.** The degree to which the system performs its work without wasted resources — CPU, memory, hardware, latency, energy, dollars. Scalability is the time-shape of efficiency: does the system stay efficient as load grows?
+
+**Operational note.** Observed through profiling, cost-per-request, throughput under load, and the question "what does it cost to serve the next user, and is that cost sustainable?"
+
+### 6. Maintainability / Manageability
+
+**Definition.** The degree to which the project can be continued by people who did not write it. Includes understandability (how readable the code is to a new contributor), modularity (whether parts can be changed independently), testability (whether changes can be verified before shipping), and hire-ability (whether the technologies and patterns chosen permit finding qualified maintainers).
+
+**Operational note.** Observed through onboarding time for new contributors, the rate at which untouched code becomes feared code, and the question "if the original team disappeared tomorrow, could the project continue?"
+
+### 7. Versatility / Adaptability
+
+**Definition.** The breadth of use cases the project can serve without modification. The degree to which the project handles related tasks beyond its primary one. The opposite of single-purpose narrowness.
+
+**Operational note.** Observed through the variety of users finding value in the project and the rate at which feature requests are answered with "actually, you can already do that." Watch for the failure mode: versatility chased prematurely produces software that does many things badly instead of one thing well.
+
+### 8. Interoperability
+
+**Definition.** The degree to which the project can exchange data and behavior with adjacent systems. Includes import/export of data formats, adherence to standards, API surface area, and the absence of artificial lock-in.
+
+**Operational note.** Observed through the friction a user experiences when bringing data in or taking data out, and the question "does this project make the user's larger workflow easier or harder?"
+
+### 9. Affordability / Sustainability
+
+**Definition.** Two coupled properties: affordability (the price the user pays is appropriate to the value received) and sustainability (the cost of building and operating the project is sustainable for the team that produces it). The intersection is whether the project's economic model survives contact with reality.
+
+**Operational note.** Observed through unit economics, retention, runway, and the question "can the team that built this afford to keep building it?" Affordability has cost gravity over every other virtue: each virtue is purchased with effort or money.
+
+### 10. Reality
+
+**Definition.** The meta-virtue that grounds all other virtues against the world as it is, rather than the world as planned. Reality includes:
+
+- **Costs** — effort and resources actually required
+- **Benefits** — advantages of success, weighted by probability
+- **Risks** — probability of failure and its consequences
+- **Dependencies** — what must be true for this to work
+- **Penalties** — consequences of not delivering
+- **Compliance** — regulatory and contractual constraints
+
+**Operational note.** Observed through the gap between stated plans and observed outcomes. Reality is the virtue that keeps the other nine honest. When teams optimize for usability without testing with real users, for originality without checking what already exists, or for urgency without checking what users actually need, reality has been demoted below where it belongs.
+
+---
+
+## "Virtues" and "Quality Attributes" Are the Same Set
+
+The 2018 source article called these virtues. The engineering literature calls them quality attributes, non-functional requirements, or "-ilities" (a suffix that fits most of them awkwardly). Both vocabularies refer to the same ten properties.
+
+Canon uses both names depending on register:
+
+- **Virtue** — moral, rhetorical, used when emphasizing that these are values a team chooses to pursue
+- **Quality attribute / "-ility"** — operational, technical, used when integrating with industry frameworks (ISO/IEC 25010, ATAM, etc.) or when discussing measurement and tradeoff analysis
+
+Neither vocabulary is preferred. A canon document discussing prioritization may use "virtues" for the framing and "quality attributes" for the worked detail without contradiction.
+
+---
+
+## What This Document Does Not Define
+
+Three things deliberately left to other canon documents:
+
+- **Which virtues take priority when** — see `odd/maturity.md` for phase-weighting and `canon/observations/quality-attribute-tension-matrix.md` for pair-by-pair detail across the canonical ten.
+- **How to elicit team priorities** — the 2018 article suggested MoSCoW voting and the Hundred Dollar Method. Both are surfaced as starting points, not endorsed as load-bearing. ODD's mature answer to elicitation lives elsewhere.
+- **The full universe of quality attributes** — there are dozens more. Auditability, securability, debugability, deployability, recoverability, observability, portability, accessibility, localizability, and many others are real. The ten here are the canonical worked example used as a reference corpus; the principle at `canon/principles/quality-attributes-are-in-tension.md` holds across the broader set, and project-specific tension graphs are generated against the principle rather than restricted to this list.
+
+---
+
+## Lineage
+
+The vocabulary is from "Software Virtues — How to Prioritize" by Chris Klapp, published on Medium in September 2018. The article seeded `odd/maturity.md` (phase-weighting) and is now the source of this definition. The companion canon — the in-tension principle and the worked-example tension matrix — completes the systematic build the original article only sketched.
diff --git a/canon/observations/observability-tension-extension.md b/canon/observations/observability-tension-extension.md
new file mode 100644
--- /dev/null
+++ b/canon/observations/observability-tension-extension.md
@@ -1,0 +1,122 @@
+---
+uri: klappy://canon/observations/observability-tension-extension
+title: "Observability Tension Extension — One Worked Example of Extending the Matrix from ODD's Existing Canon"
+audience: canon
+exposure: nav
+tier: 2
+voice: neutral
+stability: stable
+tags: ["canon", "observations", "quality-attributes", "software-virtues", "tradeoffs", "tensions", "observability", "extension", "matrix-extension", "epoch-8"]
+epoch: E0008.4
+date: 2026-05-10
+derives_from: "canon/principles/quality-attributes-are-in-tension.md, canon/observations/quality-attribute-tension-matrix.md, canon/definitions/software-virtues-vocabulary.md, canon/case-studies/catalog-observability-gap.md, docs/appendices/epoch-8.md, docs/appendices/epoch-8-2.md, docs/appendices/epoch-8-3.md, canon/values/axioms.md"
+complements: "odd/maturity.md"
+governs: "Reference for the tensions between observability and the canonical ten quality attributes. Demonstrates the extension pattern: when an ility has rich canon support, its tensions are stitched from existing canon rather than re-derived. Same shape applies to other ilities (auditability, securability, accessibility, etc.) when they earn their own extension docs."
+status: active
+---
+
+# Observability Tension Extension — One Worked Example of Extending the Matrix from ODD's Existing Canon
+
+> Observability earns its own extension because ODD has been writing about it for an entire epoch already. This document maps observability's tensions against the canonical ten — ten new pairs, each grounded in either the catalog-observability-gap case study or the Epoch 8 / 8.2 / 8.3 appendices. The point is not just observability; it is the *pattern*. When an ility already has canon, its tension graph stitches from that canon. The eventual dynamic-generation method generalizes this pattern; this doc demonstrates what one well-grounded extension looks like by hand.
+
+---
+
+## Summary — Observability Joins the Tension Graph with Its Canon Already Written
+
+Observability is not a new ility. ODD has lived inside it for an entire epoch — `klappy://docs/appendices/epoch-8` (Observability: Transparent Telemetry and Infrastructure Accountability), `klappy://docs/appendices/epoch-8-2` (Put the Clock in the Room), `klappy://docs/appendices/epoch-8-3` (Validation as Observable Mode), and the case study at `klappy://canon/case-studies/catalog-observability-gap` (When the Knowledge Server Cannot See Its Own Knowledge Base). Observability's tensions with the canonical ten are therefore not derived from intuition; they are stitched from canon already written.
+
+This document does that stitching for one ility as a worked example of the broader extension pattern. The pattern: when a project's quality attributes include something beyond the canonical ten, the tensions are not generated from nothing — they are pulled from existing canon where it exists, and from the principle (`canon/principles/quality-attributes-are-in-tension.md`) where canon is silent.
+
+The principle itself is unchanged. The matrix at `canon/observations/quality-attribute-tension-matrix.md` is unchanged. Observability is not promoted into the canonical set; the canonical ten stays canonical. This extension is the eleventh node added off to the side, with edges back to each of the ten and citations to the canon evidence for each edge.
+
+---
+
+## Definition — Observability in ODD
+
+**Definition.** The degree to which the system makes its own state legible to those who need to act on it. In ODD specifically, observability is the structural property that lets the model, the operator, and the team observe what the system is actually doing rather than what they think it is doing. Includes telemetry (what calls happened), state visibility (what the system thinks now), process visibility (what mode it is in, what gates have fired), and infrastructure accountability (what the runtime is actually charging in cycles, bytes, dollars).
+
+**Operational note.** Observed by asking three questions and answering them with primary evidence rather than reasoning: (1) Did the action that the system claims happened actually happen? (2) What did it cost? (3) What state is the system in right now? If those questions cannot be answered without rebuilding the answer from inference, observability has failed regardless of what telemetry pipelines exist.
+
+**Why observability is not in the canonical ten.** The 2018 article was written before observability was load-bearing for the kind of work ODD orchestrates. The canonical ten still apply to most projects; observability becomes critical specifically when the work is autonomous, agent-driven, or otherwise not directly supervised by humans who can spot-check by intuition. ODD's E0008 arc was the moment observability moved from optional engineering hygiene to structural requirement.
+
+---
+
+## Tensions Between Observability and the Canonical Ten
+
+Each entry: relationship type, phase weighting, operating dynamic, and the canon evidence for the claim.
+
+### Observability ↔ Usability (M*, Production)
+
+Mild mutual tension. Rich instrumentation surfaces — dashboards, traces, logs — complicate the user-facing UX surface and pull cognitive budget from the primary task. Conversely, observability into how users actually use the product is what *reveals* usability problems that would otherwise stay invisible. Net is mildly tense in production when instrumentation surfaces compete with task surfaces; net is positive at pilot when usage telemetry informs UX iteration.
+
+*Canon evidence.* The catalog-observability-gap case study (`klappy://canon/case-studies/catalog-observability-gap`) is the worked example where observability into how the catalog was *used* surfaced a usability/correctness problem the implementation team had not seen.
+
+### Observability ↔ Originality (M*, Pilot)
+
+Asymmetric mutual tension. You instrument what you already understand; truly novel mechanisms resist instrumentation because their failure modes are not yet named. Originality-first projects often defer observability ("we do not yet know what to measure"), and observability-first projects often shape the design to fit existing telemetry primitives, foreclosing some originality. Bites at pilot, when the original idea is being made operationally legible for the first time.
+
+*Canon evidence.* `klappy://docs/appendices/epoch-8-3` (Validation as Observable Mode) is the moment ODD turned its lens on its own process and found that the original epistemic-modes idea needed to be re-shaped for legibility — the originality of "validation as a distinct mode" required new observability primitives, not just rewiring the existing ones.
+
+### Observability ↔ Stability (S, Production)
+
+Strong synergy. Observability is the primary mechanism by which stability is achieved — you cannot fix what you cannot see. Tension only when instrumentation itself becomes a stability hazard (telemetry pipelines that fall over and take the host system with them). Bites at production, where both expectations are highest and where instrumentation reliability becomes a first-class concern.
+
+*Canon evidence.* `klappy://docs/appendices/epoch-8` opens with the framing that infrastructure observability is what makes stability claims falsifiable; stability without observability is a claim, not evidence.
+
+### Observability ↔ Urgency (M, Production)
+
+Mutual tension. Urgency-driven projects routinely skip telemetry; the absence of telemetry then forces urgency-mode debugging when things break in production. The cycle reinforces itself. Bites hardest at production, where the cost of un-observability is paid in compounded incident response time.
+
+*Canon evidence.* The catalog-observability-gap case study (`klappy://canon/case-studies/catalog-observability-gap`) explicitly names the urgency-skipping pattern: oddkit shipped without the consumer-pagination contract that would have made the gap immediately visible; the urgency cost was paid later in operator confusion and a production smoke that took hours to interpret.
+
+### Observability ↔ Efficiency (M, Production)
+
+Mutual tension, direct and measurable. Telemetry has cost: bytes on the wire, cycles in the worker, storage in the analytics engine, dashboards to maintain. Efficient systems often run lean on observation by design. The reverse tension is real too: optimizing without observability is optimizing in the dark, and many efficiency wins come from having seen the bottleneck. Bites at production, where both the cost of telemetry and the cost of inefficiency are simultaneously measurable.
+
+*Canon evidence.* `klappy://docs/appendices/epoch-8` introduces the Analytics Engine architecture specifically because earlier observability designs had unacceptable efficiency costs; the architectural choice was driven by the tension itself.
+
+### Observability ↔ Maintainability (S, Production)
+
+Strong synergy. Observable code is maintainable code — a new contributor reading a system with rich tracing and structured logs can answer "what does this actually do" in minutes rather than hours. The tension is mild and only at extremes: instrumentation libraries themselves can become a maintenance burden, especially when the project is small enough that the telemetry surface exceeds the business-logic surface.
+
+*Canon evidence.* `klappy://docs/appendices/epoch-8-2` (Put the Clock in the Room) is a case where adding one observability primitive (`server_time` in every response) directly reduced maintenance load — the model stops fabricating elapsed times, stops getting them wrong, and stops requiring operator correction.
+
+### Observability ↔ Versatility (M*, Production)
+
+Mild mutual tension. Versatile systems have more code paths and more states; instrumenting all of them is more work, and partial instrumentation often misses the rare paths that produce the rare bugs. Conversely, versatile-and-observable systems become complex enough that the observability surface itself becomes hard to navigate. Bites at production where both versatility and observability ambitions compound.
+
+*Canon evidence.* The catalog-observability-gap case study (`klappy://canon/case-studies/catalog-observability-gap`) hit exactly this — oddkit's versatility (serving 500+ docs across multiple consumer shapes) combined with partial observability of consumer behavior produced a gap the team did not see until a consumer surfaced it.
+
+### Observability ↔ Interoperability (S, Production)
+
+Synergy mostly. Interoperable systems benefit from observability that crosses system boundaries — distributed tracing, correlation IDs, OpenTelemetry-class standards. The integration *is* the observability work in many cases. Tension only when proprietary observability primitives conflict with interop standards (e.g., a vendor-specific tracing protocol that does not propagate across partner boundaries). Bites at production.
+
+*Canon evidence.* `klappy://docs/appendices/epoch-8` documents the choice to use Cloudflare Analytics Engine — a non-portable substrate — and the deliberate decision to accept the interop cost in exchange for the efficiency-and-affordability win. The decision is recorded as a tension explicitly accepted, not avoided.
+
+### Observability ↔ Affordability ($, Production)
+
+Cost gravity. Telemetry has direct ongoing cost: ingestion fees, storage tiers, dashboard licenses, on-call rotations to interpret what the dashboards show. Affordability constrains how much observability investment a project can sustain. Bites at production, where the recurring monthly cost of observation becomes a line item.
+
+*Canon evidence.* `klappy://docs/appendices/epoch-8` names this directly: the choice of Analytics Engine over alternatives was driven by affordability; the choice of `SUM(_sample_interval)` aggregation rather than per-event storage was driven by the same constraint.
+
+### Observability ↔ Reality (S, all phases)
+
+Strong synergy. This is the foundational pair. Axiom 4 (`canon/values/axioms.md` — "You Cannot Verify What You Did Not Observe") is the principle stated as a value; observability is the technical means by which the value becomes operative. Reality demands that the team observe what is actually happening; observability answers that demand. Tension only when the cost of observation itself outpaces what reality provides in return — i.e., when over-instrumentation becomes its own reality-distortion. Bites at all phases, since both operate continuously.
+
+*Canon evidence.* `klappy://canon/values/axioms.md` (Axiom 4) is the value statement; the entire E0008 arc (`klappy://docs/appendices/epoch-8`, `epoch-8-2`, `epoch-8-3`) is its operationalization. The catalog-observability-gap case study is a worked failure mode where the axiom was held in principle and violated in practice — the system made claims about its knowledge base that the system itself had no way to verify.
+
+---
+
+## How to Read This Extension
+
+The extension follows the same shape as the matrix: each pair has a relationship type, a phase tag, an operating dynamic, and (new in extensions) an explicit *canon evidence* citation pointing at the document or epoch where ODD has already lived this tension.
+
+The citation requirement is not decoration. It is the structural reason this extension is useful: every claim in this document is grounded in canon written for other reasons, in some cases years ago. The extension is not asserting new tensions; it is *naming* tensions ODD has already paid the cost of learning, and making them retrievable in the same shape as the canonical ten.
+
+When the matrix is extended further — auditability, securability, accessibility, portability — the pattern holds. The extension is cheap when the canon already exists. The extension is principle-grounded when canon is silent. The extension never re-opens the canonical ten.
+
+---
+
+## Lineage
+
+Observability is the first extension because ODD has the deepest existing canon on it. The case study at `klappy://canon/case-studies/catalog-observability-gap` and the three epoch appendices (`klappy://docs/appendices/epoch-8`, `epoch-8-2`, `epoch-8-3`) constitute roughly half a year of accumulated thinking that this extension stitches into the tension-graph format. Future extensions for other ilities will follow the same template — definition tight enough for canon, ten new pair entries, citations to existing canon where it exists, principle-grounded reasoning where canon is silent. The eventual method doc at `canon/methods/quality-attribute-tension-survey` (forthcoming) will operationalize this stitching dynamically; this extension is the worked example demonstrating what good output looks like.
diff --git a/canon/observations/quality-attribute-tension-matrix.md b/canon/observations/quality-attribute-tension-matrix.md
new file mode 100644
--- /dev/null
+++ b/canon/observations/quality-attribute-tension-matrix.md
@@ -1,0 +1,294 @@
+---
+uri: klappy://canon/observations/quality-attribute-tension-matrix
+title: "Quality Attribute Tension Matrix — All Forty-Five Pairs Across Ten Virtues, Phase-Weighted"
+audience: canon
+exposure: nav
+tier: 2
+voice: neutral
+stability: stable
+tags: ["canon", "observations", "quality-attributes", "software-virtues", "tradeoffs", "tensions", "matrix", "phase-weighting", "ilities"]
+epoch: E0008.4
+date: 2026-05-10
+derives_from: "canon/definitions/software-virtues-vocabulary.md, canon/principles/quality-attributes-are-in-tension.md, odd/maturity.md, https://medium.com/@klappy/what-are-software-virtues-and-how-to-prioritize-them-f0b583741afe"
+complements: "canon/values/axioms.md"
+governs: "Reference for which quality attributes are in tension with which, the type and direction of each tension, and the project phase at which each tension bites hardest. Used during prioritization, design review, and tradeoff analysis."
+status: active
+---
+
+# Quality Attribute Tension Matrix — All Forty-Five Pairs Across Ten Virtues, Phase-Weighted
+
+> A worked example of the tension graph across the canonical ten quality attributes: forty-five unique pairs, each tagged with relationship type (mutual tension / asymmetric grounding / synergy / cost gravity), direction (which virtue erodes which), and the project phase at which the tension bites hardest (PoC / Pilot / Production). Twenty-one of the pairs are named in the 2018 source article; twenty-four are filled in here for the first time. The matrix demonstrates the shape the tension survey produces — it is not the master reference. The universe of quality attributes is far larger than ten; this document is the corpus that shows what good looks like when the principle at `canon/principles/quality-attributes-are-in-tension.md` is applied.
+
+---
+
+## Summary — A Worked Example of the Tension Graph for the Canonical Ten
+
+Every design decision moves at least one quality attribute up and at least one other down. The principle at `canon/principles/quality-attributes-are-in-tension.md` asserts that the moves are not random and that this holds for any set of quality attributes. This document maps the canonical ten as a worked example: which virtue erodes which, in which direction, and at which project phase the erosion is most consequential.
+
+The matrix uses four relationship types:
+
+- **Mutual tension (M)** — both virtues erode the other. Optimizing for one reliably costs the other.
+- **Asymmetric grounding (A)** — one virtue disciplines the other without symmetric retaliation. The grounding virtue (usually reality) does not get eroded by what it constrains.
+- **Synergy (S)** — both virtues reinforce each other, with mild tension only at extremes. Pursuing one tends to advance the other.
+- **Cost gravity ($)** — affordability's relationship with every other virtue: each virtue is purchased with effort, time, or money, so affordability constrains how much of each can be afforded.
+
+Phase weighting follows the three-level maturity model from `odd/maturity.md`:
+
+- **PoC** (Level 0 — exploration, learning) — tension bites when the team has not yet decided whether the idea is worth pursuing.
+- **Pilot** (Level 1 — pilot/product) — tension bites when the project has real users but has not yet committed to long-term operation.
+- **Production** (Level 2 — production / long-term) — tension bites when the project is committed to ongoing operation under real load.
+
+Most tensions bite at one phase more than the others. A single phase tag per cell names where the tension is sharpest; secondary phases are noted where the bite is broad.
+
+---
+
+## Compact Reference — The 10×10 Grid
+
+Quick-reference grid. Lower-left triangle is filled (each pair appears once). Reading: row virtue's relationship to column virtue.
+
+| | Use | Orig | Stab | Urg | Eff | Maint | Vers | Inter | Aff | Real |
+|--------------|:---:|:----:|:----:|:---:|:---:|:-----:|:----:|:-----:|:---:|:----:|
+| **Use**ability | · | | | | | | | | | |
+| **Orig**inality | M | · | | | | | | | | |
+| **Stab**ility | M* | M | · | | | | | | | |
+| **Urg**ency | M | M* | M | · | | | | | | |
+| **Eff**iciency | M* | M* | M* | M | · | | | | | |
+| **Maint**ain | M* | M* | S | M | M | · | | | | |
+| **Vers**atility | M | M* | M* | M* | M | M* | · | | | |
+| **Inter**op | M* | M | M* | M | M* | M* | S | · | | |
+| **Aff**ordability | $ | $ | $ | $ | S | S | $ | $ | · | |
+| **Real**ity | A | A | S | A | S | S | A | S | S | · |
+
+Legend: M = mutual tension (named in 2018 article). M* = mutual tension (filled in here). A = asymmetric grounding. S = synergy. $ = cost gravity. · = self.
+
+---
+
+## The Forty-Five Pairs
+
+Each entry: relationship type, direction (if asymmetric), bite phase, and the operating dynamic. Pairs are ordered by row index then column index from the grid above.
+
+### Pairs Centered on Usability
+
+#### 1. Usability ↔ Originality (M, Pilot)
+
+Mutual tension. New innovative features are rarely understood well enough to be made simple at first; usability requires patterns the user already recognizes, and originality means breaking those patterns. Bites hardest at pilot phase, when the original idea must reach actual users. Article-named.
+
+#### 2. Usability ↔ Stability (M*, Pilot)
+
+Mutual tension, mild. Polish for usability sometimes hides instability under aesthetics ("looks finished, breaks under edge cases"); defensive stability code can produce confirmation dialogs and error states that erode usability. The tension is subtle but real at pilot when the product first touches users who do not know the workarounds.
+
+#### 3. Usability ↔ Urgency (M, Production)
+
+Mutual tension. Rushing to ship leaves no time for user testing or interface refinement; user testing and refinement take time. Bites at production, where the cost of unusable software is paid in support load and churn. Article-named.
+
+#### 4. Usability ↔ Efficiency (M*, Pilot)
+
+Mutual tension, mild. Beautifully usable interfaces often involve animations, transitions, and helpful intermediate states that cost cycles; efficient backends sometimes dictate workflows that are technically correct but cognitively awkward. Bites at pilot when the product targets devices or networks where efficiency limits are felt.
+
+#### 5. Usability ↔ Maintainability (M*, Production)
+
+Mutual tension. Usability features add code paths (undo stacks, helpful errors, accessibility affordances) that increase the code surface; maintainable, conventional code structures sometimes resist the special-casing that good UX demands. Bites at production, where the maintenance cost of a usability-rich product compounds.
+
+#### 6. Usability ↔ Versatility (M, Pilot)
+
+Mutual tension. Versatility invites ambiguity that may undermine intuitiveness — software that does many things must offer choices, and choices erode the "one obvious way" that drives intuitive usability. Bites at pilot, when the product's scope is being negotiated against real-user friction. Article-named.
+
+#### 7. Usability ↔ Interoperability (M*, Pilot)
+
+Mutual tension. Interop layers expose options (which format to export, which provider to integrate with) that complicate the UX surface; UX that wants to feel decisive sometimes hides interop choices behind opinionated defaults that limit interoperability. Bites at pilot, when integration partners are negotiated.
+
+#### 8. Usability ↔ Affordability ($, Pilot)
+
+Cost gravity. Usability work — testing, iteration, design talent — has direct cost. Affordability constrains how much UX investment a project can sustain. Bites at pilot, when the unit economics of the product are first measured against the design budget.
+
+#### 9. Usability ↔ Reality (A, PoC)
+
+Asymmetric grounding. Reality keeps usability ambitions honest: an interface that tests well with the wrong user base is not usable with the right one. Reality is not eroded by usability; usability is grounded by reality. Bites at PoC, where unrealistic user assumptions are cheapest to correct.
+
+### Pairs Centered on Originality
+
+#### 10. Originality ↔ Stability (M, Pilot)
+
+Mutual tension. Innovative approaches are inherently less battle-tested; stability requires patterns whose failure modes are known. Bites at pilot, when the original idea is exposed to the variability of real-world conditions. Article-named.
+
+#### 11. Originality ↔ Urgency (M*, Pilot)
+
+Mutual tension, asymmetric in flavor. Urgency forces shortcuts that look like originality but are actually hurried imitation; genuine originality requires the time to discover what is actually new. Bites at pilot, when the "are we actually doing something new or just shipping fast" question becomes answerable.
+
+#### 12. Originality ↔ Efficiency (M*, Production)
+
+Mutual tension. Novel approaches usually arrive less optimized than the patterns they replace; efficiency-first design often forecloses the experimental routes that produce originality. Bites at production, where the cost of novel-but-slow becomes operational.
+
+#### 13. Originality ↔ Maintainability (M*, Production)
+
+Mutual tension. Novel patterns are harder to hire for and harder to onboard against; maintainable conventions limit the shapes a novel approach can take. Bites at production, where the team must scale beyond the founders who understood the novelty natively.
+
+#### 14. Originality ↔ Versatility (M*, Pilot)
+
+Mutual tension, mild. Strong novel ideas are usually highly specific to a narrow problem; versatility-first design rarely produces deep originality. Bites at pilot, when the project must decide whether to deepen its novel angle or widen its applicability.
+
+#### 15. Originality ↔ Interoperability (M, Pilot)
+
+Mutual tension. Interop with existing systems requires conformance to existing standards, which forecloses some innovations; pure innovation often produces formats and protocols that the rest of the ecosystem cannot read. Bites at pilot, when integration with the user's existing workflow is negotiated. Article-named.
+
+#### 16. Originality ↔ Affordability ($, Pilot)
+
+Cost gravity. Innovation is expensive — research, dead ends, prototypes that do not ship. Affordability constrains how much novelty a project can afford. Bites at pilot, when the runway shape is first matched against the experimentation budget.
+
+#### 17. Originality ↔ Reality (A, PoC)
+
+Asymmetric grounding. Reality limits originality by reminding the team what is already done, what physics permits, and what users actually want. Reality is not eroded by originality; originality is grounded (sometimes harshly) by reality. Bites at PoC, where unrealistic novelty is cheapest to redirect. Article-named.
+
+### Pairs Centered on Stability
+
+#### 18. Stability ↔ Urgency (M, Production)
+
+Mutual tension. Rushing increases the rate of bugs; thorough stabilization takes time the urgency budget does not have. Bites at production, where instability translates directly to user trust erosion. Article-named.
+
+#### 19. Stability ↔ Efficiency (M*, Production)
+
+Mutual tension. Hyper-optimization sometimes introduces instability (race conditions, edge-case overflow, brittle assumptions); defensive stability code adds overhead that erodes efficiency. Bites at production, where both stability and efficiency expectations are highest.
+
+#### 20. Stability ↔ Maintainability (S, Production)
+
+Synergy. Both stability and maintainability favor clean, predictable code with known failure modes. Mild tension only when "stable" code becomes "untouchable" — the legacy system whose stability comes from no one daring to change it. Bites at production, when the system is mature enough for legacy patterns to set in.
+
+#### 21. Stability ↔ Versatility (M*, Pilot)
+
+Mutual tension. Versatile code has more states, more code paths, and more configurations to test — making stabilization harder; stable code is often stable because its scope is narrow. Bites at pilot, when the scope-versus-reliability tradeoff is being negotiated.
+
+#### 22. Stability ↔ Interoperability (M*, Production)
+
+Mutual tension. External dependencies (services, APIs, formats) introduce failure modes the project cannot directly control; isolated, stability-first systems often refuse interop because every external connection is a new failure surface. Bites at production, where third-party outages become operational concerns.
+
+#### 23. Stability ↔ Affordability ($, Production)
+
+Cost gravity. Stability work — testing, redundancy, monitoring, on-call — has substantial cost. Affordability constrains how much reliability investment a project can sustain. Bites at production, where the cost of unreliability and the cost of reliability are both measurable.
+
+#### 24. Stability ↔ Reality (S, PoC)
+
+Synergy mostly. Reality demands stability where stakes are real; the meta-virtue and the technical virtue point in the same direction. Mild tension only when reality says "ship now and stabilize later" because the cost of waiting outweighs the cost of bugs. Bites at PoC, where the "ship now" pressure is highest.
+
+### Pairs Centered on Urgency
+
+#### 25. Urgency ↔ Efficiency (M, Production)
+
+Mutual tension. Urgency leaves no time for optimization; efficiency work pushes against shipping deadlines. Bites at production, when the cost of inefficiency at scale finally exceeds the cost of slowing down to address it. Article-named.
+
+#### 26. Urgency ↔ Maintainability (M, Production)
+
+Mutual tension. Rushing produces technical debt; clean, maintainable patterns take longer to arrive at. Bites at production, where accumulated technical debt becomes the project's primary cost driver. Article-named.
+
+#### 27. Urgency ↔ Versatility (M*, Pilot)
+
+Mutual tension. Rushing leads to ignoring related use cases that would have informed a more versatile design; versatile design takes time to surface, name, and implement. Bites at pilot, when the project's scope-versus-deadline tradeoff is most consequential.
+
+#### 28. Urgency ↔ Interoperability (M, Production)
+
+Mutual tension. Rushing skips the study and integration of existing standards; interop work has substantial up-front cost that urgency budgets cannot afford. Bites at production, when standards-non-compliance produces real integration failures. Article-named.
+
+#### 29. Urgency ↔ Affordability ($, Pilot)
+
+Cost gravity. Urgency itself is expensive — overtime, rushed contractors, parallel workstreams. Affordability constrains how much urgency a project can fund. Bites at pilot, when burn rate and timeline first collide.
+
+#### 30. Urgency ↔ Reality (A, Production)
+
+Asymmetric grounding. Reality fights the tyranny of the urgent: not every urgent thing is actually urgent, and rushing on a false deadline costs everything else. Reality is not eroded by urgency; urgency is grounded by reality. Bites at production, where false urgency creates real damage. Article-named.
+
+### Pairs Centered on Efficiency
+
+#### 31. Efficiency ↔ Maintainability (M, Production)
+
+Mutual tension. Optimized code is harder to read; readable conventional code is often slower. Bites at production, when both performance and maintainability bills come due. Article-named.
+
+#### 32. Efficiency ↔ Versatility (M, Pilot)
+
+Mutual tension. Efficient code is shaped tightly to its expected workload; versatile code must accommodate workloads it was not optimized for. Bites at pilot, when the scope decision determines how tight the optimization can be. Article-named.
+
+#### 33. Efficiency ↔ Interoperability (M*, Production)
+
+Mutual tension. Interop overhead — serialization, format conversion, protocol negotiation — has real cost; high-performance systems often use proprietary protocols specifically to skip that overhead. Bites at production, where high-throughput meets standards compliance.
+
+#### 34. Efficiency ↔ Affordability (S, Production)
+
+Synergy. Efficiency is a primary mechanism for affordability — fewer cycles is fewer dollars. The two reinforce each other directly. Mild tension only when the engineering cost of an efficiency win exceeds the operational cost of running un-optimized. Bites at production, where unit economics become decisive.
+
+#### 35. Efficiency ↔ Reality (S, Pilot)
+
+Synergy. Reality demands that hardware and cloud bills get paid; efficiency answers. Mild tension only when reality says "ship before optimizing" because the optimization budget is better spent learning whether anyone wants the product. Bites at pilot, where the "premature optimization" failure mode is most expensive.
+
+### Pairs Centered on Maintainability
+
+#### 36. Maintainability ↔ Versatility (M*, Production)
+
+Mutual tension. Versatile code has more code paths to maintain; maintainable conventions often limit the shapes a versatile system can take. Bites at production, where both maintainability and versatility expectations compound.
+
+#### 37. Maintainability ↔ Interoperability (M*, Production)
+
+Mutual tension, mild. Interop layers add code surface area to maintain; well-chosen standards reduce interop complexity by externalizing the spec. The tension net depends on which standards are chosen. Bites at production.
+
+#### 38. Maintainability ↔ Affordability (S, Production)
+
+Synergy. Maintainability reduces technical debt, which reduces ongoing development cost. The two reinforce each other directly. Tension only when maintainability investment (refactoring, documentation, test infrastructure) exceeds the cost of accumulated debt at the project's current scale. Bites at production, where the cost of un-maintainable code compounds. Article-named (implicitly).
+
+#### 39. Maintainability ↔ Reality (S, Pilot)
+
+Synergy. Reality favors hireable, conventional, well-understood code; maintainability serves that. Tension only at PoCs where conventional code costs more than throwaway code. Bites at pilot/production, where the project commits to a maintenance future or accepts a rewrite.
+
+### Pairs Centered on Versatility
+
+#### 40. Versatility ↔ Interoperability (S, Production)
+
+Synergy mostly. Interoperability is itself a form of versatility — the ability to participate in adjacent workflows. The two reinforce each other. Mild tension only when interop standards limit what the project can express (e.g., a REST-only standard locks out streaming designs). Bites at production.
+
+#### 41. Versatility ↔ Affordability ($, Pilot)
+
+Cost gravity. Versatile design takes more time, more testing, and more code surface — all expensive. Affordability constrains how much versatility a project can afford. Bites at pilot, when scope and budget first negotiate.
+
+#### 42. Versatility ↔ Reality (A, Pilot)
+
+Asymmetric grounding. Reality limits versatility ambitions: it is rarely realistic to achieve broad versatility, and chasing it produces software that does many things badly. Reality is not eroded by versatility; versatility is grounded by reality. Bites at pilot, where scope ambition meets evidence about what users actually do. Article-named.
+
+### Pairs Centered on Interoperability
+
+#### 43. Interoperability ↔ Affordability ($, Pilot)
+
+Cost gravity. Interop work — protocol implementation, format conversion, partner integration — has direct cost. Affordability constrains how much interop a project can fund. Bites at pilot, when integration partner agreements are first scoped against budget.
+
+#### 44. Interoperability ↔ Reality (S, Pilot)
+
+Synergy. Reality favors integration with the tools users already have; interoperability answers. Mild tension only when interop ambitions outrun real user needs (building bridges to systems no one bridges to). Bites at pilot, when integration scope is decided.
+
+### Pair Centered on Affordability and Reality
+
+#### 45. Affordability ↔ Reality (S, all phases)
+
+Synergy. Affordability and reality are both grounding meta-virtues; they reinforce each other directly. Reality's costs/benefits/risks/dependencies/penalties/compliance lens IS, in operational terms, an affordability analysis. Tension only when the framings are mismatched (e.g., reality demands compliance investment that the affordability budget cannot sustain — at which point the project's viability is itself in question). Bites at all phases, since both operate continuously.
+
+---
+
+## How to Read the Matrix
+
+The matrix supports three primary uses:
+
+**Design review.** Before committing to a design, look up the pairs of virtues most affected by the choice. For each pair, name the predicted direction of erosion and decide whether the cost is acceptable for the project's current phase.
+
+**Disagreement diagnosis.** When a team disagrees about a tradeoff, the disagreement is often about which virtue is being prioritized rather than about facts. The matrix gives the disagreement a vocabulary: "you are prioritizing originality and accepting the predicted erosion of stability — at our current phase, is that the right call?"
+
+**Phase audit.** When a project moves between phases (PoC → Pilot → Production), the priorities shift. Use the phase tags to identify which tensions become more consequential at the new phase and which become less. Cross-reference with `odd/maturity.md` for the phase-by-phase weighting of the virtues themselves.
+
+---
+
+## What This Matrix Does Not Claim
+
+Three things the matrix is deliberately silent on:
+
+- **The relative weight of each virtue** — that is project-specific and phase-specific. The matrix names the directions of tension, not the priority ranking.
+- **The correct decision in any given case** — the matrix surfaces the costs of a choice; the choice itself is a judgment call that depends on the team's priorities and the project's phase.
+- **Completeness** — there are dozens of quality attributes beyond these ten (auditability, securability, debugability, deployability, recoverability, observability, portability, accessibility, localizability, and many more). A static matrix cannot scale to the full universe; the canonical ten are a worked example that demonstrates the shape. For a project that uses a different set, the principle at `canon/principles/quality-attributes-are-in-tension.md` holds — generate the tension graph for that set dynamically rather than treating this matrix as the master reference. See `canon/observations/observability-tension-extension.md` for one worked example of the extension pattern, applied to observability because ODD has rich existing canon to stitch from.
+
+---
+
+## Lineage
+
... diff truncated: showing 564 of 949 linesYou can send follow-ups to the cloud agent here.
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes and found 1 potential issue.
Bugbot Autofix prepared a fix for the issue found in the latest run.
- ✅ Fixed: Essay klappy:// URIs include .md breaking convention
- Removed the
.mdsuffix from all fourklappy://links inwritings/software-virtues-revisited.mdso they match the extensionless convention used throughout the codebase.
- Removed the
Preview (3c5aeff1ab)
diff --git a/canon/definitions/software-virtues-vocabulary.md b/canon/definitions/software-virtues-vocabulary.md
new file mode 100644
--- /dev/null
+++ b/canon/definitions/software-virtues-vocabulary.md
@@ -1,0 +1,132 @@
+---
+uri: klappy://canon/definitions/software-virtues-vocabulary
+title: "Software Virtues Vocabulary — Ten Quality Attributes That Compete for Priority"
+audience: canon
+exposure: nav
+tier: 2
+voice: neutral
+stability: stable
+tags: ["canon", "definitions", "software-virtues", "quality-attributes", "ilities", "prioritization", "tradeoffs"]
+epoch: E0008.4
+date: 2026-05-10
+derives_from: "https://medium.com/@klappy/what-are-software-virtues-and-how-to-prioritize-them-f0b583741afe (2018-09-09 — origin article)"
+complements: "canon/principles/quality-attributes-are-in-tension.md, canon/observations/quality-attribute-tension-matrix.md, odd/maturity.md"
+governs: "Vocabulary used across canon when discussing tradeoffs between competing software properties. 'Virtues' is the rhetorical/historical name; 'quality attributes' or 'ilities' is the operational synonym. Both are first-class."
+status: active
+---
+
+# Software Virtues Vocabulary — Ten Quality Attributes That Compete for Priority
+
+> Ten properties every software project optimizes for, in tension with each other: usability, originality, stability, urgency, efficiency, maintainability, versatility, interoperability, affordability, and reality. Each is a virtue (a thing worth pursuing) and a quality attribute (an "-ility" the engineering literature already names). Each stands in tension with others. Priority among them shifts by team, by project, and by lifecycle phase. The vocabulary is from a 2018 article that has stayed load-bearing for nearly a decade; this entry canonizes it for ODD. The ten are a canonical worked example, not an exhaustive set — the universe of quality attributes is far larger, and the principle holds across all of it.
+
+---
+
+## Summary — A Stable Naming for the Tradeoff Space
+
+Software has no single objective function. Every project optimizes for a bundle of competing properties, and every choice that advances one property tends to retreat from at least one other. The engineering literature names many of these properties — usually with the suffix "-ility" — and treats them as orthogonal axes. The 2018 source article reframed them as **virtues**: things worth pursuing, with intrinsic moral weight, that nevertheless conflict.
+
+This document defines the ten virtues that have proven generative across nearly a decade of use. The name "virtue" is preserved because the moral framing is load-bearing — these are not just metrics, they are values a team holds. The phrase "quality attribute" (or "-ility") is the operational synonym that integrates with industry vocabulary and ODD's existing language. Both names refer to the same set; canon documents may use either depending on register.
+
+The tensions among these virtues — which optimize against which, and under what conditions — are mapped at `canon/observations/quality-attribute-tension-matrix.md`. The principle that the tensions are real and irreducible is at `canon/principles/quality-attributes-are-in-tension.md`. The phase-by-phase shift in which virtues take priority is grounded in `odd/maturity.md`.
+
+---
+
+## The Ten Virtues
+
+Each virtue is named with its primary form first, followed by its companion synonym in the original article. The definition states what the virtue measures or rewards; the operational note states how it is observed in practice.
+
+### 1. Usability / Simplicity
+
+**Definition.** The degree to which the user can accomplish their intended task without unnecessary friction, training, or guesswork. Includes learnability (how quickly a new user becomes effective) and intuitiveness (how much the interface aligns with prior expectations).
+
+**Operational note.** Observed through user testing, time-to-task, error rates, and the volume of support requests asking how to do basic things. A product whose documentation is required to use it is failing on usability before the manual is opened.
+
+### 2. Originality / Innovation
+
+**Definition.** The degree to which the project does something not already done — a new approach, a new combination, a new affordance. Differentiation from existing alternatives; intrinsic novel value.
+
+**Operational note.** Observed through the question "what would have to be true elsewhere for this to be unnecessary?" If the honest answer is "nothing — there are five products that already do this," the project is not original.
+
+### 3. Stability / Reliability
+
+**Definition.** Two related properties often treated as one: stability (the system does not freeze, crash, or corrupt state) and reliability (when something goes wrong, the system recovers without losing the user's work). Either may dominate depending on the use case.
+
+**Operational note.** Observed through error rates, mean time between failures, recovery times, and the question "if a user trusts this with their work, will the trust be repaid?"
+
+### 4. Urgency / Timeliness
+
+**Definition.** The degree to which the project ships in time to serve its purpose. Urgency is not speed for its own sake; it is the temporal fit between the delivery and the window in which delivery still matters. Late software solving a no-longer-urgent problem has failed on this virtue.
+
+**Operational note.** Observed through schedule fit, market timing, and the question "if we ship six months from now, do users still need this?"
+
+### 5. Efficiency / Scalability
+
+**Definition.** The degree to which the system performs its work without wasted resources — CPU, memory, hardware, latency, energy, dollars. Scalability is the time-shape of efficiency: does the system stay efficient as load grows?
+
+**Operational note.** Observed through profiling, cost-per-request, throughput under load, and the question "what does it cost to serve the next user, and is that cost sustainable?"
+
+### 6. Maintainability / Manageability
+
+**Definition.** The degree to which the project can be continued by people who did not write it. Includes understandability (how readable the code is to a new contributor), modularity (whether parts can be changed independently), testability (whether changes can be verified before shipping), and hire-ability (whether the technologies and patterns chosen permit finding qualified maintainers).
+
+**Operational note.** Observed through onboarding time for new contributors, the rate at which untouched code becomes feared code, and the question "if the original team disappeared tomorrow, could the project continue?"
+
+### 7. Versatility / Adaptability
+
+**Definition.** The breadth of use cases the project can serve without modification. The degree to which the project handles related tasks beyond its primary one. The opposite of single-purpose narrowness.
+
+**Operational note.** Observed through the variety of users finding value in the project and the rate at which feature requests are answered with "actually, you can already do that." Watch for the failure mode: versatility chased prematurely produces software that does many things badly instead of one thing well.
+
+### 8. Interoperability
+
+**Definition.** The degree to which the project can exchange data and behavior with adjacent systems. Includes import/export of data formats, adherence to standards, API surface area, and the absence of artificial lock-in.
+
+**Operational note.** Observed through the friction a user experiences when bringing data in or taking data out, and the question "does this project make the user's larger workflow easier or harder?"
+
+### 9. Affordability / Sustainability
+
+**Definition.** Two coupled properties: affordability (the price the user pays is appropriate to the value received) and sustainability (the cost of building and operating the project is sustainable for the team that produces it). The intersection is whether the project's economic model survives contact with reality.
+
+**Operational note.** Observed through unit economics, retention, runway, and the question "can the team that built this afford to keep building it?" Affordability has cost gravity over every other virtue: each virtue is purchased with effort or money.
+
+### 10. Reality
+
+**Definition.** The meta-virtue that grounds all other virtues against the world as it is, rather than the world as planned. Reality includes:
+
+- **Costs** — effort and resources actually required
+- **Benefits** — advantages of success, weighted by probability
+- **Risks** — probability of failure and its consequences
+- **Dependencies** — what must be true for this to work
+- **Penalties** — consequences of not delivering
+- **Compliance** — regulatory and contractual constraints
+
+**Operational note.** Observed through the gap between stated plans and observed outcomes. Reality is the virtue that keeps the other nine honest. When teams optimize for usability without testing with real users, for originality without checking what already exists, or for urgency without checking what users actually need, reality has been demoted below where it belongs.
+
+---
+
+## "Virtues" and "Quality Attributes" Are the Same Set
+
+The 2018 source article called these virtues. The engineering literature calls them quality attributes, non-functional requirements, or "-ilities" (a suffix that fits most of them awkwardly). Both vocabularies refer to the same ten properties.
+
+Canon uses both names depending on register:
+
+- **Virtue** — moral, rhetorical, used when emphasizing that these are values a team chooses to pursue
+- **Quality attribute / "-ility"** — operational, technical, used when integrating with industry frameworks (ISO/IEC 25010, ATAM, etc.) or when discussing measurement and tradeoff analysis
+
+Neither vocabulary is preferred. A canon document discussing prioritization may use "virtues" for the framing and "quality attributes" for the worked detail without contradiction.
+
+---
+
+## What This Document Does Not Define
+
+Three things deliberately left to other canon documents:
+
+- **Which virtues take priority when** — see `odd/maturity.md` for phase-weighting and `canon/observations/quality-attribute-tension-matrix.md` for pair-by-pair detail across the canonical ten.
+- **How to elicit team priorities** — the 2018 article suggested MoSCoW voting and the Hundred Dollar Method. Both are surfaced as starting points, not endorsed as load-bearing. ODD's mature answer to elicitation lives elsewhere.
+- **The full universe of quality attributes** — there are dozens more. Auditability, securability, debugability, deployability, recoverability, observability, portability, accessibility, localizability, and many others are real. The ten here are the canonical worked example used as a reference corpus; the principle at `canon/principles/quality-attributes-are-in-tension.md` holds across the broader set, and project-specific tension graphs are generated against the principle rather than restricted to this list.
+
+---
+
+## Lineage
+
+The vocabulary is from "Software Virtues — How to Prioritize" by Chris Klapp, published on Medium in September 2018. The article seeded `odd/maturity.md` (phase-weighting) and is now the source of this definition. The companion canon — the in-tension principle and the worked-example tension matrix — completes the systematic build the original article only sketched.
diff --git a/canon/observations/observability-tension-extension.md b/canon/observations/observability-tension-extension.md
new file mode 100644
--- /dev/null
+++ b/canon/observations/observability-tension-extension.md
@@ -1,0 +1,138 @@
+---
+uri: klappy://canon/observations/observability-tension-extension
+title: "Observability Tension Extension — One Worked Example of Extending the Matrix from ODD's Existing Canon"
+audience: canon
+exposure: nav
+tier: 2
+voice: neutral
+stability: stable
+tags: ["canon", "observations", "quality-attributes", "software-virtues", "tradeoffs", "tensions", "observability", "extension", "matrix-extension", "epoch-8"]
+epoch: E0008.4
+date: 2026-05-10
+derives_from: "canon/principles/quality-attributes-are-in-tension.md, canon/observations/quality-attribute-tension-matrix.md, canon/definitions/software-virtues-vocabulary.md, canon/case-studies/catalog-observability-gap.md, docs/appendices/epoch-8.md, docs/appendices/epoch-8-2.md, docs/appendices/epoch-8-3.md, canon/values/axioms.md"
+complements: "odd/maturity.md"
+governs: "Reference for the tensions between observability and the canonical ten quality attributes. Demonstrates the extension pattern: when an ility has rich canon support, its tensions are stitched from existing canon rather than re-derived. Same shape applies to other ilities (auditability, securability, accessibility, etc.) when they earn their own extension docs."
+status: active
+---
+
+# Observability Tension Extension — One Worked Example of Extending the Matrix from ODD's Existing Canon
+
+> Observability earns its own extension because ODD has been writing about it for an entire epoch already. This document maps observability's tensions against the canonical ten — ten new pairs, each grounded in either the catalog-observability-gap case study or the Epoch 8 / 8.2 / 8.3 appendices. The point is not just observability; it is the *pattern*. When an ility already has canon, its tension graph stitches from that canon. The eventual dynamic-generation method generalizes this pattern; this doc demonstrates what one well-grounded extension looks like by hand.
+
+---
+
+## Summary — Observability Joins the Tension Graph with Its Canon Already Written
+
+Observability is not a new ility. ODD has lived inside it for an entire epoch — `klappy://docs/appendices/epoch-8` (Observability: Transparent Telemetry and Infrastructure Accountability), `klappy://docs/appendices/epoch-8-2` (Put the Clock in the Room), `klappy://docs/appendices/epoch-8-3` (Validation as Observable Mode), and the case study at `klappy://canon/case-studies/catalog-observability-gap` (When the Knowledge Server Cannot See Its Own Knowledge Base). Observability's tensions with the canonical ten are therefore not derived from intuition; they are stitched from canon already written.
+
+This document does that stitching for one ility as a worked example of the broader extension pattern. The pattern: when a project's quality attributes include something beyond the canonical ten, the tensions are not generated from nothing — they are pulled from existing canon where it exists, and from the principle (`canon/principles/quality-attributes-are-in-tension.md`) where canon is silent.
+
+The principle itself is unchanged. The matrix at `canon/observations/quality-attribute-tension-matrix.md` is unchanged. Observability is not promoted into the canonical set; the canonical ten stays canonical. This extension is the eleventh node added off to the side, with edges back to each of the ten and citations to the canon evidence for each edge.
+
+---
+
+## Definition — Observability in ODD
+
+**Definition.** The degree to which the system makes its own state legible to those who need to act on it. In ODD specifically, observability is the structural property that lets the model, the operator, and the team observe what the system is actually doing rather than what they think it is doing. Includes telemetry (what calls happened), state visibility (what the system thinks now), process visibility (what mode it is in, what gates have fired), and infrastructure accountability (what the runtime is actually charging in cycles, bytes, dollars).
+
+**Operational note.** Observed by asking three questions and answering them with primary evidence rather than reasoning: (1) Did the action that the system claims happened actually happen? (2) What did it cost? (3) What state is the system in right now? If those questions cannot be answered without rebuilding the answer from inference, observability has failed regardless of what telemetry pipelines exist.
+
+**Why observability is not in the canonical ten.** The 2018 article was written before observability was load-bearing for the kind of work ODD orchestrates. The canonical ten still apply to most projects; observability becomes critical specifically when the work is autonomous, agent-driven, or otherwise not directly supervised by humans who can spot-check by intuition. ODD's E0008 arc was the moment observability moved from optional engineering hygiene to structural requirement.
+
+---
+
+## Observability and the Observation Encoding Type Are Siblings Under Axiom 4
+
+There is a deeper structural reason observability earns its own extension before any of the other ilities ODD might absorb. It is the system-level expression of an axiom ODD already operationalizes at the session level. The two faces share parentage; naming the parallel makes the canon's underlying architecture visible.
+
+**At the session level**, ODD operationalizes Axiom 4 ("You Cannot Verify What You Did Not Observe") through the `O` encoding type in DOLCHEO — see `klappy://odd/encoding-types/observation`. An Observation captures what was seen during work, separated from what it means. "The deploy took 47 seconds" is an observation; "the deploy is too slow" is a Learning. Keeping the layers separate is what makes the rest of the framework — Decisions, Learnings, Constraints — defensible. Observations that nobody recorded are, in the encoding doc's phrasing, observations that never happened for the system's purposes.
+
+**At the runtime system level**, observability — the quality attribute mapped in this extension — is the same discipline applied to the system's own operation. The system reports its state in primary form (telemetry, traces, structured logs) rather than requiring its operators to infer state from secondary signals. Stability, maintainability, and debugability all build on top. A system that nobody can observe is, structurally, a system whose claims about its own behavior cannot be verified.
+
+**The two failure modes are the same.** When the catalog-observability-gap case study (`klappy://canon/case-studies/catalog-observability-gap`) names oddkit serving 500+ documents while its primary interface could only retrieve 196, that is the runtime-system version of an unrecorded observation: the team had a model of the system's behavior that the system itself had no way to corroborate. The Observation encoding type exists to prevent the same failure at the session scale, where a team can hold a confident interpretation of work that was never grounded in recorded evidence.
+
+**The two principles reinforce each other.** Sessions that capture rich Observations are sessions that produce defensible Learnings, Decisions, and Constraints. Systems that are richly observable are systems whose stability, maintainability, and debugability are defensible. Both stand or fall on the same axiom: claims unsupported by observation are debts the system carries until something forces them to be paid.
+
+This sibling relationship is why this extension was the first one written. Other ilities — auditability, securability, accessibility, portability — will earn their own extensions as projects need them and as ODD canon accumulates. Observability earns its place at the front of the queue because the parallel is already explicit in the canon's foundations, and naming the parallel strengthens both faces of it.
+
+---
+
+## Tensions Between Observability and the Canonical Ten
+
+Each entry: relationship type, phase weighting, operating dynamic, and the canon evidence for the claim.
+
+### Observability ↔ Usability (M*, Production)
+
+Mild mutual tension. Rich instrumentation surfaces — dashboards, traces, logs — complicate the user-facing UX surface and pull cognitive budget from the primary task. Conversely, observability into how users actually use the product is what *reveals* usability problems that would otherwise stay invisible. Net is mildly tense in production when instrumentation surfaces compete with task surfaces; net is positive at pilot when usage telemetry informs UX iteration.
+
+*Canon evidence.* The catalog-observability-gap case study (`klappy://canon/case-studies/catalog-observability-gap`) is the worked example where observability into how the catalog was *used* surfaced a usability/correctness problem the implementation team had not seen.
+
+### Observability ↔ Originality (M*, Pilot)
+
+Asymmetric mutual tension. You instrument what you already understand; truly novel mechanisms resist instrumentation because their failure modes are not yet named. Originality-first projects often defer observability ("we do not yet know what to measure"), and observability-first projects often shape the design to fit existing telemetry primitives, foreclosing some originality. Bites at pilot, when the original idea is being made operationally legible for the first time.
+
+*Canon evidence.* `klappy://docs/appendices/epoch-8-3` (Validation as Observable Mode) is the moment ODD turned its lens on its own process and found that the original epistemic-modes idea needed to be re-shaped for legibility — the originality of "validation as a distinct mode" required new observability primitives, not just rewiring the existing ones.
+
+### Observability ↔ Stability (S, Production)
+
+Strong synergy. Observability is the primary mechanism by which stability is achieved — you cannot fix what you cannot see. Tension only when instrumentation itself becomes a stability hazard (telemetry pipelines that fall over and take the host system with them). Bites at production, where both expectations are highest and where instrumentation reliability becomes a first-class concern.
+
+*Canon evidence.* `klappy://docs/appendices/epoch-8` opens with the framing that infrastructure observability is what makes stability claims falsifiable; stability without observability is a claim, not evidence.
+
+### Observability ↔ Urgency (M, Production)
+
+Mutual tension. Urgency-driven projects routinely skip telemetry; the absence of telemetry then forces urgency-mode debugging when things break in production. The cycle reinforces itself. Bites hardest at production, where the cost of un-observability is paid in compounded incident response time.
+
+*Canon evidence.* The catalog-observability-gap case study (`klappy://canon/case-studies/catalog-observability-gap`) explicitly names the urgency-skipping pattern: oddkit shipped without the consumer-pagination contract that would have made the gap immediately visible; the urgency cost was paid later in operator confusion and a production smoke that took hours to interpret.
+
+### Observability ↔ Efficiency (M, Production)
+
+Mutual tension, direct and measurable. Telemetry has cost: bytes on the wire, cycles in the worker, storage in the analytics engine, dashboards to maintain. Efficient systems often run lean on observation by design. The reverse tension is real too: optimizing without observability is optimizing in the dark, and many efficiency wins come from having seen the bottleneck. Bites at production, where both the cost of telemetry and the cost of inefficiency are simultaneously measurable.
+
+*Canon evidence.* `klappy://docs/appendices/epoch-8` introduces the Analytics Engine architecture specifically because earlier observability designs had unacceptable efficiency costs; the architectural choice was driven by the tension itself.
+
+### Observability ↔ Maintainability (S, Production)
+
+Strong synergy. Observable code is maintainable code — a new contributor reading a system with rich tracing and structured logs can answer "what does this actually do" in minutes rather than hours. The tension is mild and only at extremes: instrumentation libraries themselves can become a maintenance burden, especially when the project is small enough that the telemetry surface exceeds the business-logic surface.
+
+*Canon evidence.* `klappy://docs/appendices/epoch-8-2` (Put the Clock in the Room) is a case where adding one observability primitive (`server_time` in every response) directly reduced maintenance load — the model stops fabricating elapsed times, stops getting them wrong, and stops requiring operator correction.
+
+### Observability ↔ Versatility (M*, Production)
+
+Mild mutual tension. Versatile systems have more code paths and more states; instrumenting all of them is more work, and partial instrumentation often misses the rare paths that produce the rare bugs. Conversely, versatile-and-observable systems become complex enough that the observability surface itself becomes hard to navigate. Bites at production where both versatility and observability ambitions compound.
+
+*Canon evidence.* The catalog-observability-gap case study (`klappy://canon/case-studies/catalog-observability-gap`) hit exactly this — oddkit's versatility (serving 500+ docs across multiple consumer shapes) combined with partial observability of consumer behavior produced a gap the team did not see until a consumer surfaced it.
+
+### Observability ↔ Interoperability (S, Production)
+
+Synergy mostly. Interoperable systems benefit from observability that crosses system boundaries — distributed tracing, correlation IDs, OpenTelemetry-class standards. The integration *is* the observability work in many cases. Tension only when proprietary observability primitives conflict with interop standards (e.g., a vendor-specific tracing protocol that does not propagate across partner boundaries). Bites at production.
+
+*Canon evidence.* `klappy://docs/appendices/epoch-8` documents the choice to use Cloudflare Analytics Engine — a non-portable substrate — and the deliberate decision to accept the interop cost in exchange for the efficiency-and-affordability win. The decision is recorded as a tension explicitly accepted, not avoided.
+
+### Observability ↔ Affordability ($, Production)
+
+Cost gravity. Telemetry has direct ongoing cost: ingestion fees, storage tiers, dashboard licenses, on-call rotations to interpret what the dashboards show. Affordability constrains how much observability investment a project can sustain. Bites at production, where the recurring monthly cost of observation becomes a line item.
+
+*Canon evidence.* `klappy://docs/appendices/epoch-8` names this directly: the choice of Analytics Engine over alternatives was driven by affordability; the choice of `SUM(_sample_interval)` aggregation rather than per-event storage was driven by the same constraint.
+
+### Observability ↔ Reality (S, all phases)
+
+Strong synergy. This is the foundational pair. Axiom 4 (`canon/values/axioms.md` — "You Cannot Verify What You Did Not Observe") is the principle stated as a value; observability is the technical means by which the value becomes operative. Reality demands that the team observe what is actually happening; observability answers that demand. Tension only when the cost of observation itself outpaces what reality provides in return — i.e., when over-instrumentation becomes its own reality-distortion. Bites at all phases, since both operate continuously.
+
+*Canon evidence.* `klappy://canon/values/axioms.md` (Axiom 4) is the value statement; the entire E0008 arc (`klappy://docs/appendices/epoch-8`, `epoch-8-2`, `epoch-8-3`) is its operationalization. The catalog-observability-gap case study is a worked failure mode where the axiom was held in principle and violated in practice — the system made claims about its knowledge base that the system itself had no way to verify.
+
+---
+
+## How to Read This Extension
+
+The extension follows the same shape as the matrix: each pair has a relationship type, a phase tag, an operating dynamic, and (new in extensions) an explicit *canon evidence* citation pointing at the document or epoch where ODD has already lived this tension.
+
+The citation requirement is not decoration. It is the structural reason this extension is useful: every claim in this document is grounded in canon written for other reasons, in some cases years ago. The extension is not asserting new tensions; it is *naming* tensions ODD has already paid the cost of learning, and making them retrievable in the same shape as the canonical ten.
+
+When the matrix is extended further — auditability, securability, accessibility, portability — the pattern holds. The extension is cheap when the canon already exists. The extension is principle-grounded when canon is silent. The extension never re-opens the canonical ten.
+
+---
+
+## Lineage
+
+Observability is the first extension because ODD has the deepest existing canon on it. The case study at `klappy://canon/case-studies/catalog-observability-gap` and the three epoch appendices (`klappy://docs/appendices/epoch-8`, `epoch-8-2`, `epoch-8-3`) constitute roughly half a year of accumulated thinking that this extension stitches into the tension-graph format. Future extensions for other ilities will follow the same template — definition tight enough for canon, ten new pair entries, citations to existing canon where it exists, principle-grounded reasoning where canon is silent. The eventual method doc at `canon/methods/quality-attribute-tension-survey` (forthcoming) will operationalize this stitching dynamically; this extension is the worked example demonstrating what good output looks like.
diff --git a/canon/observations/quality-attribute-tension-matrix.md b/canon/observations/quality-attribute-tension-matrix.md
new file mode 100644
--- /dev/null
+++ b/canon/observations/quality-attribute-tension-matrix.md
@@ -1,0 +1,294 @@
+---
+uri: klappy://canon/observations/quality-attribute-tension-matrix
+title: "Quality Attribute Tension Matrix — All Forty-Five Pairs Across Ten Virtues, Phase-Weighted"
+audience: canon
+exposure: nav
+tier: 2
+voice: neutral
+stability: stable
+tags: ["canon", "observations", "quality-attributes", "software-virtues", "tradeoffs", "tensions", "matrix", "phase-weighting", "ilities"]
+epoch: E0008.4
+date: 2026-05-10
+derives_from: "canon/definitions/software-virtues-vocabulary.md, canon/principles/quality-attributes-are-in-tension.md, odd/maturity.md, https://medium.com/@klappy/what-are-software-virtues-and-how-to-prioritize-them-f0b583741afe"
+complements: "canon/values/axioms.md"
+governs: "Reference for which quality attributes are in tension with which, the type and direction of each tension, and the project phase at which each tension bites hardest. Used during prioritization, design review, and tradeoff analysis."
+status: active
+---
+
+# Quality Attribute Tension Matrix — All Forty-Five Pairs Across Ten Virtues, Phase-Weighted
+
+> A worked example of the tension graph across the canonical ten quality attributes: forty-five unique pairs, each tagged with relationship type (mutual tension / asymmetric grounding / synergy / cost gravity), direction (which virtue erodes which), and the project phase at which the tension bites hardest (PoC / Pilot / Production). Twenty-one of the pairs are named in the 2018 source article; twenty-four are filled in here for the first time. The matrix demonstrates the shape the tension survey produces — it is not the master reference. The universe of quality attributes is far larger than ten; this document is the corpus that shows what good looks like when the principle at `canon/principles/quality-attributes-are-in-tension.md` is applied.
+
+---
+
+## Summary — A Worked Example of the Tension Graph for the Canonical Ten
+
+Every design decision moves at least one quality attribute up and at least one other down. The principle at `canon/principles/quality-attributes-are-in-tension.md` asserts that the moves are not random and that this holds for any set of quality attributes. This document maps the canonical ten as a worked example: which virtue erodes which, in which direction, and at which project phase the erosion is most consequential.
+
+The matrix uses four relationship types:
+
+- **Mutual tension (M)** — both virtues erode the other. Optimizing for one reliably costs the other.
+- **Asymmetric grounding (A)** — one virtue disciplines the other without symmetric retaliation. The grounding virtue (usually reality) does not get eroded by what it constrains.
+- **Synergy (S)** — both virtues reinforce each other, with mild tension only at extremes. Pursuing one tends to advance the other.
+- **Cost gravity ($)** — affordability's relationship with every other virtue: each virtue is purchased with effort, time, or money, so affordability constrains how much of each can be afforded.
+
+Phase weighting follows the three-level maturity model from `odd/maturity.md`:
+
+- **PoC** (Level 0 — exploration, learning) — tension bites when the team has not yet decided whether the idea is worth pursuing.
+- **Pilot** (Level 1 — pilot/product) — tension bites when the project has real users but has not yet committed to long-term operation.
+- **Production** (Level 2 — production / long-term) — tension bites when the project is committed to ongoing operation under real load.
+
+Most tensions bite at one phase more than the others. A single phase tag per cell names where the tension is sharpest; secondary phases are noted where the bite is broad.
+
+---
+
+## Compact Reference — The 10×10 Grid
+
+Quick-reference grid. Lower-left triangle is filled (each pair appears once). Reading: row virtue's relationship to column virtue.
+
+| | Use | Orig | Stab | Urg | Eff | Maint | Vers | Inter | Aff | Real |
+|--------------|:---:|:----:|:----:|:---:|:---:|:-----:|:----:|:-----:|:---:|:----:|
+| **Use**ability | · | | | | | | | | | |
+| **Orig**inality | M | · | | | | | | | | |
+| **Stab**ility | M* | M | · | | | | | | | |
+| **Urg**ency | M | M* | M | · | | | | | | |
+| **Eff**iciency | M* | M* | M* | M | · | | | | | |
+| **Maint**ain | M* | M* | S | M | M | · | | | | |
+| **Vers**atility | M | M* | M* | M* | M | M* | · | | | |
+| **Inter**op | M* | M | M* | M | M* | M* | S | · | | |
+| **Aff**ordability | $ | $ | $ | $ | S | S | $ | $ | · | |
+| **Real**ity | A | A | S | A | S | S | A | S | S | · |
+
+Legend: M = mutual tension (named in 2018 article). M* = mutual tension (filled in here). A = asymmetric grounding. S = synergy. $ = cost gravity. · = self.
+
+---
+
+## The Forty-Five Pairs
+
+Each entry: relationship type, direction (if asymmetric), bite phase, and the operating dynamic. Pairs are ordered by row index then column index from the grid above.
+
+### Pairs Centered on Usability
+
+#### 1. Usability ↔ Originality (M, Pilot)
+
+Mutual tension. New innovative features are rarely understood well enough to be made simple at first; usability requires patterns the user already recognizes, and originality means breaking those patterns. Bites hardest at pilot phase, when the original idea must reach actual users. Article-named.
+
+#### 2. Usability ↔ Stability (M*, Pilot)
+
+Mutual tension, mild. Polish for usability sometimes hides instability under aesthetics ("looks finished, breaks under edge cases"); defensive stability code can produce confirmation dialogs and error states that erode usability. The tension is subtle but real at pilot when the product first touches users who do not know the workarounds.
+
+#### 3. Usability ↔ Urgency (M, Production)
+
+Mutual tension. Rushing to ship leaves no time for user testing or interface refinement; user testing and refinement take time. Bites at production, where the cost of unusable software is paid in support load and churn. Article-named.
+
+#### 4. Usability ↔ Efficiency (M*, Pilot)
+
+Mutual tension, mild. Beautifully usable interfaces often involve animations, transitions, and helpful intermediate states that cost cycles; efficient backends sometimes dictate workflows that are technically correct but cognitively awkward. Bites at pilot when the product targets devices or networks where efficiency limits are felt.
+
+#### 5. Usability ↔ Maintainability (M*, Production)
+
+Mutual tension. Usability features add code paths (undo stacks, helpful errors, accessibility affordances) that increase the code surface; maintainable, conventional code structures sometimes resist the special-casing that good UX demands. Bites at production, where the maintenance cost of a usability-rich product compounds.
+
+#### 6. Usability ↔ Versatility (M, Pilot)
+
+Mutual tension. Versatility invites ambiguity that may undermine intuitiveness — software that does many things must offer choices, and choices erode the "one obvious way" that drives intuitive usability. Bites at pilot, when the product's scope is being negotiated against real-user friction. Article-named.
+
+#### 7. Usability ↔ Interoperability (M*, Pilot)
+
+Mutual tension. Interop layers expose options (which format to export, which provider to integrate with) that complicate the UX surface; UX that wants to feel decisive sometimes hides interop choices behind opinionated defaults that limit interoperability. Bites at pilot, when integration partners are negotiated.
+
+#### 8. Usability ↔ Affordability ($, Pilot)
+
+Cost gravity. Usability work — testing, iteration, design talent — has direct cost. Affordability constrains how much UX investment a project can sustain. Bites at pilot, when the unit economics of the product are first measured against the design budget.
+
+#### 9. Usability ↔ Reality (A, PoC)
+
+Asymmetric grounding. Reality keeps usability ambitions honest: an interface that tests well with the wrong user base is not usable with the right one. Reality is not eroded by usability; usability is grounded by reality. Bites at PoC, where unrealistic user assumptions are cheapest to correct.
+
+### Pairs Centered on Originality
+
+#### 10. Originality ↔ Stability (M, Pilot)
+
+Mutual tension. Innovative approaches are inherently less battle-tested; stability requires patterns whose failure modes are known. Bites at pilot, when the original idea is exposed to the variability of real-world conditions. Article-named.
+
+#### 11. Originality ↔ Urgency (M*, Pilot)
+
+Mutual tension, asymmetric in flavor. Urgency forces shortcuts that look like originality but are actually hurried imitation; genuine originality requires the time to discover what is actually new. Bites at pilot, when the "are we actually doing something new or just shipping fast" question becomes answerable.
+
+#### 12. Originality ↔ Efficiency (M*, Production)
+
+Mutual tension. Novel approaches usually arrive less optimized than the patterns they replace; efficiency-first design often forecloses the experimental routes that produce originality. Bites at production, where the cost of novel-but-slow becomes operational.
+
+#### 13. Originality ↔ Maintainability (M*, Production)
+
+Mutual tension. Novel patterns are harder to hire for and harder to onboard against; maintainable conventions limit the shapes a novel approach can take. Bites at production, where the team must scale beyond the founders who understood the novelty natively.
+
+#### 14. Originality ↔ Versatility (M*, Pilot)
+
+Mutual tension, mild. Strong novel ideas are usually highly specific to a narrow problem; versatility-first design rarely produces deep originality. Bites at pilot, when the project must decide whether to deepen its novel angle or widen its applicability.
+
+#### 15. Originality ↔ Interoperability (M, Pilot)
+
+Mutual tension. Interop with existing systems requires conformance to existing standards, which forecloses some innovations; pure innovation often produces formats and protocols that the rest of the ecosystem cannot read. Bites at pilot, when integration with the user's existing workflow is negotiated. Article-named.
+
+#### 16. Originality ↔ Affordability ($, Pilot)
+
+Cost gravity. Innovation is expensive — research, dead ends, prototypes that do not ship. Affordability constrains how much novelty a project can afford. Bites at pilot, when the runway shape is first matched against the experimentation budget.
+
+#### 17. Originality ↔ Reality (A, PoC)
+
+Asymmetric grounding. Reality limits originality by reminding the team what is already done, what physics permits, and what users actually want. Reality is not eroded by originality; originality is grounded (sometimes harshly) by reality. Bites at PoC, where unrealistic novelty is cheapest to redirect. Article-named.
+
+### Pairs Centered on Stability
+
+#### 18. Stability ↔ Urgency (M, Production)
+
+Mutual tension. Rushing increases the rate of bugs; thorough stabilization takes time the urgency budget does not have. Bites at production, where instability translates directly to user trust erosion. Article-named.
+
+#### 19. Stability ↔ Efficiency (M*, Production)
+
+Mutual tension. Hyper-optimization sometimes introduces instability (race conditions, edge-case overflow, brittle assumptions); defensive stability code adds overhead that erodes efficiency. Bites at production, where both stability and efficiency expectations are highest.
+
+#### 20. Stability ↔ Maintainability (S, Production)
+
+Synergy. Both stability and maintainability favor clean, predictable code with known failure modes. Mild tension only when "stable" code becomes "untouchable" — the legacy system whose stability comes from no one daring to change it. Bites at production, when the system is mature enough for legacy patterns to set in.
+
+#### 21. Stability ↔ Versatility (M*, Pilot)
+
+Mutual tension. Versatile code has more states, more code paths, and more configurations to test — making stabilization harder; stable code is often stable because its scope is narrow. Bites at pilot, when the scope-versus-reliability tradeoff is being negotiated.
+
+#### 22. Stability ↔ Interoperability (M*, Production)
+
+Mutual tension. External dependencies (services, APIs, formats) introduce failure modes the project cannot directly control; isolated, stability-first systems often refuse interop because every external connection is a new failure surface. Bites at production, where third-party outages become operational concerns.
+
+#### 23. Stability ↔ Affordability ($, Production)
+
+Cost gravity. Stability work — testing, redundancy, monitoring, on-call — has substantial cost. Affordability constrains how much reliability investment a project can sustain. Bites at production, where the cost of unreliability and the cost of reliability are both measurable.
+
+#### 24. Stability ↔ Reality (S, PoC)
+
+Synergy mostly. Reality demands stability where stakes are real; the meta-virtue and the technical virtue point in the same direction. Mild tension only when reality says "ship now and stabilize later" because the cost of waiting outweighs the cost of bugs. Bites at PoC, where the "ship now" pressure is highest.
+
+### Pairs Centered on Urgency
+
+#### 25. Urgency ↔ Efficiency (M, Production)
+
+Mutual tension. Urgency leaves no time for optimization; efficiency work pushes against shipping deadlines. Bites at production, when the cost of inefficiency at scale finally exceeds the cost of slowing down to address it. Article-named.
+
+#### 26. Urgency ↔ Maintainability (M, Production)
+
+Mutual tension. Rushing produces technical debt; clean, maintainable patterns take longer to arrive at. Bites at production, where accumulated technical debt becomes the project's primary cost driver. Article-named.
+
+#### 27. Urgency ↔ Versatility (M*, Pilot)
+
+Mutual tension. Rushing leads to ignoring related use cases that would have informed a more versatile design; versatile design takes time to surface, name, and implement. Bites at pilot, when the project's scope-versus-deadline tradeoff is most consequential.
+
+#### 28. Urgency ↔ Interoperability (M, Production)
+
+Mutual tension. Rushing skips the study and integration of existing standards; interop work has substantial up-front cost that urgency budgets cannot afford. Bites at production, when standards-non-compliance produces real integration failures. Article-named.
+
+#### 29. Urgency ↔ Affordability ($, Pilot)
+
+Cost gravity. Urgency itself is expensive — overtime, rushed contractors, parallel workstreams. Affordability constrains how much urgency a project can fund. Bites at pilot, when burn rate and timeline first collide.
+
+#### 30. Urgency ↔ Reality (A, Production)
+
+Asymmetric grounding. Reality fights the tyranny of the urgent: not every urgent thing is actually urgent, and rushing on a false deadline costs everything else. Reality is not eroded by urgency; urgency is grounded by reality. Bites at production, where false urgency creates real damage. Article-named.
+
+### Pairs Centered on Efficiency
+
+#### 31. Efficiency ↔ Maintainability (M, Production)
+
+Mutual tension. Optimized code is harder to read; readable conventional code is often slower. Bites at production, when both performance and maintainability bills come due. Article-named.
+
+#### 32. Efficiency ↔ Versatility (M, Pilot)
+
+Mutual tension. Efficient code is shaped tightly to its expected workload; versatile code must accommodate workloads it was not optimized for. Bites at pilot, when the scope decision determines how tight the optimization can be. Article-named.
+
+#### 33. Efficiency ↔ Interoperability (M*, Production)
+
+Mutual tension. Interop overhead — serialization, format conversion, protocol negotiation — has real cost; high-performance systems often use proprietary protocols specifically to skip that overhead. Bites at production, where high-throughput meets standards compliance.
+
+#### 34. Efficiency ↔ Affordability (S, Production)
+
+Synergy. Efficiency is a primary mechanism for affordability — fewer cycles is fewer dollars. The two reinforce each other directly. Mild tension only when the engineering cost of an efficiency win exceeds the operational cost of running un-optimized. Bites at production, where unit economics become decisive.
+
+#### 35. Efficiency ↔ Reality (S, Pilot)
+
+Synergy. Reality demands that hardware and cloud bills get paid; efficiency answers. Mild tension only when reality says "ship before optimizing" because the optimization budget is better spent learning whether anyone wants the product. Bites at pilot, where the "premature optimization" failure mode is most expensive.
+
+### Pairs Centered on Maintainability
+
+#### 36. Maintainability ↔ Versatility (M*, Production)
+
+Mutual tension. Versatile code has more code paths to maintain; maintainable conventions often limit the shapes a versatile system can take. Bites at production, where both maintainability and versatility expectations compound.
+
+#### 37. Maintainability ↔ Interoperability (M*, Production)
+
+Mutual tension, mild. Interop layers add code surface area to maintain; well-chosen standards reduce interop complexity by externalizing the spec. The tension net depends on which standards are chosen. Bites at production.
+
+#### 38. Maintainability ↔ Affordability (S, Production)
+
+Synergy. Maintainability reduces technical debt, which reduces ongoing development cost. The two reinforce each other directly. Tension only when maintainability investment (refactoring, documentation, test infrastructure) exceeds the cost of accumulated debt at the project's current scale. Bites at production, where the cost of un-maintainable code compounds. Article-named (implicitly).
+
+#### 39. Maintainability ↔ Reality (S, Pilot)
+
+Synergy. Reality favors hireable, conventional, well-understood code; maintainability serves that. Tension only at PoCs where conventional code costs more than throwaway code. Bites at pilot/production, where the project commits to a maintenance future or accepts a rewrite.
+
+### Pairs Centered on Versatility
+
+#### 40. Versatility ↔ Interoperability (S, Production)
+
+Synergy mostly. Interoperability is itself a form of versatility — the ability to participate in adjacent workflows. The two reinforce each other. Mild tension only when interop standards limit what the project can express (e.g., a REST-only standard locks out streaming designs). Bites at production.
+
+#### 41. Versatility ↔ Affordability ($, Pilot)
+
+Cost gravity. Versatile design takes more time, more testing, and more code surface — all expensive. Affordability constrains how much versatility a project can afford. Bites at pilot, when scope and budget first negotiate.
+
+#### 42. Versatility ↔ Reality (A, Pilot)
+
+Asymmetric grounding. Reality limits versatility ambitions: it is rarely realistic to achieve broad versatility, and chasing it produces software that does many things badly. Reality is not eroded by versatility; versatility is grounded by reality. Bites at pilot, where scope ambition meets evidence about what users actually do. Article-named.
+
+### Pairs Centered on Interoperability
+
+#### 43. Interoperability ↔ Affordability ($, Pilot)
+
+Cost gravity. Interop work — protocol implementation, format conversion, partner integration — has direct cost. Affordability constrains how much interop a project can fund. Bites at pilot, when integration partner agreements are first scoped against budget.
+
+#### 44. Interoperability ↔ Reality (S, Pilot)
+
+Synergy. Reality favors integration with the tools users already have; interoperability answers. Mild tension only when interop ambitions outrun real user needs (building bridges to systems no one bridges to). Bites at pilot, when integration scope is decided.
+
+### Pair Centered on Affordability and Reality
+
+#### 45. Affordability ↔ Reality (S, all phases)
+You can send follow-ups to the cloud agent here.
Reviewed by Cursor Bugbot for commit b5688dd. Configure here.
klappy
pushed a commit
that referenced
this pull request
May 10, 2026
Encodes the corrected lane after a prior-session off-lane drift drafting Oddie content without checking that Oddie already exists in canon (PR #179, #180). Withdrawn off-lane draft lives at /mnt/user-data/outputs/oddie-system-prompt-v0.md and should be ignored. Lane: wire canon/methods/quality-attribute-tension-survey.md to oddkit's existing governance machinery (preflight, gate, challenge, validate, encode) following the runtime-contract / persona-shaped pattern that PR #187 landed 2026-05-10. Scope is the method doc + the session ledger on the same PR branch. Required reading enumerated: PRs #187 (runtime-contract pattern), #186 (five modes including Resolution), #180 + #179 (existing Oddie canon), plus four open PRs ahead that may force a rebase. Concrete steps, do-not list, and banked off-scope items captured so a fresh session can pick up without re-deriving context. Frontmatter matches odd/handoffs/ conventions; tier 2; status active.
Introduces a four-document canon package on quality-attribute tradeoffs, plus a worked observability extension and a narrative essay. - canon/definitions/software-virtues-vocabulary.md (132 lines, tier 2): Names and defines the canonical ten virtues from the 2018 Medium article. Declares 'virtues' and 'quality attributes' as the same set; explicitly notes the universe is larger than ten. - canon/principles/quality-attributes-are-in-tension.md (85 lines, tier 1): Short axiomatic principle. The tradeoff space is structured by tensions, not single objective functions. Holds for any set of quality attributes. - canon/observations/quality-attribute-tension-matrix.md (294 lines, tier 2): Worked example demonstrating the principle across the canonical ten: 10x10 quick-reference grid plus all 45 unique pairs detailed with relationship type (mutual/asymmetric/synergy/cost gravity), direction, and phase weighting (PoC/Pilot/Production). Twenty-one pairs are named in the 2018 article; twenty-four are filled in. - canon/observations/observability-tension-extension.md (122 lines, tier 2): First worked extension. Maps observability's tensions against the canonical ten, stitching from existing canon (Epoch 8 / 8.2 / 8.3 appendices and the catalog-observability-gap case study). Demonstrates the extension pattern for future ility-class additions. - writings/software-virtues-revisited.md (160 lines): Narrative essay framing the matrix as the systematic completion of the 2018 article and pivoting to its constraints-survey use for agent work. - odd/ledger/2026-05-10-software-virtues-canon-package.md (121 lines): Session DOLCHEO journal capturing decisions, observations, learnings, constraints, handoffs, and opens. Vocabulary note: the 2018 article's 'natural enemies' framing is preserved only when explicitly quoting the article. Canon vocabulary throughout is 'tensions' for structural precision. Banked for next session: canon/methods/quality-attribute-tension-survey (operationalizes the matrix as a constraints survey for agent work, including the dynamic-generation step over arbitrary ility sets).
…ing type Both operationalize Axiom 4 (You Cannot Verify What You Did Not Observe) at different scales — the encoding type at the session level, the observability quality attribute at the runtime-system level. - Adds a 'Siblings Under Axiom 4' section to the observability extension explaining the parallel: shared parentage, shared failure mode, reinforcing principles. Explains why observability earned the first extension slot. - Adds one See Also entry to odd/encoding-types/observation.md pointing at the observability extension as its runtime-system sibling. Cross-reference makes the canon's underlying architecture visible: the same axiom shows up at multiple scales because it has to.
…he matrix as a constraints survey for agent work) Seven-phase method: stage identification, ility selection, phase-weighted ranking, tension surfacing (matrix consult or dynamic generation), sacrifice acknowledgment, constraint encoding (DOLCHEO Constraints), re-run triggers. Output is a typed artifact under 500 words: stage / ility set / tension list / accepted sacrifices / constraint set with re-run triggers. Constraints become the answer the agent gives whenever uncertain about which virtue to prioritize during execution. Includes a 6-row 6B borrow evaluation embedded in the doc per canon/constraints/borrow-evaluation-before-implementation: 1. Klappy 2018 Software Virtues -> borrow (already absorbed) 2. Klappy 2018 Lean Expectations -> borrow (phase-axis source) 3. agent-skill v1.3 PRD elicitation (archived)-> bend (spirit yes, arch no) 4. SEI ATAM -> bend (scenarios yes, workshop no) 5. ISO/IEC 25010 -> inspected-and-adopted 6. Bass/Clements/Kazman SAIP -> inspected-and-rejected Bide candidates: SEI QAW, NFR Framework. Reversibility high. Integration points named: oddkit_preflight should surface this method as a constraint reference for projects with existing constraint sets; future oddkit tensions(...) action would codify the dynamic-generation step in Phase 3 as a tool call. Ledger updated to record D6 (method doc lands same PR rather than stacked follow-on) and O5 (web search of Medium author page surfaced Lean Expectations as day-prior precursor article).
…a personality test for the product) Adds a new section to the method doc framing the survey output as a personality profile rather than a constraint list. Same shape humans already use for personality traits — radar chart with one axis per ility — maps cleanly onto a project. Two products with similar functions and different personalities will solve the same problem differently; the radar makes that legible at a glance. Section contents: - Personality-test framing: the cleanest way to think about the survey output is not a list of constraints but a personality profile. Earns the radar chart for free and gives the survey a public-facing entry point. - Format spec: tension-adjacent axis ordering by default (Usability > Originality > Stability > Urgency > Maintainability > Efficiency > Versatility > Interoperability > Affordability > Reality, walking the natural-tension chain), MoSCoW scale 1-4, sortable for renderers that support interaction. - Worked example: inline SVG radar for a hypothetical Pilot-stage authentication service. Strong spikes on Stability, Interoperability, and Reality; sharp valleys on Usability, Originality, Urgency, and Versatility; Maintainability and Affordability at Should. The polygon's silhouette is the tradeoff record. - Quality signal named: an honest profile is asymmetric. A near-circular profile indicates Phase 2 was rubber-stamped rather than worked through. - Forward pointer to a standalone article that will frame the personality-test view for non-technical audiences (banked, not in this PR). Ledger updated with D7 (radar addition), O6 (framing observation), and O-open P5 (standalone article banked).
…osite radar Two operator corrections applied: D8 — Axis ordering: tension-opposite, not tension-adjacent. Across-the-diameter pairs carry mutual tension; adjacent pairs carry synergy. Right half is the synergy chain (Stability through Efficiency); left half is the tension cluster mirrored across the diameter (Urgency through Interoperability). Polygon lean at the diameter becomes the visible tradeoff; right-side contour smoothness becomes the visible synergy coherence. D9 — Dual-state survey, one flow. Operator directive: 'the survey asks you to respond with what is and what do you want it to be for each question. One flow.' Phases 1, 2, 3, 4 each elicit both current and desired state in the same pass. Phase 5 renamed 'Output Encoding' and produces three DOLCHEO artifact types from one survey run: - Constraints (C) — desired state, what the agent inherits - Observations (O) — current state, falsifiable baseline - Opens (O-open) — the gaps, prioritized roadmap items by magnitude Radar redrawn with two polygons (Desired solid blue, Current dashed orange) and tension-opposite axis ordering. Gap segments between the polygons visualize the roadmap directly. Worked example (Pilot-stage authentication service) updated to dual-state table showing current=2/desired=4 on Stability and Interoperability (top-priority roadmap items, gap +2 each), plus +1 gaps on Maintainability and Reality, and six on-target axes. Phase 6 re-run triggers updated to account for the three artifact types and a new 'drift detection' trigger when observed current state diverges measurably from the prior Observation set. Ledger appended with D8, D9, O7 (radar audit signals from new ordering), O8 (one-flow framing collapses what would have been a separate audit pass).
…elicitation learning Stakeholder validation. Technical partner Ian Lindsley reviewed the rendered dual-state radar (commit 3509386) and responded 'This is perfect.' Captures operator's verbatim framing to Ian as source material for the standalone article (O-open P5): - 'personality test for a product. What personality do you want your product to have?' - 'oddkit survey questions... discovers the current and aspirational personality of your project.' - 'renders this chart and over time you can track the movement from what was to your desired priorities.' - 'roadmap and priorities for features and functions that actually move the needle towards the outcomes and impact the user in a meaningful way.' L3 — voice landed first. The framing for the standalone article crystallized in real-time stakeholder conversation before any draft was attempted. The article preserves this voice across audiences rather than deriving a new one. New product surface — Oddie, the dynamic survey interviewer. Distinct from the static method doc (canonical specification) and the future oddkit tensions(...) action (a tool call). Oddie is the interactive interview runtime: a persona-pack a model consumes to run the quality- attribute tension survey as a conversation. L4 — Vodka Architecture applied to elicitation. Oddie inherits oddkit's own architectural shape: thin pack (identity + posture + flow + canon URIs) over stateful canon. Pack reads canon live via oddkit; updates propagate automatically. Explicitly rejects the archived agent-skill v1.3 pack- compilation / Cloudflare Pages distribution pattern. O-open P6 — Oddie pack design banked for next focused session. Shape proposed (persona, runtime canon dependencies, phase-by-phase flow controller, output emitter, distribution surfaces). Pre-implementation 6B borrow recommended against agent-skill v1.3 with explicit guardrails ('no pack compilation, no snapshot lock-in'). O-open P7 — oddkit tensions(...) action remains separate from Oddie. Distinct surface: action is the tool call Oddie uses at Phase 3; Oddie is the conversational runtime. Sequencing: Oddie can be drafted before the action lands because Phase 3's hand-run procedure is documented.
Encodes the corrected lane after a prior-session off-lane drift drafting Oddie content without checking that Oddie already exists in canon (PR #179, #180). Withdrawn off-lane draft lives at /mnt/user-data/outputs/oddie-system-prompt-v0.md and should be ignored. Lane: wire canon/methods/quality-attribute-tension-survey.md to oddkit's existing governance machinery (preflight, gate, challenge, validate, encode) following the runtime-contract / persona-shaped pattern that PR #187 landed 2026-05-10. Scope is the method doc + the session ledger on the same PR branch. Required reading enumerated: PRs #187 (runtime-contract pattern), #186 (five modes including Resolution), #180 + #179 (existing Oddie canon), plus four open PRs ahead that may force a rebase. Concrete steps, do-not list, and banked off-scope items captured so a fresh session can pick up without re-deriving context. Frontmatter matches odd/handoffs/ conventions; tier 2; status active.
…tract pattern per #187)
klappy
force-pushed
the
canon/software-virtues-tension-matrix
branch
from
c349c2b to
1101424
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Six new documents canonizing the quality-attribute tradeoff space, derived from a 2018 Medium article that has stayed load-bearing for nearly a decade. Companion essay revisits the article and pivots to its constraints-survey use for agent work.
Files
canon/definitions/software-virtues-vocabulary.mdcanon/principles/quality-attributes-are-in-tension.mdcanon/observations/quality-attribute-tension-matrix.mdcanon/observations/observability-tension-extension.mdwritings/software-virtues-revisited.mdodd/ledger/2026-05-10-software-virtues-canon-package.mdTotal: 914 insertions across 6 files.
What This Lands
Vocabulary Note
The 2018 article's "natural enemies" framing is preserved only when explicitly quoting the article. Canon vocabulary throughout is tensions for structural precision.
Cross-Links
klappy://odd/maturity(Levels 0/1/2 = PoC/Pilot/Production).klappy://canon/case-studies/catalog-observability-gap,klappy://docs/appendices/epoch-8,klappy://docs/appendices/epoch-8-2,klappy://docs/appendices/epoch-8-3, and Axiom 4.Banked for Next Session
canon/methods/quality-attribute-tension-survey— operationalizes the matrix as a constraints survey for agent work, including the dynamic-generation step that produces tension graphs for arbitrary ility sets at scope-setting time. A potentialoddkit tensions(...)action would codify the generation step. Borrow-evaluation against existing prior art recommended before drafting.Open Items
Three opens carried in the ledger for operator review:
Validation Status
Note
Low Risk
Docs-only change that adds new canon definitions/methods/essays; risk is limited to reviewer workload and potential cross-link/terminology consistency issues, not runtime behavior.
Overview
Canonizes a quality-attribute/“software virtues” tradeoff vocabulary and a phase-weighted tension model derived from the 2018 source article, including a worked
quality-attribute-tension-matrix(all 45 pairs across the canonical ten) and a companionquality-attributes-are-in-tensiontier-1 principle.Adds an operational
quality-attribute-tension-surveymethod that turns the matrix/principle into a per-project artifact (rank ilities, surface tensions, accept sacrifices, encode as DOLCHEO Constraints/Observations/Opens), including explicit oddkit governance wiring (oddkit_preflight/gate/challenge/encode/validate) and a dual-state radar visualization spec.Extends the matrix with a new
observability-tension-extension(evidence-linked tensions for observability vs the canonical ten), links it fromodd/encoding-types/observation, and adds a public essay plus an ODD ledger capturing the session decisions and follow-on handoff.Reviewed by Cursor Bugbot for commit 1101424. Bugbot is set up for automated code reviews on this repo. Configure here.