# Pattern Examples

This directory contains real-world examples of CALF files matching core Cleave patterns, along with detailed analysis of each pattern.

## Available Patterns

### 1. Authentication System
**File**: `authentication-system.calf`
**Documentation**: `authentication-system.md`

Demonstrates JWT authentication implementation alongside existing session auth. Shows:
- Security-critical pattern recognition
- Migration path planning
- Dual-mode authentication strategy
- Binary or ternary splitting options

**Complexity**: 6.0-8.0
**Confidence**: 0.85

### 2. Database Migration
**File**: `database-migration.calf`
**Documentation**: `database-migration.md`

Demonstrates soft delete implementation with schema changes and backfill. Shows:
- Schema migration strategy
- Data backfill coordination
- Query update patterns
- Performance considerations (indexing)

**Complexity**: 5.5-7.0
**Confidence**: 0.90

### 3. External Integration
**File**: `external-integration.calf`
**Documentation**: `external-integration.md`

Demonstrates Stripe payment integration with webhook handling. Shows:
- Third-party API integration
- Webhook reliability patterns
- State synchronization strategies
- Security considerations

**Complexity**: 7.5-9.0
**Confidence**: 0.90

### 4. API Refactor
**File**: `api-refactor.calf` (from root examples/)

Demonstrates async/await refactoring for performance. Shows:
- Performance optimization pattern
- Backwards compatibility maintenance
- Connection pool management
- Integration testing requirements

**Complexity**: 6.0-7.5
**Confidence**: 0.80

## Pattern Documentation Structure

Each pattern includes:

1. **Pattern Characteristics**: What makes this pattern recognizable
2. **Expected Systems**: Which architectural boundaries are involved
3. **Expected Modifiers**: Complexity factors (security, state, migration, etc.)
4. **Recommended Splitting**: Binary or ternary decomposition strategies
5. **Key Considerations**: Domain-specific concerns (security, performance, etc.)
6. **Expected Conflicts**: Likely reunification conflicts
7. **Verification Commands**: How to test the implementation
8. **Success Criteria**: Objective measures of completion
9. **Common Pitfalls**: Mistakes to avoid

## Using Pattern Examples

### Step 1: Match Your Directive

```bash
# See if your directive matches a known pattern
cleave match --directive "$(cat your-directive.calf)"
```

### Step 2: Review Pattern Documentation

Read the corresponding `.md` file to understand:
- Why this pattern was recognized
- What splitting strategy is recommended
- What conflicts to expect during reunification

### Step 3: Assess Complexity

```bash
# Confirm the complexity assessment
cleave assess --directive "$(cat your-directive.calf)"
```

### Step 4: Execute with Context

Use the pattern documentation to inform your implementation:
- Follow the recommended splitting strategy
- Anticipate the expected conflicts
- Use the verification commands to test

## Pattern Confidence Levels

- **0.90+**: High confidence, well-established pattern
- **0.80-0.89**: Good confidence, common pattern with variations
- **0.70-0.79**: Moderate confidence, pattern needs refinement
- **< 0.70**: Low confidence, consider custom splitting

## Adding New Patterns

To contribute a new pattern example:

1. Create `pattern-name.calf` with a clear, complete directive
2. Create `pattern-name.md` following the structure above
3. Test with `cleave assess` and `cleave match`
4. Document expected complexity range and confidence
5. Include verification commands and success criteria

## Pattern Library Location

The authoritative pattern definitions live in:
- `src/cleave/core/assessment.py` (pattern matching logic)
- `src/cleave/skill/SKILL.md` (pattern descriptions)

These examples demonstrate how the patterns are applied in practice.
