playbook/outfitter-agents/plugins/outfitter-stack/skills/stack-audit/templates/plan/03-errors.md

Stage 3: Errors

Status: ⬜ Not Started Blocked By: Handlers Unlocks: Documents

Objective

Replace custom error classes with Outfitter error taxonomy.

Error Taxonomy Reference

Category	Class	Exit	HTTP	Use For
validation	ValidationError	1	400	Invalid input, schema failures
not_found	NotFoundError	2	404	Resource doesn't exist
conflict	ConflictError	3	409	Already exists, version mismatch
permission	PermissionError	4	403	Forbidden action
timeout	TimeoutError	5	504	Operation took too long
rate_limit	RateLimitError	6	429	Too many requests
network	NetworkError	7	503	Connection failures
internal	InternalError	8	500	Unexpected errors, bugs
auth	AuthError	9	401	Authentication required
cancelled	CancelledError	130	499	User interrupted

Error Classes to Migrate

{{#each ERROR_CLASSES}}

{{this.name}}

• File: {{this.file}}:{{this.line}}
• Usages: {{this.usageCount}}
• Suggested Mapping: {{this.suggestedMapping}}

Migration

• Identify all usages of {{this.name}}
• Replace with {{this.suggestedMapping}}
• Update error metadata/details
• Remove original class definition
• Update tests

// Before
throw new {{this.name}}({{this.exampleArgs}});

// After
return Result.err(new {{this.suggestedMapping}}({{this.newArgs}}));

---

{{/each}}

Unmapped Errors

Errors that don't fit standard taxonomy:

{{#each UNMAPPED_ERRORS}}

• {{this.name}} — {{this.reason}} {{/each}}

Options for unmapped errors:

1. Use InternalError with descriptive message
2. Create domain-specific error extending OutfitterError
3. Map to closest category with metadata

Completion Checklist

• All custom errors mapped to taxonomy
• Original error classes removed
• Error messages include structured metadata
• Exit codes verified correct
• Tests updated

Notes

{{ERROR_NOTES}}