Task: Generate QUALITY.md — Observability & Performance Contract

Task: Generate QUALITY.md — Observability & Performance Contract

Objective

Produce a QUALITY.md that serves as the single source of truth for everything the system measures, logs, traces, and alerts on, together with the performance budgets and capacity envelope every hot path must respect. It fixes the logging format and forbidden-fields list, registers the domain event log vocabulary distinct from wire events, catalogues every metric under a stable METRIC-* ID with label cardinality stated, defines service-level objectives under SLO-* IDs with burn-rate alerts, pins the tracing strategy and span inventory per saga, enumerates alerts with severity and runbook links, attaches per-flow latency and throughput budgets, commits a capacity envelope, specifies caching per location, names back-pressure and load-shedding policies, and records benchmark baselines. An agent reading this document alone can — for any endpoint, saga, or event in the system — name the metrics that observe it, the SLO it serves, the alerts that fire on it, the latency budget it must satisfy, and the capacity envelope that frames it, without opening ARCHITECTURE, INTERFACES, or BEHAVIOR.

QUALITY.md consolidates what older guidance split as OBSERVABILITY.md and PERFORMANCE_MODEL.md, because every downstream reader needs both together: /operations wires alert routing and runbooks; every per-unit /SPEC.md declares the signals the unit emits and the budgets it satisfies; /code-review verifies the declarations; /system-verification checks end-to-end that signals actually flow. The defining discipline — and the commonest violation — is every SLI has an SLO, every SLO has a burn-rate alert, every alert links to a runbook: orphan signals rot into noise; orphan SLOs decay into aspirations; orphan alerts page humans with no script to follow.

Inputs

1. ARCHITECTURE.md (required) — § 2 Components and cross-component flow sections supply the list of components that emit signals and the flows that carry latency budgets; any ADR-NN on consistency, caching, or overload framing informs §§ 9–10.
2. INTERFACES.md (required) — § 6 Endpoints are the externally-measurable entry points; every EP-name that qualifies as a critical flow gets a § 7 Performance Budget row. § 7 Events supply the EVT-name set that the tracing strategy in § 5 and metric emission in § 3 anchor to.
3. BEHAVIOR.md (required) — § 1 State Machines supply transitions whose rates this document measures; § 2 Sagas supply saga steps whose durations § 7 budgets and whose spans § 5 traces; § 3 Idempotency Keys inform replay metrics; § 6 Event Emission Timing anchors the span inventory of § 5 to exact emission points.
4. PROPOSAL.md (optional) — product success criteria inform SLO targets. If PROPOSAL.md states a numeric target (e.g., "p95 push latency under 2 seconds"), cite it verbatim in the relevant SLO-*. If no numeric target is stated, propose one in § 13 Open Questions with options and tradeoffs.
5. DATA.md (optional — required if produced) — § 8 (or equivalent) sensitive-column inventory is the authoritative forbidden-fields list for § 1 Logging Standard. If DATA.md is not yet produced, derive the forbidden list from DOMAIN's value objects and surface the absent DATA reference as an open question.
6. ERRORS.md (optional — required if produced) — § 3 Error Code Registry supplies the codes that § 6 Alerts and § 2 Domain Event Log Vocabulary may reference. Alerts that trigger on specific error codes cite them by code string.
7. OPERATIONS.md (optional — if not yet produced, § 6 alert routing and runbook links surface as open questions for /operations to resolve downstream).
8. Existing QUALITY.md (auto-discovered — only if refining) — read fully. Every assigned METRIC-* and SLO-* ID is permanent. New entries take new unused IDs. Retired entries retain their row with (retired — superseded by {new-id}) markers.

Read set size: 3 required artifacts + PROPOSAL, DATA, ERRORS when present + optional prior QUALITY. Read all required inputs end-to-end. Truncated reads cause two specific failure modes: metrics cataloged against endpoints or sagas that do not exist (INTERFACES / BEHAVIOR not fully read) and SLOs whose targets contradict PROPOSAL's success criteria (PROPOSAL not fully read).

Workflow

Quality-contract construction proceeds in eight phases: logging standard, event log vocabulary, metrics catalogue, SLOs, tracing, alerts, performance and capacity, caching and back-pressure. Phases are sequential — later phases cite IDs introduced by earlier phases — but revisit earlier phases if a later one reveals a missing metric or an un-derivable SLO.

Phase 1: Logging Standard & Event Log Vocabulary

Produce § 1 Logging Standard and § 2 Domain Event Log Vocabulary together — they share the redaction contract.

§ 1 fixes format (structured JSON default), required fields, forbidden fields, log-level policy, retention, correlation, and redaction — see the template in Output Format for exact fields. The forbidden-fields list is derived from DATA.md § 8 (or DOMAIN's value objects if DATA not yet produced); missing any sensitive column is a data-leak bug. Retention cites OPERATIONS; absence surfaces as an open question.

§ 2 catalogues domain log events — operational log events the system writes, distinct from wire events owned by INTERFACES § 7. Name them in dotted lowercase verb-phrase form (repo.push.accepted, user.login.failed, saga.push.compensated). Each entry anchors to BEHAVIOR: cite SAGA-{name} step {N} or SM-{entity}: {from} → {to} where emission occurs. Un-anchored events drift. Sampling rates below 100% name the justification (volume, cost) and whether sampling is head or tail.

Phase 2: Metrics Catalogue

§ 3 is the master metrics catalogue — one row per metric, alphabetical by METRIC-*. Derive from three sources: every EP-name in INTERFACES § 6 gets request-count, duration-histogram, and in-flight gauge; every SAGA-{name} in BEHAVIOR § 2 gets duration-histogram, compensation-count, and timeout-count; every non-trivial SM-{entity}: {from} → {to} transition worth counting gets a counter.