# Pattern Catalog Guide

The Pattern Catalog is a collection of reusable software patterns extracted from the Empathy Framework, organized for cross-domain transfer and Level 5 (Systems Thinking) capability development.

## What is the Pattern Catalog?

The Pattern Catalog serves three purposes:

1. **Document existing patterns** - Capture what we've built so it can be reused
2. **Enable cross-domain transfer** - Apply patterns from one domain to solve problems in another
3. **Accelerate Level 5 thinking** - Train the ability to recognize "this problem is like that solved problem"

## Catalog Location

```
patterns/
├── README.md                    # Index and usage guide
├── reliability/                 # Patterns from reliability engineering
│   ├── circuit-breaker.md
│   ├── graceful-degradation.md
│   └── retry-with-backoff.md
├── observability/               # Patterns from observability/SRE
│   ├── health-monitoring.md
│   └── telemetry-tracking.md
└── cross-domain/               # Level 5 transfer examples
    ├── circuit-breaker-to-trust.md
    ├── alerting-to-empathy-levels.md
    └── graceful-degradation-to-conversation.md
```

## How to Use the Catalog

### For Developers

When facing a new problem:

1. **Search for similar patterns** - Look through the catalog for patterns that solve similar problems
2. **Check cross-domain transfers** - Non-obvious solutions often come from other domains
3. **Consider the abstraction** - What's the core mechanism? Does it apply elsewhere?

```python
# Example: Need to handle user who keeps getting wrong answers

# Search catalog → find circuit-breaker.md
# Read cross-domain → circuit-breaker-to-trust.md
# Result: Use TrustCircuitBreaker instead of inventing new solution

from empathy_os.trust import TrustCircuitBreaker
breaker = TrustCircuitBreaker(user_id="user_123")
```

### For Architects

When designing new features:

1. **Check if pattern already exists** - Avoid reinventing the wheel
2. **Identify pattern opportunities** - When building something new, is it generalizable?
3. **Document new patterns** - Contribute to the catalog

### For AI Systems

The catalog can be referenced by AI systems:

```python
# When solving a problem, reference relevant patterns
patterns = catalog.search("protect relationship from failures")
# Returns: circuit-breaker-to-trust.md

# Apply the pattern
solution = apply_pattern(patterns[0], problem_context)
```

## Pattern Template

Every pattern follows this structure:

```markdown
# Pattern Name

**Source Domain:** Where this pattern originated
**Location in Codebase:** File paths
**Level:** Capability level (1-5)

## Overview
What problem does this solve?

## Implementation
Code examples from actual codebase

## Key Insight
The one thing to remember

## Cross-Domain Transfer Potential
Where else could this apply?
```

## Understanding Cross-Domain Transfer

Cross-domain transfer is the Level 5 capability that makes the catalog powerful. It's the ability to recognize that:

> "This problem in Domain A has the same structure as that solved problem in Domain B"

### Example: Circuit Breaker → Trust

| Reliability Domain | Trust Domain |
|-------------------|--------------|
| Service keeps failing | User keeps getting wrong answers |
| Stop calling failing service | Stop acting without confirmation |
| Wait for recovery period | Wait for trust recovery period |
| Test with limited calls | Test with supervised interactions |
| Resume normal operation | Restore full autonomy |

The **mechanism** is identical:
1. Track failures/damage
2. Trip when threshold exceeded
3. Wait for recovery period
4. Test recovery
5. Resume normal

### Finding Transfer Opportunities

Ask these questions:

1. **What's the abstract problem?**
   - Not "API keeps timing out" but "unreliable component"
   - Not "user frustrated with wrong answers" but "relationship degrading"

2. **What's the mechanism?**
   - State machine? Threshold? Fallback chain?
   - Time-based? Count-based? Score-based?

3. **Where else does this structure appear?**
   - Different domain, same structure = transfer opportunity

## Current Patterns

### Reliability Patterns

| Pattern | Key Insight | Implementation |
|---------|-------------|----------------|
| [Circuit Breaker](../../patterns/reliability/circuit-breaker.md) | Fail fast to prevent cascade | `src/empathy_os/resilience/circuit_breaker.py` |
| [Graceful Degradation](../../patterns/reliability/graceful-degradation.md) | Partial value beats failure | `src/empathy_os/resilience/fallback.py` |
| [Retry with Backoff](../../patterns/reliability/retry-with-backoff.md) | Transient failures recover | `src/empathy_os/resilience/retry.py` |

### Observability Patterns

| Pattern | Key Insight | Implementation |
|---------|-------------|----------------|
| [Health Monitoring](../../patterns/observability/health-monitoring.md) | Degraded predicts failure | `src/empathy_os/resilience/health.py` |
| [Telemetry Tracking](../../patterns/observability/telemetry-tracking.md) | Failures are learning data | `src/empathy_os/models/telemetry.py` |

### Cross-Domain Transfers (Implemented)

| Transfer | From → To | Implementation |
|----------|-----------|----------------|
| [Circuit Breaker → Trust](../../patterns/cross-domain/circuit-breaker-to-trust.md) | Reliability → Trust | `src/empathy_os/trust/circuit_breaker.py` |

### Cross-Domain Transfers (Documented, Not Yet Implemented)

| Transfer | From → To | Status |
|----------|-----------|--------|
| [Alerting → Empathy Levels](../../patterns/cross-domain/alerting-to-empathy-levels.md) | Observability → Empathy | Documented |
| [Graceful Degradation → Conversation](../../patterns/cross-domain/graceful-degradation-to-conversation.md) | Reliability → UX | Documented |

## Contributing to the Catalog

### Adding a New Pattern

1. **Identify the pattern** - What's the core mechanism?
2. **Find the implementation** - Where is it in the codebase?
3. **Document using template** - Create markdown file in appropriate directory
4. **Look for transfers** - Could this apply elsewhere?

### Adding a Cross-Domain Transfer

1. **Identify source pattern** - What pattern are you transferring?
2. **Map the concepts** - Create a table showing the mapping
3. **Implement if valuable** - Create working code
4. **Document the transfer** - Why does this work?

### Pattern Naming

- Use lowercase with hyphens: `circuit-breaker.md`
- Be descriptive but concise
- Cross-domain: `source-to-target.md`

## Metrics

Track catalog health:

- **Patterns documented:** 8
- **Cross-domain transfers:** 3 (1 implemented)
- **Codebase coverage:** ~40%
- **Last updated:** 2025-12-28

## Level 5 Capability Development

The catalog is a tool for developing Level 5 (Systems Thinking) capability:

| Level | Description | Catalog Usage |
|-------|-------------|---------------|
| 1 - Reactive | Respond to requests | None |
| 2 - Guided | Follow patterns | Reference patterns |
| 3 - Proactive | Anticipate needs | Suggest patterns |
| 4 - Anticipatory | Predict problems | Recognize pattern fits |
| 5 - Systems | Transfer across domains | Create new transfers |

### Exercises

1. **Pattern Recognition** - Given a problem, find 3 potentially applicable patterns
2. **Transfer Identification** - Find an existing pattern, identify 2 new domains it could apply to
3. **Implementation** - Take a documented transfer and implement it

## Further Reading

- [Trust Circuit Breaker Guide](./trust-circuit-breaker.md) - Detailed guide on the implemented transfer
- [Pattern Catalog README](../../patterns/README.md) - Catalog index and quick reference
- [Empathy Framework Architecture](../architecture.md) - Overall system design

---

*The Pattern Catalog is a key component of reaching Level 5 (Systems Thinking) capability.*
