Failures Are Data

Summary

Recoverable business ambiguity should be captured as structured operational data. It should not be hidden as an exception, buried in logs, or retried until context disappears.

Problem

Operational work often fails for reasons that are not programmer errors: a missing mapping, an ambiguous identity, an incomplete artifact, or an external system mismatch. Treating those as generic exceptions makes repair harder and turns human intervention into ad hoc debugging.

Principle

Use exceptions for unrecoverable system failures and programmer mistakes. Use issues, signals, review tasks, diagnostics, and run artifacts for business ambiguity.

Platform Shape

The architecture guidance frames human review and repair surfaces as OLTP-backed stateful operations. A failed automation should produce something visible and resumable when the next step depends on human judgment. Jobs can continue through batch work while recording partial problems. UI surfaces can show the state, evidence, and available repair actions.

The same principle supports future agent work. Agents can inspect issues, evidence, and action descriptors only if failures are explicit data rather than private control flow.

Source Evidence

• AGENTS.md
• docs/reference/architecture.md
• docs/reference/operational-surface-ownership.md

Tradeoffs

Modeling failures as data takes more design work up front. The payoff is a system that can pause, explain itself, and resume without manual spelunking.

Related Reading

• docs/engineering/concepts/pipelines-jobs-services-review-surfaces.md
• docs/engineering/reference/thin-jobs-fat-services.md