Update instructions, agents, skills - part 1

2026-09-02 14:05:41 -05:00
parent 88cef169c4
commit e5ef4d4422
8 changed files with 94 additions and 20 deletions
@@ -75,6 +75,28 @@ Required internal -> canonical mapping:
 - Include actionable remediation guidance aligned to category.
 - Keep envelope structure consistent across API endpoints.

+### `AppError.message` vs `AppError.detail`
+
+`AppError` carries two texts with different audiences, and they must not be collapsed. Getting this
+wrong has already caused a real defect in this repository, in both directions.
+
+| Attribute | Audience | Reaches | Rule |
+| :--- | :--- | :--- | :--- |
+| `message` | User and API clients | `ErrorEnvelope.message`, UI notifications | Stays generic. Never embed exception text, provider payloads, or filesystem paths. |
+| `detail` | Internal only | Logs, and `format_error_detail` -> `ExecutionAttempt.error_detail` and `MaintenanceRun.error_detail` | Carries the root cause. Never rendered to users or serialized into an envelope. |
+
+- Putting root-cause data in `message` leaks infrastructure detail to users.
+- Omitting it from `detail` silently degrades the provenance record this system exists to preserve —
+  a failed attempt whose `error_detail` says nothing is an attempt that cannot be diagnosed later.
+- When you raise from a caught exception, populate **both**: a generic `message` and a `detail`
+  carrying `type(exc).__name__` and the exception text, with `raise ... from exc`.
+- `detail` is optional (`None`). A read path that assumes it is populated must handle its absence.
+- Before changing either attribute, or any helper that formats them, enumerate every consumer —
+  evidence writes, maintenance runs, logging, API envelopes, and UI presentation all read these
+  fields, and tests assert on the persisted text.
+
+Canonical definitions live in `src/transcription/errors.py`; see also `docs/error_handling.md`.
+
 ## Logging and Diagnostics

 - Log operation identifiers and error IDs where available.