outfitter-dev/trails/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.

1. Choose the most specific TrailsError subclass for runtime failures.
2. Trace rendering data back to owner exports such as error categories, retryability, and status or code maps.
3. Check redaction at the boundary that exposes data to agents, users, logs, or surface clients.
4. Verify tests cover both the raw error object and the rendered surface shape when both are public behavior.

Authoritative Sources

• Bundled error taxonomy
• 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.