Observability Tension Extension

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

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.

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.

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.

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.