trails-error-format

# Trails Error Format Use this skill when a change touches error classes, `Result.err`, CLI/HTTP/MCP rendering, redaction, retry behavior, or host construction boundaries. ## Workflow 1. Classify the failure boundary: - Trail runtime failures return `Result.err(new TrailsErrorSubclass(...))`. - Surface presentation maps existing `TrailsError` values to surface-specific output. - Construction or programmer errors may throw when the boundary is explicit. 2. Choose the most specific `TrailsError` subclass for runtime failures. 3. Trace rendering data back to owner exports such as error categories, retryability, and status or code maps. 4. Check redaction at the boundary that exposes data to agents, users, logs, or surface clients. 5. Verify tests cover both the raw error object and the rendered surface shape when both are public behavior. ## Authoritative Sources - [Bundled error taxonomy](../trails/references/error-taxonomy.md) - Public error exports from the installed `@ontrails/core` package. - The installed CLI, MCP, HTTP, and Hono surface packages when their rendering behavior is under review. ## Must Not - Do not collapse all throws into bugs; verify whether the throw is a construction or programmer-error boundary. - Do not add parallel error-code maps when core owner data already exposes the mapping. - Do not leak raw native `Error` values through public runtime Results when a specific `TrailsError` exists. - Do not put surface rendering policy inside trail implementation logic. ## Output Return: - Runtime, rendering, redaction, or host-boundary classification. - Expected error subclass and category. - Owner mapping or rendering source. - Surface behavior checked. - Missing tests or follow-up issue.