vamfi/claude-user-memory/pattern-recognition

Pattern Recognition Skill

This skill provides systematic methodology for identifying reusable patterns from completed work and automatically updating the knowledge core to preserve institutional knowledge across sessions.

When Claude Should Use This Skill

Claude will automatically invoke this skill when:

• Implementation successfully completed (tests passing)
• @code-implementer finishes major feature work
• Chief-architect synthesizes results from multiple agents
• User explicitly requests pattern documentation
• Stop hook triggers (end of session)

Core Principles (BRAHMA Constitution)

1. Knowledge preservation - Capture patterns for future use
2. Reproducibility - Document enough detail to replicate pattern
3. Simplicity - Extract essential pattern, not every detail
4. Verification - Patterns should be validated by actual code
5. Adaptive learning - Learn from outcomes to suggest proven patterns (NEW v3.1)

Before Implementation (Pattern Suggestion - NEW v3.1)

Trigger: User requests feature implementation via /workflow, /implement, or direct agent invocation

Purpose: Leverage past implementation success to accelerate current work by suggesting proven patterns proactively

Pattern Suggestion Workflow

Step 1: Context Extraction (< 5 seconds)

Extract context tags from user request to find similar past implementations:

• Technology keywords: "nodejs", "python", "redis", "postgresql", "express", "fastapi"
• Problem domain: "authentication", "caching", "logging", "error-handling", "validation"
• Solution type: "service-layer", "repository", "factory", "middleware", "api"

Example:

User request: "Add JWT authentication to Express API"
Extracted tags: ["nodejs", "express", "authentication", "jwt", "security"]

Step 2: Pattern Lookup (< 2 seconds)

Read ~/.claude/data/pattern-index.json
Find patterns with ≥60% context tag overlap (similarity matching)
Filter to HIGH confidence patterns only (confidence ≥ 0.80)
Rank by: confidence DESC, quality DESC, recency DESC
Return top 3 patterns

Graceful Degradation:

try:
    pattern_index = read_json('~/.claude/data/pattern-index.json')
    suggestions = suggest_patterns(context_tags, pattern_index)
except (FileNotFoundError, JSONDecodeError):
    logger.warning("pattern-index.json unavailable, skipping suggestions")
    suggestions = []  # Proceed without suggestions
    # User impact: ZERO (workflow continues normally)

Step 3: Present Suggestions (user interaction)

If HIGH confidence patterns found, show top 3:

💡 Suggested patterns based on past implementations:
 
1.[HIGH CONFIDENCE: 92%] JWT Authentication Middleware Pattern
   -Used 8 times, 7 successes (88% success rate)
   -Average time: 12 minutes, Average quality: 89/100
   -Context match: 85% similar to your request
   -See: knowledge-core.md#jwt-authentication-middleware-pattern
 
2.[HIGH CONFIDENCE: 85%] Token Refresh Pattern
   -Used 5 times, 4 successes (80% success rate)
   -Average time: 15 minutes, Average quality: 85/100
   -See: knowledge-core.md#token-refresh-pattern
 
Use suggested pattern? (y/n/view)

Step 4: User Response Handling

• User accepts (y): Track acceptance, use pattern in implementation
• User rejects (n): Track rejection, proceed without pattern
• User views (view): Show full pattern from knowledge-core.md, ask again
• No response: Proceed without pattern (don't block workflow)

Step 5: Record User Feedback

Update pattern acceptance tracking in pattern-index.json:

{
  "user_acceptance_rate": (accepted_count + 1) / (total_suggestions + 1),
  "total_suggestions": total_suggestions + 1
}

Performance Target: < 7 seconds total for suggestion workflow

Pattern Recognition Methodology

Step 1: Implementation Analysis (< 30 seconds)

Objective: Review what was just implemented to identify patterns

Analysis questions:

1. Architectural patterns:

• What high-level structure was used? (Service layer, Repository, Factory, etc.)
• How are concerns separated? (Business logic, data access, presentation)
• What design patterns were applied? (Singleton, Strategy, Observer, etc.)

1. Integration patterns:

• How does new code connect to existing code?
• What interfaces/contracts were established?
• How is dependency injection handled?

1. Error handling patterns:

• How are errors caught and handled?
• What logging/monitoring was added?
• How are errors propagated to callers?

1. Testing patterns:

• What test structure was used? (AAA: Arrange-Act-Assert, etc.)
• How are mocks/stubs created?
• What edge cases were covered?

1. Configuration patterns:

• How are environment-specific values managed?
• Where do defaults live?
• How is configuration validated?

Data to extract:

• File paths demonstrating pattern
• Code snippets showing key concepts
• When this pattern should/shouldn't be used
• Alternatives considered and why rejected

Step 2: Pattern Classification (< 15 seconds)

Classify into knowledge-core.md sections:

Section 1: Architectural Principles (high-level rules)

• Broad guidelines affecting entire codebase
• Example: "Use dependency injection for all external services"
• Example: "All API routes must have auth middleware"
• Example: "Database queries must go through repository layer"

Section 2: Established Patterns (concrete implementations)

• Specific, reusable implementation patterns
• Include: Pattern name, context, implementation example, files
• Example: "Service Layer Pattern for business logic"
• Example: "Factory pattern for creating Redis clients"

Section 3: Key Decisions & Learnings (chronological log)

• Decisions made during specific implementations
• Include: Date, decision, rationale, alternatives considered
• Example: "2025-10-17: Chose Redis over Memcached for caching (reason: better data structure support)"
• Learnings from mistakes or discoveries

Classification criteria:

• Principle: Applies across many features/files
• Pattern: Reusable template for specific problem
• Decision: One-time choice with lasting impact
• Learning: New insight or gotcha discovered

Step 3: Pattern Documentation (< 30 seconds)

For each pattern identified, document:

### Pattern: [Descriptive Name]
 
**Context**: [When to use this pattern]
-Use when: [Specific scenarios]
-Don't use when: [Scenarios where it doesn't fit]
 
