From 4f6ebc24defe1991f76098873b792a011df0d938 Mon Sep 17 00:00:00 2001
From: HiranoMasaaki <lambda.groove@gmail.com>
Date: Sat, 3 Jan 2026 06:08:29 +0000
Subject: [PATCH] refactor(create-expert): add error recovery guidance to
 expert templates

Add Error Handling sections to:
- Main Expert Template: standard error format with 'To fix:' guidance
- Setup Expert Template: error handling with doctor expert suggestion

Closes #362
---
 .changeset/add-error-recovery-guidance.md        | 11 +++++++++++
 apps/create-expert/src/lib/create-expert-toml.ts | 10 ++++++++++
 2 files changed, 21 insertions(+)
 create mode 100644 .changeset/add-error-recovery-guidance.md

diff --git a/.changeset/add-error-recovery-guidance.md b/.changeset/add-error-recovery-guidance.md
new file mode 100644
index 00000000..0d79c1d7
--- /dev/null
+++ b/.changeset/add-error-recovery-guidance.md
@@ -0,0 +1,11 @@
+---
+"create-expert": patch
+---
+
+Add error recovery guidance to expert templates
+
+Added explicit error handling sections to:
+- Main Expert Template: Format for error messages with "To fix:" guidance
+- Setup Expert Template: Error handling with suggestion to run doctor expert
+
+Reinforces Design Principle #7: "All errors must include 'To fix: ...' guidance"
diff --git a/apps/create-expert/src/lib/create-expert-toml.ts b/apps/create-expert/src/lib/create-expert-toml.ts
index 586663b3..db4e42f9 100644
--- a/apps/create-expert/src/lib/create-expert-toml.ts
+++ b/apps/create-expert/src/lib/create-expert-toml.ts
@@ -120,6 +120,11 @@ version = "1.0.0"
 description = "Brief description of main functionality"
 instruction = '''
 Your role and capabilities...
+
+## Error Handling
+When errors occur, provide actionable guidance:
+- "❌ Error: [what went wrong] | To fix: [specific steps]"
+- Never fail silently - always explain what happened and how to resolve it
 '''
 
 [experts."<name>".skills."@perstack/base"]
@@ -194,6 +199,11 @@ Help users configure required dependencies quickly and correctly.
 ## Success Output
 "✓ Setup complete! Try: npx perstack run <name> \\"your query\\""
 
+## Error Handling
+When setup fails, guide the user:
+- "❌ Failed: [what went wrong] | To fix: [specific steps]"
+- Suggest running the doctor expert for diagnostics
+
 ## Required Dependencies
 [List the specific dependencies this expert needs]
 '''