Arch Lens Error Resilience

Error/Resilience Architecture Lens

Cognitive Mode: Diagnostic Primary Question: "How are failures handled?" Focus: Error Propagation, Recovery Mechanisms, Circuit Breakers, Validation Gates

When to Use

• Need to understand error handling architecture
• Documenting recovery and retry mechanisms
• Analyzing validation gates and circuit breakers
• User invokes /arch-lens-error-resilience or /make-arch-diag error

Critical Constraints

NEVER:

• Modify any source code files
• Show happy path details (that's process flow lens)
• Ignore validation and fail-fast patterns

ALWAYS:

• Focus on FAILURE paths and recovery
• Show validation gates and their failure modes
• Document retry limits and circuit breakers
• Include exception hierarchy if present
• BEFORE creating any diagram, LOAD the /mermaid skill using the Skill tool - this is MANDATORY

---

Analysis Workflow

Step 1: Launch Parallel Exploration Subagents

Spawn Explore subagents to investigate:

Exception Hierarchy

• Find custom exception classes
• Map inheritance relationships
• Look for: Exception, Error, raise, error classes, custom exceptions

Validation Gates

• Find validation/guard functions
• Identify fail-fast patterns
• Look for: validate, check, assert, guard, gate, precondition checks

Error Detection

• Find error detection points
• Identify how failures are recognized
• Look for: try/except, catch, onerror, handleerror, error handling

Recovery Mechanisms

• Find retry logic
• Identify fallback strategies
• Look for: retry, backoff, attempt, max_retries, retry policies

Circuit Breakers

• Find patterns that prevent infinite retries
• Identify failure thresholds
• Look for: circuit, breaker, max_failures, trip, failure thresholds

Error Routing

• Find how errors are propagated
• Identify error terminal states
• Look for: raise, return Error, error node, ERROR state

Step 2: Map Error Paths

For each major operation, document:

• Success Path: Normal completion
• Retry Path: Transient failure recovery
• Failure Path: Permanent failure handling
• Circuit Break Path: Threshold exceeded

CRITICAL - Analyze Read/Write Direction: For EVERY error handling component:

• Error context capture: What data is READ to build error context?
• Error logging: Where are errors WRITTEN (logs, database, files)?
• State updates: What state is WRITTEN on failure?
• Recovery reads: What data is READ during recovery?

Distinguish:

• Error logs (write-only, never read back for logic)
• Failure context in database (may be read for retry/debugging)
• Debug artifacts (write-only diagnostics)

Step 3: Document Recovery Mechanisms

| Mechanism | Trigger | Action | Limit | |-----------|---------|--------|-------| | Retry | Transient error | Repeat operation | max N | | Fallback | Specific error | Alternative action | - | | Circuit Breaker | Too many failures | Stop retrying | threshold |

Step 4: Create the Diagram

Use flowchart with:

Direction: TB for error flow hierarchy

Subgraphs:

• Execution (normal operation)
• Validation Gates (fail-fast checks)
• Error Handling (detection and routing)
• Recovery (retry, fallback)
• Terminals (success, failure states)

Node Styling:

• handler class: Execution nodes
• detector class: Validation gates, error detection
• gap class: Failed/error state (yellow warning)
• stateNode class: Decision points, circuit breaker
• output class: Recovery actions
• terminal class: Final states (success, error)

Connection Types:

• Solid: Normal flow
• Edge labels: Conditions, error types
• Show loops for retry mechanisms

Step 5: Write Output

Write the diagram to: temp/arch-lens-error-resilience/arch_diag_error_resilience_{YYYY-MM-DD_HHMMSS}.md

---

Output Template

# Error/Resilience Diagram: {System Name}

**Lens:** Error/Resilience (Diagnostic)
**Question:** How are failures handled?
**Date:** {YYYY-MM-DD}
**Scope:** {What was analyzed}

## Exception Hierarchy

BaseError ├── ValidationError ├── ProcessingError │ └── RetryableError └── FatalError

## Resilience Diagram

```mermaid
%%{init: {'flowchart': {'nodeSpacing': 40, 'rankSpacing': 50, 'curve': 'basis'}}}%%
flowchart TB
    %% CLASS DEFINITIONS %%
    classDef terminal fill:#1a237e,stroke:#7986cb,stroke-width:2px,color:#fff;
    classDef stateNode fill:#004d40,stroke:#4db6ac,stroke-width:2px,color:#fff;
    classDef handler fill:#e65100,stroke:#ffb74d,stroke-width:2px,color:#fff;
    classDef phase fill:#6a1b9a,stroke:#ba68c8,stroke-width:2px,color:#fff;
    classDef detector fill:#b71c1c,stroke:#ef5350,stroke-width:2px,color:#fff;
    classDef output fill:#00695c,stroke:#4db6ac,stroke-width:2px,color:#fff;
    classDef gap fill:#ff6f00,stroke:#ffa726,stroke-width:2px,color:#000;

    subgraph Execution ["EXECUTION"]
        EXEC["Execute━━━━━━━━━━Main operation"]
        SUCCESS["SUCCESS━━━━━━━━━━Completed"]
        RETRY["RETRY━━━━━━━━━━Transient failure"]
        FAILED["FAILED━━━━━━━━━━Needs handling"]
    end

    subgraph Gates ["VALIDATION GATES (Fail-Fast)"]
        GATE1["Validate Input━━━━━━━━━━Check required fields"]
        GATE2["Validate State━━━━━━━━━━Check preconditions"]
    end

    subgraph Recovery ["RECOVERY MECHANISMS"]
        direction TB
        R_RETRY["Retry with Backoff━━━━━━━━━━Max N attempts"]
        R_FALLBACK["Fallback Action━━━━━━━━━━Alternative path"]
        R_CIRCUIT{"CircuitBreakertriggered?"}
    end

    subgraph Terminals ["TERMINAL STATES"]
        T_COMPLETE([COMPLETE])
        T_ERROR([ERROR])
        T_CIRCUIT([CIRCUIT_BROKEN])
    end

    %% EXECUTION FLOW %%
    EXEC --> SUCCESS
    EXEC --> RETRY
    EXEC --> FAILED

    SUCCESS --> T_COMPLETE
    RETRY -->|"back to queue"| EXEC

    %% VALIDATION GATES %%
    GATE1 -->|"missing"| T_ERROR
    GATE1 -->|"valid"| GATE2
    GATE2 -->|"invalid"| T_ERROR
    GATE2 -->|"valid"| EXEC

    %% RECOVERY %%
    FAILED --> R_CIRCUIT
    R_CIRCUIT -->|"not triggered"| R_RETRY
    R_CIRCUIT -->|"triggered"| T_CIRCUIT
    R_RETRY --> EXEC
    R_RETRY -->|"exhausted"| R_FALLBACK
    R_FALLBACK --> T_ERROR

    %% CLASS ASSIGNMENTS %%
    class EXEC,SUCCESS handler;
    class RETRY,FAILED gap;
    class GATE1,GATE2 detector;
    class R_RETRY,R_FALLBACK output;
    class R_CIRCUIT stateNode;
    class T_COMPLETE,T_ERROR,T_CIRCUIT terminal;

Color Legend: | Color | Category | Description | |-------|----------|-------------| | Orange | Execution | Normal operation and success | | Yellow | Failed | Failure states requiring handling | | Red | Gates | Validation gates (fail-fast) | | Dark Teal | Recovery | Retry and fallback mechanisms | | Teal | Circuit | Circuit breaker decisions | | Dark Blue | Terminal | Final states |

Recovery Mechanisms

| Mechanism | Trigger | Action | Max Attempts | |-----------|---------|--------|--------------| | {name} | {condition} | {what happens} | {limit} |

Validation Gates

| Gate | Checks | Failure Mode | |------|--------|--------------| | {name} | {what validated} | {error raised} |

---

## Pre-Diagram Checklist

Before creating the diagram, verify:

- [ ] LOADED `/mermaid` skill using the Skill tool
- [ ] Using ONLY classDef styles from the mermaid skill (no invented colors)
- [ ] Diagram will include a color legend table

---

## Related Skills

- `/make-arch-diag` - Parent skill for lens selection
- `/mermaid` - MUST BE LOADED before creating diagram
- `/arch-lens-process-flow` - For normal flow view
- `/arch-lens-concurrency` - For parallel failure handling

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [Trecek](https://github.com/Trecek)
- **Source:** [Trecek/useful-claude-skills](https://github.com/Trecek/useful-claude-skills)
- **License:** MIT

Install and usage instructions live in the source repository linked above.