Claude: Self-Learning Protocol - Universal Pattern for All Tasks

self-learning-protocol.mdc

---
description: Self-Learning Protocol - Universal Pattern for All Tasks
globs:
alwaysApply: true
---

# Self-Learning Protocol (MANDATORY)

**A fundamental working methodology that applies to ALL tasks - every action taken during development, testing, debugging, and implementation.**

## The Universal Self-Learning Cycle

```
1. ATTEMPT → Try an approach
2. VERIFY → Check if it worked (always verify observable results)
3. LEARN → Analyze what happened
   ✅ Success → Document the working pattern
   ❌ Failure → Document why it failed + alternative approach
4. UPDATE → Immediately update relevant documentation/rules
5. APPLY → Use the learned pattern going forward
6. REPEAT → Apply this cycle to every action
```

**This is not optional. This is how to work on ANY task.**

## Core Principles

### 1. Never Repeat Failed Patterns
- If approach X failed, document it immediately
- Don't try the same approach again without modification
- Switch to documented alternative or explore new approach

### 2. Build on Successful Patterns
- If approach Y worked, reuse that pattern
- Document why it worked for future reference
- Apply the pattern to similar situations

### 3. Update Documentation Immediately
- Don't batch documentation updates
- Document in-flow as you learn
- Keep rules and patterns current in real-time

### 4. Fail Forward
- Each failure teaches what doesn't work
- Failures narrow the solution space
- Document failures as anti-patterns, not setbacks

### 5. Create Feedback Loops
- Each verification informs the next action
- Results shape the next approach
- Build cumulative knowledge during task execution

### 6. No Blind Execution
- Always verify before proceeding to next step
- Check observable results after every action
- Don't assume success - verify it

## Documentation Types

### Pattern Library
Document approaches that work reliably:
```markdown
[PATTERN] <Name of pattern>
[WORKS BECAUSE] <Why this approach succeeds>
[USE WHEN] <Situations where this applies>
[EXAMPLE] <Concrete example>
```

### Anti-Patterns
Document approaches that fail:
```markdown
[ANTI-PATTERN] <Name of failed approach>
[FAILS BECAUSE] <Why this doesn't work>
[ALTERNATIVE] <What to use instead>
[SYMPTOMS] <How to recognize this failure>
```

### Workarounds
Document alternatives when primary approach fails:
```markdown
[WORKAROUND] <When primary fails>
[PRIMARY APPROACH] <Ideal solution>
[WHEN IT FAILS] <Failure conditions>
[WORKAROUND] <Alternative approach>
[TRADEOFFS] <What you lose with workaround>
```

### Context-Specific Rules
Document domain/project specific learnings:
```markdown
[CONTEXT] <Technology/domain>
[LEARNED] <Specific discovery>
[PROBLEM] <Issue encountered>
[SOLUTION] <How to solve it>
[PREVENTION] <How to avoid in future>
```

### Failure Analysis
Document root causes of failures:
```markdown
[FAILURE] <What didn't work>
[ROOT CAUSE] <Underlying reason>
[INVESTIGATION] <How you discovered it>
[FIX] <Solution applied>
[PREVENTION] <How to avoid this>
```

## Real-Time Documentation Format

Use this format during execution:

```markdown
[ATTEMPT] Trying approach X
[VERIFY] Checking result...
[RESULT] ✅/❌ Observable outcome
[LEARN] Pattern X works/fails because Y
[UPDATE] Documented in <location>
[APPLY] Using learned pattern for next step
```

## The Self-Improving System

This creates a system where:

1. **Learning is continuous** - Every action is a learning opportunity
2. **Documentation stays current** - Updated in real-time, never stale
3. **Patterns emerge organically** - Successful approaches naturally surface
4. **Efficiency improves over time** - Reuse proven patterns, avoid failed ones
5. **Failures become learning** - Document anti-patterns
6. **Knowledge compounds** - Context accumulates across tasks
7. **Adaptation is automatic** - Apply learned patterns immediately

## Universal Application Examples

### Example 1: Code Implementation
```markdown
[ATTEMPT] Using useMemo to watch form state
[VERIFY] Checking if component re-renders when form changes...
[RESULT] ❌ Component doesn't re-render, lots don't display
[LEARN] useMemo doesn't create reactive subscription
[UPDATE] Documented in self-learning-protocol.mdc
[APPLY] Switching to useEffect with watch() callback
[ATTEMPT] Using watch() with callback in useEffect
[VERIFY] Changing form state and checking component...
[RESULT] ✅ Component re-renders, lots display correctly
[LEARN] watch() with callback creates reactive subscription
[UPDATE] Documented working pattern in implementation plan
[APPLY] Using this pattern for other form state subscriptions
```

### Example 2: Debugging
```markdown
[ATTEMPT] Running tests to find failure point
[VERIFY] Checking test output...
[RESULT] ❌ 3 tests failing with "Cannot read property 'x' of undefined"
[LEARN] Component accessing prop before it's loaded
[UPDATE] Documented pattern in debugging notes
[APPLY] Adding null checks before accessing nested properties
[ATTEMPT] Adding optional chaining (?)
[VERIFY] Re-running tests...
[RESULT] ✅ All tests pass
[LEARN] Optional chaining prevents undefined errors
[UPDATE] Added to code quality checklist
[APPLY] Using optional chaining for all nested prop access
```

### Example 3: API Integration
```markdown
[ATTEMPT] Calling GraphQL mutation without error handling
[VERIFY] Checking mutation result...
[RESULT] ❌ Network error, app crashes
[LEARN] Unhandled promise rejection crashes app
[UPDATE] Documented in API integration patterns
[APPLY] Adding try-catch and error state
[ATTEMPT] Calling mutation with error handling
[VERIFY] Simulating network failure...
[RESULT] ✅ Error displayed to user, app stable
[LEARN] Error boundaries + try-catch = resilient API calls
[UPDATE] Added to implementation checklist
[APPLY] Using this pattern for all mutations
```

## Domain-Specific Applications

This universal pattern is applied differently in each domain. See domain-specific guides:

- **Browser Automation**: `.cursor/rules/browser-automation-self-learning.mdc`
- **Code Implementation**: `.cursor/rules/code-implementation-self-learning.mdc`
- **Debugging**: `.cursor/rules/debugging-self-learning.mdc`

Each guide shows how to apply the universal cycle to that specific domain with concrete examples and verification techniques.

## Integration with Other Protocols

### Works With Context Management Protocol
- Document immediately when patterns discovered (not at end)
- Update working patterns in real-time
- Build cumulative knowledge across sessions

### Works With Technical Precision Rule
- State "I don't know" when uncertain (don't guess)
- Document observable facts, not assumptions
- Verify before concluding

### Works With Protocol Enforcer
- Document before file operations
- Ensure learnings are captured
- Maintain protocol compliance

## Critical Reminder

**Every action → Verify → Learn → Document → Apply → Repeat**

This applies to:
- Writing code
- Running tests
- Making API calls
- Navigating UIs
- Debugging issues
- Researching solutions
- Implementing features
- Analyzing problems
- Making decisions
- Tool usage
- Process execution

**If you're doing something, you're learning. If you're learning, you're documenting.**