aiblueprint-cli 1.4.11 → 1.4.13

package/claude-code-config/skills/create-subagents/references/error-handling-and-recovery.md

@@ -0,0 +1,502 @@
+# Error Handling and Recovery for Subagents
+
+<common_failure_modes>
+
+
+Industry research identifies these failure patterns:
+
+<specification_problems>
+**32% of failures**: Subagents don't know what to do.
+
+**Causes**:
+- Vague or incomplete role definition
+- Missing workflow steps
+- Unclear success criteria
+- Ambiguous constraints
+
+**Symptoms**: Subagent asks clarifying questions (can't if it's a subagent), makes incorrect assumptions, produces partial outputs, or fails to complete task.
+
+**Prevention**: Explicit `<role>`, `<workflow>`, `<focus_areas>`, and `<output_format>` sections in prompt.
+</specification_problems>
+
+<inter_agent_misalignment>
+**28% of failures**: Coordination breakdowns in multi-agent workflows.
+
+**Causes**:
+- Subagents have conflicting objectives
+- Handoff points unclear
+- No shared context or state
+- Assumptions about other agents' outputs
+
+**Symptoms**: Duplicate work, contradictory outputs, infinite loops, tasks falling through cracks.
+
+**Prevention**: Clear orchestration patterns (see [orchestration-patterns.md](orchestration-patterns.md)), explicit handoff protocols.
+</inter_agent_misalignment>
+
+<verification_gaps>
+**24% of failures**: Nobody checks quality.
+
+**Causes**:
+- No validation step in workflow
+- Missing output format specification
+- No error detection logic
+- Blind trust in subagent outputs
+
+**Symptoms**: Incorrect results silently propagated, hallucinations undetected, format errors break downstream processes.
+
+**Prevention**: Include verification steps in subagent workflows, validate outputs before use, implement evaluator agents.
+</verification_gaps>
+
+<error_cascading>
+**Critical pattern**: Failures in one subagent propagate to others.
+
+**Causes**:
+- No error handling in downstream agents
+- Assumptions that upstream outputs are valid
+- No circuit breakers or fallbacks
+
+**Symptoms**: Single failure causes entire workflow to fail.
+
+**Prevention**: Defensive programming in subagent prompts, graceful degradation strategies, validation at boundaries.
+</error_cascading>
+
+<non_determinism>
+**Inherent challenge**: Same prompt can produce different outputs.
+
+**Causes**:
+- LLM sampling and temperature settings
+- API latency variations
+- Context window ordering effects
+
+**Symptoms**: Inconsistent behavior across invocations, tests pass sometimes and fail other times.
+
+**Mitigation**: Lower temperature for consistency-critical tasks, comprehensive testing to identify variation patterns, robust validation.
+</non_determinism>
+</common_failure_modes>
+
+<recovery_strategies>
+
+
+<graceful_degradation>
+**Pattern**: Workflow produces useful result even when ideal path fails.
+
+<example>
+```markdown
+<workflow>
+1. Attempt to fetch latest API documentation from web
+2. If fetch fails, use cached documentation (flag as potentially outdated)
+3. If no cache available, use local stub documentation (flag as incomplete)
+4. Generate code with best available information
+5. Add TODO comments indicating what should be verified
+</workflow>
+
+<fallback_hierarchy>
+- Primary: Live API docs (most accurate)
+- Secondary: Cached docs (may be stale, flag date)
+- Tertiary: Stub docs (minimal, flag as incomplete)
+- Always: Add verification TODOs to generated code
+</fallback_hierarchy>
+```
+
+**Key principle**: Partial success better than total failure. Always produce something useful.
+</example>
+</graceful_degradation>
+
+<autonomous_retry>
+**Pattern**: Subagent retries failed operations with exponential backoff.
+
+<example>
+```markdown
+<error_handling>
+When a tool call fails:
+1. Attempt operation
+2. If fails, wait 1 second and retry
+3. If fails again, wait 2 seconds and retry
+4. If fails third time, proceed with fallback approach
+5. Document the failure in output
+
+Maximum 3 retry attempts before falling back.
+</error_handling>
+```
+
+**Use case**: Transient failures (network issues, temporary file locks, rate limits).
+
+**Anti-pattern**: Infinite retry loops without backoff or max attempts.
+</example>
+</autonomous_retry>
+
+<circuit_breakers>
+**Pattern**: Prevent cascading failures by stopping calls to failing components.
+
+<conceptual_example>
+```markdown
+<circuit_breaker_logic>
+If API endpoint has failed 5 consecutive times:
+- Stop calling the endpoint (circuit "open")
+- Use fallback data source
+- After 5 minutes, attempt one call (circuit "half-open")
+- If succeeds, resume normal calls (circuit "closed")
+- If fails, keep circuit open for another 5 minutes
+</circuit_breaker_logic>
+```
+
+**Application to subagents**: Include in prompt when subagent calls external APIs or services.
+
+**Benefit**: Prevents wasting time/tokens on operations known to be failing.
+</conceptual_example>
+</circuit_breakers>
+
+<timeouts>
+**Pattern**: Agents going silent shouldn't block workflow indefinitely.
+
+<implementation>
+```markdown
+<timeout_handling>
+For long-running operations:
+1. Set reasonable timeout (e.g., 2 minutes for analysis)
+2. If operation exceeds timeout:
+   - Abort operation
+   - Provide partial results if available
+   - Clearly flag as incomplete
+   - Suggest manual intervention
+</timeout_handling>
+```
+
+**Note**: Claude Code has built-in timeouts for tool calls. Subagent prompts should include guidance on what to do when operations approach reasonable time limits.
+</implementation>
+</timeouts>
+
+<multiple_verification_paths>
+**Pattern**: Different validators catch different error types.
+
+<example>
+```markdown
+<verification_strategy>
+After generating code:
+1. Syntax check: Parse code to verify valid syntax
+2. Type check: Run static type checker (if applicable)
+3. Linting: Check for common issues and anti-patterns
+4. Security scan: Check for obvious vulnerabilities
+5. Test run: Execute tests if available
+
+If any check fails, fix issue and re-run all checks.
+Each check catches different error types.
+</verification_strategy>
+```
+
+**Benefit**: Layered validation catches more issues than single validation pass.
+</example>
+</multiple_verification_paths>
+
+<reassigning_tasks>
+**Pattern**: Invoke alternative agents or escalate to human when primary approach fails.
+
+<example>
+```markdown
+<escalation_workflow>
+If automated fix fails after 2 attempts:
+1. Document what was tried and why it failed
+2. Provide diagnosis of the problem
+3. Recommend human review with specific questions to investigate
+4. DO NOT continue attempting automated fixes that aren't working
+
+Know when to escalate rather than thrashing.
+</escalation_workflow>
+```
+
+**Key insight**: Subagents should recognize their limitations and provide useful handoff information.
+</example>
+</reassigning_tasks>
+</recovery_strategies>
+
+<structured_communication>
+
+
+Multi-agent systems fail when communication is ambiguous. Structured messaging prevents misunderstandings.
+
+<message_types>
+Every message between agents (or from agent to user) should have explicit type:
+
+**Request**: Asking for something
+```markdown
+Type: Request
+From: code-reviewer
+To: test-writer
+Task: Create tests for authentication module
+Context: Recent security review found gaps in auth testing
+Expected output: Comprehensive test suite covering auth edge cases
+```
+
+**Inform**: Providing information
+```markdown
+Type: Inform
+From: debugger
+To: Main chat
+Status: Investigation complete
+Findings: Root cause identified in line 127, race condition in async handler
+```
+
+**Commit**: Promising to do something
+```markdown
+Type: Commit
+From: security-reviewer
+Task: Review all changes in PR #342 for security issues
+Deadline: Before responding to main chat
+```
+
+**Reject**: Declining request with reason
+```markdown
+Type: Reject
+From: test-writer
+Reason: Cannot write tests - no testing framework configured in project
+Recommendation: Install Jest or similar framework first
+```
+</message_types>
+
+<schema_validation>
+**Pattern**: Validate every payload against expected schema.
+
+<example>
+```markdown
+<output_validation>
+Expected output format:
+{
+  "vulnerabilities": [
+    {
+      "severity": "Critical|High|Medium|Low",
+      "location": "file:line",
+      "type": "string",
+      "description": "string",
+      "fix": "string"
+    }
+  ],
+  "summary": "string"
+}
+
+Before returning output:
+1. Verify JSON is valid
+2. Check all required fields present
+3. Validate severity values are from allowed list
+4. Ensure location follows "file:line" format
+</output_validation>
+```
+
+**Benefit**: Prevents malformed outputs from breaking downstream processes.
+</example>
+</schema_validation>
+</structured_communication>
+
+<observability>
+
+
+"Most agent failures are not model failures, they are context failures."
+
+<structured_logging>
+**What to log**:
+- Input prompts and parameters
+- Tool calls and their results
+- Intermediate reasoning (if visible)
+- Final outputs
+- Metadata (timestamps, model version, token usage, latency)
+- Errors and warnings
+
+**Log structure**:
+```markdown
+Invocation ID: abc-123-def
+Timestamp: 2025-11-15T14:23:01Z
+Subagent: security-reviewer
+Model: sonnet-4.5
+Input: "Review changes in commit a3f2b1c"
+Tool calls:
+  1. git diff a3f2b1c (success, 234 lines)
+  2. Read src/auth.ts (success, 156 lines)
+  3. Read src/db.ts (success, 203 lines)
+Output: 3 vulnerabilities found (2 High, 1 Medium)
+Tokens: 2,341 input, 876 output
+Latency: 4.2s
+Status: Success
+```
+
+**Use case**: Debugging failures, identifying patterns, performance optimization.
+</structured_logging>
+
+<correlation_ids>
+**Pattern**: Track every message, plan, and tool call for end-to-end reconstruction.
+
+```markdown
+Correlation ID: workflow-20251115-abc123
+
+Main chat [abc123]:
+  → Launched code-reviewer [abc123-1]
+     → Tool: git diff [abc123-1-t1]
+     → Tool: Read auth.ts [abc123-1-t2]
+     → Returned: 3 issues found
+  → Launched test-writer [abc123-2]
+     → Tool: Read auth.ts [abc123-2-t1]
+     → Tool: Write auth.test.ts [abc123-2-t2]
+     → Returned: Test suite created
+  → Presented results to user
+```
+
+**Benefit**: Can trace entire workflow execution, identify where failures occurred, understand cascading effects.
+</correlation_ids>
+
+<metrics_monitoring>
+**Key metrics to track**:
+- Success rate (completed tasks / total invocations)
+- Error rate by error type
+- Average token usage (spikes indicate prompt issues)
+- Latency trends (increases suggest inefficiency)
+- Tool call patterns (unusual patterns indicate problems)
+- Retry rates (how often users re-invoke after failure)
+
+**Alert thresholds**:
+- Success rate drops below 80%
+- Error rate exceeds 15%
+- Token usage increases >50% without prompt changes
+- Latency exceeds 2x baseline
+- Same error type occurs >5 times in 24 hours
+</metrics_monitoring>
+
+<evaluator_agents>
+**Pattern**: Dedicated quality guardrail agents validate outputs.
+
+<example>
+```markdown
+---
+name: output-validator
+description: Validates subagent outputs against expected schemas and quality criteria. Use after any subagent produces structured output.
+tools: Read
+model: haiku
+---
+
+<role>
+You are an output validation specialist. Check subagent outputs for:
+- Schema compliance
+- Completeness
+- Internal consistency
+- Format correctness
+</role>
+
+<workflow>
+1. Receive subagent output and expected schema
+2. Validate structure matches schema
+3. Check for required fields
+4. Verify value constraints (enums, formats, ranges)
+5. Test internal consistency (references valid, no contradictions)
+6. Return validation report: Pass/Fail with specific issues
+</workflow>
+
+<validation_criteria>
+Pass: All checks succeed
+Fail: Any check fails - provide detailed error report
+Partial: Minor issues that don't prevent use - flag warnings
+</validation_criteria>
+```
+
+**Use case**: Critical workflows where output quality is essential, high-risk operations, compliance requirements.
+</example>
+</evaluator_agents>
+</observability>
+
+<anti_patterns>
+
+
+<anti_pattern name="silent_failures">
+❌ Subagent fails but doesn't indicate failure in output
+
+**Example**:
+```markdown
+Task: Review 10 files for security issues
+Reality: Only reviewed 3 files due to errors, returned results anyway
+Output: "No issues found" (incomplete review, but looks successful)
+```
+
+**Fix**: Explicitly state what was reviewed, flag partial completion, include error summary.
+</anti_pattern>
+
+<anti_pattern name="no_fallback">
+❌ When ideal path fails, subagent gives up entirely
+
+**Example**:
+```markdown
+Task: Generate code from API documentation
+Error: API docs unavailable
+Output: "Cannot complete task, API docs not accessible"
+```
+
+**Better**:
+```markdown
+Error: API docs unavailable
+Fallback: Using cached documentation (last updated: 2025-11-01)
+Output: Code generated with note: "Verify against current API docs, using cached version"
+```
+
+**Principle**: Provide best possible output given constraints, clearly flag limitations.
+</anti_pattern>
+
+<anti_pattern name="infinite_retry">
+❌ Retrying failed operations without backoff or limit
+
+**Risk**: Wastes tokens, time, and may hit rate limits.
+
+**Fix**: Maximum retry count (typically 2-3), exponential backoff, fallback after exhausting retries.
+</anti_pattern>
+
+<anti_pattern name="error_cascading">
+❌ Downstream agents assume upstream outputs are valid
+
+**Example**:
+```markdown
+Agent 1: Generates code (contains syntax error)
+  ↓
+Agent 2: Writes tests (assumes code is syntactically valid, tests fail)
+  ↓
+Agent 3: Runs tests (all tests fail due to syntax error in code)
+  ↓
+Total workflow failure from single upstream error
+```
+
+**Fix**: Each agent validates inputs before processing, includes error handling for invalid inputs.
+</anti_pattern>
+
+<anti_pattern name="no_error_context">
+❌ Error messages without diagnostic context
+
+**Bad**: "Failed to complete task"
+
+**Good**: "Failed to complete task: Unable to access file src/auth.ts (file not found). Attempted to review authentication code but file missing from expected location. Recommendation: Verify file path or check if file was moved/deleted."
+
+**Principle**: Error messages should help diagnose root cause and suggest remediation.
+</anti_pattern>
+</anti_patterns>
+
+<recovery_checklist>
+
+
+Include these patterns in subagent prompts:
+
+**Error detection**:
+- [ ] Validate inputs before processing
+- [ ] Check tool call results for errors
+- [ ] Verify outputs match expected format
+- [ ] Test assumptions (file exists, data valid, etc.)
+
+**Recovery mechanisms**:
+- [ ] Define fallback approach for primary path failure
+- [ ] Include retry logic for transient failures
+- [ ] Graceful degradation (partial results better than none)
+- [ ] Clear error messages with diagnostic context
+
+**Failure communication**:
+- [ ] Explicitly state when task cannot be completed
+- [ ] Explain what was attempted and why it failed
+- [ ] Provide partial results if available
+- [ ] Suggest remediation or next steps
+
+**Quality gates**:
+- [ ] Validation steps before returning output
+- [ ] Self-checking (does output make sense?)
+- [ ] Format compliance verification
+- [ ] Completeness check (all required components present?)
+</recovery_checklist>