**Problem**: [What problem does this solve?]
 
**Solution**:
[Brief description of the pattern]
 
**Implementation Example**:

// Minimal code example showing pattern // File: path/to/example.ts

 
**Files Demonstrating Pattern**:
- `path/to/file1.ts` - [What aspect it demonstrates]
- `path/to/file2.ts` - [What aspect it demonstrates]
 
**Related Patterns**:
- [Other patterns that work well with this]
 
**Trade-offs**:
- ✅ Benefits: [List]
- ⚠️ Costs: [List]
 
**Alternatives Considered**:
1. [Alternative 1] - Rejected because [reason]
2. [Alternative 2] - Rejected because [reason]

Quality criteria:

• Actionable: Another developer can apply this pattern from the description
• Specific: Not vague generalities ("use good code" → ❌)
• Verified: Pattern is actually implemented in referenced files
• Complete: Includes when to use AND when not to use

Step 4: Knowledge Core Update (< 20 seconds)

Update `knowledge-core.md` following its structure:

# Knowledge Core
 
Last Updated: [ISO date]
Version: [increment version number]
 
## 1. Architectural Principles
 
### [New principle if identified]
[Description]
 
**Rationale**: [Why this principle]
**Established**: [Date]
**Applies to**: [Which parts of codebase]
 
---
 
## 2. Established Patterns
 
### [New pattern from Step 3]
[Full pattern documentation]
 
---
 
## 3. Key Decisions & Learnings
 
### [YYYY-MM-DD] [Decision Title]
**Decision**: [What was decided]
**Context**: [What prompted this decision]
**Alternatives**: [What else was considered]
**Rationale**: [Why this was chosen]
**Implementation**: See `[files]`
**Status**: [Active / Superseded by [link]]
 
---

Update protocol:

1. Read current knowledge-core.md
2. Check for duplicates (don't add pattern if it already exists)
3. Append new patterns to appropriate sections
4. Increment version number
5. Update "Last Updated" timestamp
6. Write updated file

Merge strategy (if pattern partially exists):

• Enhance existing pattern with new examples/files
• Note that pattern was "reinforced" in latest implementation
• Don't create duplicate entries

Step 5: Outcome Metrics Capture (< 10 seconds) - NEW v3.1

Purpose: Track implementation outcomes for pattern learning and confidence scoring

Metrics to Capture:

1. Success/Failure Classification:

``python success = ( all_tests_passing AND quality_gates_passed AND no_rollback_required ) ``

1. Implementation Duration:

``python duration_minutes = (end_time - start_time).total_seconds() / 60 # Start time: When @code-implementer begins # End time: When tests pass and implementation complete ``

1. Quality Scores (if available from /workflow):

``python quality_score = (research_pack_score + implementation_plan_score) / 2 # Only available if full workflow used (research + plan phases) ``

1. Self-Correction Count:

``python retry_count = number_of_self_correction_attempts # Reported by @code-implementer (0-3 range, lower is better) ``

1. User Acceptance (if pattern was suggested):

``python pattern_was_accepted = user_selected_yes_to_suggestion ``

Data Structure:

outcome_metrics = {
    "success": True,  # or False
    "duration_minutes": 12.5,
    "quality_score": 87,  # or None if not available
    "retry_count": 1,
    "pattern_used": "JWT Authentication Middleware Pattern",  # or None
    "pattern_was_suggested": True,
    "pattern_was_accepted": True,
    "timestamp": "2025-10-25T14:30:00Z"
}

Capture Process:

1. Collect metrics from @code-implementer at end of implementation
2. Classify success/failure based on tests and quality gates
3. Calculate duration from timestamps
4. Retrieve quality scores from research/plan phases (if available)
5. Package into outcome_metrics structure
6. Pass to pattern-index.json update step

Step 6: pattern-index.json Update (< 15 seconds) - NEW v3.1

Purpose: Update pattern metrics for adaptive learning and future suggestions

Update Workflow:

1. Read Current pattern-index.json:

try:
    pattern_index = read_json('~/.claude/data/pattern-index.json')
except (FileNotFoundError, JSONDecodeError):
    logger.warning("pattern-index.json missing/corrupted, skipping metrics update")
    return  # Continue with knowledge-core.md update only (graceful degradation)

2. Find or Create Pattern Entry:

pattern_name = "JWT Authentication Middleware Pattern"  # From pattern recognition
if pattern_name not in pattern_index['patterns']:
    # Create new pattern entry with conservative defaults
    pattern_index['patterns'][pattern_name] = {
        "pattern_id": generate_kebab_case_id(pattern_name),
        "total_uses": 0,
        "successes": 0,
        "failures": 0,
        "avg_time_minutes": 0,
        "avg_quality_score": 0,
        "quality_scores": [],
        "last_used": today_iso(),
        "first_used": today_iso(),
        "confidence": 0.5,  # Start conservative (MEDIUM)
        "confidence_level": "MEDIUM",
        "context_tags": extract_tags_from_pattern(),
        "related_patterns": [],
        "anti_pattern": False,
        "deprecation_warning": None,
        "user_acceptance_rate": 0.0,
        "self_correction_avg": 0.0
    }