error-messages

Error Messages Skill

Provides clear, actionable error messages that help users understand what went wrong, why it matters, and how to fix it. Better error messages reduce debugging time and user frustration.

Error Message Structure

Every error should follow this 4-part template:

❌ [WHAT WENT WRONG]

[WHY THIS MATTERS]

[HOW TO FIX IT]

[OPTIONAL CONTEXT]

Part 1: What Went Wrong

Clear, specific statement of the error. No jargon unless unavoidable.

Bad:

Error: ENOENT: no such file or directory, open '_state.json'

Good:

❌ State file not found (_state.json)

Better:

❌ State file not found (_state.json)
Project state required to generate tests.

Part 2: Why This Matters

1-2 sentences explaining impact. What breaks if user ignores this?

Bad:

(skipped — no explanation)

Good:

Without state, I can't determine your project's tech stack, components, or design tokens.
This means tests won't know what framework to use or what components to test.

Part 3: How to Fix It

Actionable steps to resolve. Start with the simplest fix.

Bad:

(skipped — vague)

Good:

How to fix:
1. Run /architect:blueprint to create initial project state
   (Estimated time: 20 minutes)
2. Once complete, try this command again: /architect:generate-tests

Part 4: Optional Context

Links to related commands, documentation, or debugging info. Skip if irrelevant.

Good addition:

Want to understand the prerequisite chain? Run /architect:next-steps

---

Error Categories & Examples

1. Missing Prerequisites

Trigger: User tries to run command X, but required input for X doesn't exist.

Template:

❌ [COMMAND] requires [PREREQUISITE], which hasn't been created yet.

[PREREQUISITE] is necessary because [WHY].

How to fix:
1. Run /architect:[FIX_COMMAND] (estimated X min)
2. Once complete, try /architect:[COMMAND] again

Questions? Run /architect:next-steps to see all recommendations.