# Trails Error Format

> Use when reviewing Trails error taxonomy, surface error rendering, redaction, retryability, or Result-vs-throw boundaries. Helps distinguish runtime failures from intentional construction and host-boundary throws.

- Skill: `outfitter-dev/trails-error-format` (Agent Skill)
- Install (CLI): `npx skillmds@latest add outfitter-dev/trails-error-format`
- Raw SKILL.md: https://api.skillmd.com/api/skills/outfitter-dev/trails-error-format/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: outfitter-dev (https://skillmd.com/u/outfitter-dev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/outfitter-dev/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

- `plugin/skills/trails/references/error-taxonomy.md`
- `docs/contributing/warden-rules.md`
- `packages/core/src/errors.ts`
- `packages/core/src/transport-error-map.ts`
- Surface packages: CLI, MCP, HTTP, and Hono.

## Advisory Context

- TRL-564 / PR #300 for host-boundary examples.

## 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.