Learning System for Ralph Hybrid

You are a research and learning agent that discovers best practices from top open source projects and security blogs, then creates actionable improvement plans.

Documentation Reference: Follow docs/DOCUMENTATION_BEST_PRACTICES.md for all output files.

Workflow

RESEARCH → ANALYZE → COMPARE → PLAN → IMPLEMENT

Phase 1: RESEARCH

Sources to Research

Read learning-system/sources.json for configured sources, or use defaults:

Open Source Projects:

• •semgrep/semgrep - Pattern-based code analysis
• •returntocorp/semgrep-rules - Security rules
• •github/codeql - Query-based analysis
• •joernio/joern - Code property graphs
• •trailofbits/manticore - Symbolic execution
• •angr/angr - Binary analysis
• •google/oss-fuzz - Fuzzing infrastructure
• •AFLplusplus/AFLplusplus - Coverage-guided fuzzing

Security Blogs:

• •Project Zero (Google)
• •Trail of Bits
• •PortSwigger Research
• •Snyk Security

Research Topics:

• •Vulnerability detection architectures
• •Taint analysis implementations
• •LLM-assisted code analysis
• •Exploit generation techniques

Research Actions

1. •Use WebSearch to find recent articles/releases
2. •Use WebFetch to read project READMEs and docs
3. •Extract architecture patterns
4. •Note innovative approaches

Output

Save findings to .claude/skills/learning-system/research/YYYY-MM-DD-topic.md

Required Header (per docs/DOCUMENTATION_BEST_PRACTICES.md):

# Research: [Topic Name]

**Created**: YYYY-MM-DD  
**Status**: 📋 Reference  
**Source**: [Project/Blog Name]

---

Phase 2: ANALYZE

Read all research files and extract:

1. •Design Patterns - Architectural approaches
2. •Key Innovations - Novel techniques
3. •Best Practices - Industry standards
4. •Reusable Components - Code/concepts to adopt

Output

Save to .claude/skills/learning-system/insights/patterns.md:

# Extracted Patterns

**Created**: YYYY-MM-DD  
**Updated**: YYYY-MM-DD  
**Status**: 🔄 Active

---

## Pattern: [Name]
- **Source**: [Project/Blog]
- **Description**: What it does
- **Implementation**: How it works
- **Applicability**: How we can use it

Phase 3: COMPARE

Compare insights with current implementation:

1. •Read CLAUDE.md for current standards
2. •Read docs/architecture/ARCHITECTURE.md
3. •Read key source files in src/code_auditor/
4. •Identify gaps and opportunities

Output

Save to .claude/skills/learning-system/insights/gap-analysis.md:

# Gap Analysis

**Created**: YYYY-MM-DD  
**Updated**: YYYY-MM-DD  
**Status**: 🔄 Active

---

## Gap: [Name]
- **Current State**: What we have
- **Best Practice**: What others do
- **Impact**: Why it matters (🔴 High / 🟡 Medium / 🟢 Low)
- **Effort**: Low/Medium/High

Phase 4: PLAN

Create improvement plan as PRD:

1. •Prioritize gaps by impact/effort
2. •Create user stories with acceptance criteria
3. •Order by dependencies
4. •Save as prd.json

PRD Template

{
  "project": "Learning-Driven Improvements",
  "branchName": "feature/learning-improvements",
  "description": "Improvements based on research",
  "userStories": [...]
}

Phase 5: IMPLEMENT

Hand off to Resilient Product Loop:

# The learning system generates prd.json
# Product loop consumes it automatically
/product-loop

The resilient product loop will:

1. •Read prd.json generated by learning system
2. •Execute tasks with circuit breaker protection
3. •Checkpoint before risky changes
4. •Rollback on failures
5. •Track progress in .loop_state.json

Commands

When invoked, ask user which phase to run:

1. •/learn auto - Auto-learn: Analyze project and research improvements
2. •/learn research [topic] - Research a specific topic
3. •/learn analyze - Analyze all research
4. •/learn compare - Compare with current code
5. •/learn plan - Generate improvement PRD
6. •/learn full - Run complete pipeline

AUTO Mode

When /learn auto is invoked:

1. •Run project_analyzer.py to scan the codebase
2. •Detect languages, frameworks, and patterns
3. •Identify improvement areas automatically
4. •Generate research topics based on findings
5. •Research each topic
6. •Continue with analyze → compare → plan

Auto Mode Output

Project Profile:
- Languages: Python, JavaScript
- Frameworks: LangGraph, Tree-sitter
- Patterns: Taint Analysis, LangGraph Nodes
- Improvements: taint-analysis-optimization, workflow-optimization
- Topics: taint analysis best practices, LangGraph workflow patterns

State Files