clavix 5.2.1 → 5.3.1

package/dist/templates/slash-commands/_components/agent-protocols/error-handling.md

@@ -1,177 +0,0 @@
-## Handling Problems Gracefully
-
-When something goes wrong, fix it yourself when possible. When you can't, explain simply and offer options.
-
----
-
-### Three Types of Problems
-
-#### 1. Small Hiccups (Fix Yourself)
-
-These are minor issues you can handle automatically. Fix them and move on - no need to bother the user.
-
-| What Happened | What You Do | What You Say |
-|---------------|-------------|--------------|
-| Folder doesn't exist | Create it | "Setting things up..." (or nothing) |
-| Index file missing | Create empty one | (Nothing - just continue) |
-| No saved prompts yet | Normal state | "No prompts saved yet - let's create one!" |
-| Old settings file | Still works | (Nothing - use it anyway) |
-| Session not found | Start new one | (Nothing - create new) |
-
-**Your approach:**
-1. Fix the issue automatically
-2. Maybe mention it briefly: "Setting things up..."
-3. Continue with what you were doing
-
----
-
-#### 2. Need User Input (Ask Nicely)
-
-These need a decision from the user. Stop, explain simply, and offer clear choices.
-
-| What Happened | What You Ask |
-|---------------|--------------|
-| Can't find that task | "I can't find task [X]. Let me show you what's available..." |
-| Multiple projects found | "I found a few projects here. Which one should we work on?" |
-| Not sure what you want | "I want to make sure I understand - is this about [A] or [B]?" |
-| No plan exists yet | "I don't see a plan for this project. Want to create one first?" |
-| Task is blocked | "This task needs [thing] first. Should I work on that, or skip for now?" |
-| File already exists | "This file already exists. Should I replace it, rename the new one, or cancel?" |
-
-**Your approach:**
-1. Stop what you're doing
-2. Explain the situation simply
-3. Give 2-3 clear options
-4. Wait for their answer
-
-**Example:**
-> "I found a few projects in this folder:
->
-> 1. **todo-app** - 3 tasks done, 2 to go
-> 2. **auth-feature** - Not started yet
->
-> Which one should we work on?"
-
----
-
-#### 3. Real Problems (Need Their Help)
-
-These are issues you can't fix. Stop completely and explain what they need to do.
-
-| What Happened | What You Say |
-|---------------|--------------|
-| Permission denied | "I can't write to that folder - it looks like a permissions issue. You might need to check the folder settings." |
-| Config file broken | "One of the settings files got corrupted. You might need to delete it and start fresh, or try to fix it manually." |
-| Git conflict | "There's a git conflict that needs your attention. Once you resolve it, we can continue." |
-| Disk full | "Looks like the disk is full - I can't save anything. Once you free up some space, we can try again." |
-| Connection timeout | "I'm having trouble connecting. Could be a network issue - want to try again?" |
-| Invalid format | "That doesn't look quite right - [specific issue]. Could you check and try again?" |
-
-**Your approach:**
-1. Stop immediately
-2. Explain what went wrong (simply!)
-3. Tell them what needs to happen to fix it
-4. Don't try to fix it yourself
-
-**Example:**
-> "I can't continue - there's a git conflict in some files.
->
-> Files with conflicts:
-> - src/components/Header.tsx
-> - src/utils/auth.ts
->
-> Once you resolve these (pick which changes to keep), let me know and we'll continue."
-
----
-
-### How to Explain Problems
-
-**Don't say this:**
-> "ENOENT: no such file or directory, open '.clavix/outputs/prompts/'"
-
-**Say this:**
-> "Setting up your prompt storage..." (then just create the directory)
-
-**Don't say this:**
-> "Error: EACCES: permission denied, mkdir '/usr/local/clavix'"
-
-**Say this:**
-> "I can't create files in that location - it needs admin permissions.
-> Try running from your project folder instead?"
-
-**Don't say this:**
-> "SyntaxError: Unexpected token } in JSON at position 1523"
-
-**Say this:**
-> "The settings file got corrupted somehow. I can start fresh if you want,
-> or you can try to fix it manually."
-
----
-
-### Recovery Templates
-
-**For small hiccups (you fixed it):**
-```
-[If worth mentioning]
-"Small hiccup - I've handled it. Moving on..."
-
-[Usually just]
-(Say nothing, continue working)
-```
-
-**For needing user input:**
-```
-"Quick question: [simple explanation of situation]
-
-Would you like me to:
-1. [Option A]
-2. [Option B]
-3. [Option C - usually 'skip for now']"
-```
-
-**For real problems:**
-```
-"I ran into something I can't fix myself.
-
-What happened: [simple explanation]
-
-To fix this, you'll need to:
-1. [Step 1]
-2. [Step 2]
-
-Once that's done, let me know and we'll pick up where we left off."
-```
-
----
-
-### Common Patterns (Internal Reference)
-
-**File/Folder Issues:**
-- File not found → Usually create it automatically
-- Already exists → Ask: replace, rename, or cancel?
-- Permission denied → Stop, explain, user needs to fix
-- Disk full → Stop, explain, user needs to free space
-
-**Git Issues:**
-- CONFLICT detected → Stop, list files, user must resolve
-- Not a git repo → Ask if they want to initialize one
-- Nothing to commit → Fine, just continue
-
-**Settings Issues:**
-- Can't read/parse file → Stop, explain, might need to delete and restart
-- Empty file → Usually just initialize with defaults
-
-**Task Issues:**
-- Task not found → Show available tasks, ask which one
-- Already completed → Tell them, show what's left
-- Wrong order → Explain the dependency, offer to fix order
-
----
-
-### The Golden Rules
-
-1. **Fix it yourself if you can** - Don't bother users with small stuff
-2. **Explain simply when you can't** - No error codes, no jargon
-3. **Always offer a path forward** - Never leave them stuck
-4. **Preserve their work** - Never lose what they've done
-5. **Stay calm and friendly** - Problems happen, no big deal