From 8996a3c92dc44a11e51ff7f05af0a43636d16a47 Mon Sep 17 00:00:00 2001 From: Ed_ Date: Sun, 5 Jul 2026 15:19:50 -0400 Subject: [PATCH] =?UTF-8?q?refactor(conductor/product-guidelines.md):=20th?= =?UTF-8?q?in-pointer=20=C2=A7Data-Oriented=20Error=20Handling=20to=20erro?= =?UTF-8?q?r=5Fhandling.md?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Per agent_directives_consolidation_20260705 §3.4. The 30-line §Data-Oriented Error Handling section (key principles + incremental rollout plan + audit-script enforcement) is replaced with a 1-line pointer to conductor/code_styleguides/error_handling.md, the canonical home for the Result[T] + NIL_T convention. Net: 30 lines reduced to 1 line. Duplicate content removed; the canonical styleguide remains the source of truth. --- conductor/product-guidelines.md | 32 +------------------------------- 1 file changed, 1 insertion(+), 31 deletions(-) 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