diff --git a/conductor/product-guidelines.md b/conductor/product-guidelines.md index e2c2bc08..ab615a21 100644 --- a/conductor/product-guidelines.md +++ b/conductor/product-guidelines.md @@ -62,37 +62,7 @@ For the **Indentation** and **Newlines** rules (1-space indent, blank-line rules ## Data-Oriented Error Handling -The codebase follows the "errors are just cases" framework from Ryan Fleury's -[The Easiest Way To Handle Errors](https://www.dgtlgrove.com/p/the-easiest-way-to-handle-errors). -The canonical reference (with code examples) is in -[`conductor/code_styleguides/error_handling.md`](code_styleguides/error_handling.md). -Key principles: - -- **Result dataclasses** instead of `Optional[T]` or exception-based control flow. -- **Nil-sentinel dataclasses** instead of `None`. -- **Zero-initialized fields** via `@dataclass` defaults. -- **Fail early**: validation at the entry point, not deep in the call stack. -- **AND over OR**: return a struct with data + side-channel errors, not a sum type. -- **Exceptions reserved for the SDK boundary**: SDK errors are caught and converted - to `ErrorInfo` dataclasses; the rest of the application works with data, not control flow. - -This convention is established incrementally. The 2026-06-11 -`data_oriented_error_handling_20260606` track applies it to -`src/mcp_client.py`, `src/ai_client.py`, and `src/rag_engine.py`. Future -tracks will apply it to the remaining `src/` files -(`src/app_controller.py`, `src/models.py`, `src/project_manager.py`, etc. - -see `conductor/tracks/data_oriented_error_handling_20260606/spec.md` 12.2 -for the prioritized list). - -**Audit:** the convention is enforced via -[`scripts/audit_exception_handling.py`](../../scripts/audit_exception_handling.py) -(static analyzer; file-presence = enabled per -[`feature_flags.md`](code_styleguides/feature_flags.md)). Run -`uv run python scripts/audit_exception_handling.py` for a human-readable -report or `--json` for machine-readable output. The audit classifies each -`try/except/finally/raise` site against 10 categories (5 compliant + 3 -violation + 1 suspicious + 1 unclear); see the styleguide's "Audit Script" -section for the full taxonomy. +The canonical home (with code examples, the 5 patterns, the audit-script enforcement, and the incremental rollout plan) is [`conductor/code_styleguides/error_handling.md`](code_styleguides/error_handling.md). This section is a 1-line pointer to that canonical home. ## Data Structure Conventions