Initial commit

skills/skill-factory/references/error-handling.md

@@ -0,0 +1,181 @@
+# Error Handling & Fix Strategy
+
+## Core Principle: Fail Fast
+
+When a phase fails without auto-fix capability, the workflow **stops immediately**. No complex recovery, no
+checkpointing, no resume commands—only clean exit with clear error reporting and preserved artifacts.
+
+## Rule-Based Fix Tiers
+
+Issues are categorized into three tiers based on complexity:
+
+### Tier 1: Simple (Auto-Fix)
+
+**Issue Types:**
+
+- Formatting issues (whitespace, indentation)
+- Missing frontmatter fields (can be inferred)
+- Markdown syntax errors (quote escaping, link formatting)
+- File structure issues (missing directories)
+
+**Actions:**
+
+1. Automatically apply fix
+2. Auto re-run the failed command ONCE
+3. Continue if passes, fail fast if still broken
+
+**Example:**
+
+```text
+/meta-claude:skill:review-compliance fails: "Missing frontmatter description field"
+  ↓
+Tier: Simple → AUTO-FIX
+  ↓
+Fix: Add description field inferred from skill name
+  ↓
+Auto re-run: /meta-claude:skill:review-compliance <skill-path>
+  ↓
+Result: Pass → Mark todo completed, continue to /meta-claude:skill:validate-runtime
+```
+
+### Tier 2: Medium (Guided Fix with Approval)
+
+**Issue Types:**
+
+- Content clarity suggestions
+- Example improvements
+- Instruction rewording
+- Structure optimization
+
+**Actions:**
+
+1. Present issue and suggested fix
+2. Ask user: "Apply this fix? [Yes/No/Edit]"
+3. If Yes → Apply fix, re-run command once
+4. If No → Fail fast
+5. If Edit → Show fix, let user modify, apply, re-run
+
+**Example:**
+
+```text
+/meta-claude:skill:review-content fails: "Examples section unclear, lacks practical context"
+  ↓
+Tier: Medium → GUIDED FIX
+  ↓
+Suggested fix: [Shows proposed rewrite with clearer examples]
+  ↓
+Ask: "Apply this fix? [Yes/No/Edit]"
+  ↓
+User: Yes
+  ↓
+Apply fix
+  ↓
+Re-run: /meta-claude:skill:review-content <skill-path>
+  ↓
+Result: Pass → Mark todo completed, continue to /meta-claude:skill:review-compliance
+```
+
+### Tier 3: Complex (Stop and Report)
+
+**Issue Types:**
+
+- Architectural problems (skill design flaws)
+- Insufficient research (missing critical information)
+- Unsupported use cases (doesn't fit Claude Code model)
+- Schema violations (fundamental structure issues)
+- Composition rule violations (e.g., attempting to nest sub-agents)
+
+**Actions:**
+
+1. Report the issue with detailed explanation
+2. Provide recommendations for manual fixes
+3. **Fail fast** - exit workflow immediately
+4. User must fix manually and restart workflow
+
+**Example:**
+
+```text
+/meta-claude:skill:review-content fails: "Skill attempts to nest sub-agents, violates composition rules"
+  ↓
+Tier: Complex → STOP AND REPORT
+  ↓
+Report:
+  ❌ Skill creation failed at: Review Content Quality
+
+  Issue found:
+  - [Tier 3: Complex] Skill attempts to nest sub-agents, which violates composition rules
+
+  Recommendation:
+  - Restructure skill to invoke sub-agents via SlashCommand tool instead
+  - See: plugins/meta/meta-claude/skills/multi-agent-composition/
+
+  Workflow stopped. Please fix manually and restart.
+
+  Artifacts preserved at:
+    Research: docs/research/skills/coderabbit/
+    Partial skill: plugins/meta/meta-claude/skills/coderabbit/
+
+  ↓
+WORKFLOW EXITS (fail fast)
+```
+
+## One-Shot Fix Policy
+
+To prevent infinite loops:
+
+```text
+Phase fails
+  ↓
+Apply fix (auto or guided)
+  ↓
+Re-run command ONCE
+  ↓
+Result:
+  - Pass → Continue to next phase
+  - Fail → FAIL FAST (no second fix attempt)
+```
+
+**Rationale:** If the first fix fails, the issue exceeds initial assessment. Stop and let the user investigate rather
+than looping infinitely.
+
+## Issue Categorization Response Format
+
+Each primitive command returns errors with tier metadata:
+
+```javascript
+{
+  "status": "fail",
+  "issues": [
+    {
+      "tier": "simple",
+      "category": "frontmatter",
+      "description": "Missing description field",
+      "fix": "Add description: 'Guide for CodeRabbit code review'",
+      "auto_fixable": true
+    },
+    {
+      "tier": "medium",
+      "category": "content-clarity",
+      "description": "Examples section unclear, lacks practical context",
+      "suggestion": "[Proposed rewrite with clearer examples]",
+      "auto_fixable": false
+    },
+    {
+      "tier": "complex",
+      "category": "architectural",
+      "description": "Skill violates composition rules by nesting sub-agents",
+      "recommendation": "Restructure to use SlashCommand tool for sub-agent invocation",
+      "auto_fixable": false
+    }
+  ]
+}
+```
+
+## Parsing Command Responses
+
+When a command completes, analyze its output to determine status:
+
+- Look for "Success", "PASS", or exit code 0 → Continue
+- Look for "Error", "FAIL", or exit code 1 → Apply fix strategy
+- Parse issue tier metadata (if provided) to select fix approach
+- If no tier metadata, infer tier from issue description