Initial commit

skills/oracle/References/integration-guide.md

@@ -0,0 +1,344 @@
+# Oracle Integration Guide
+
+This guide explains how to integrate Oracle into your development workflow for maximum effectiveness.
+
+## Integration Methods
+
+### 1. claude.md Integration (Recommended)
+
+The `claude.md` file is automatically loaded by Claude Code at session start. Integrating Oracle here ensures context is always available.
+
+#### Setup
+
+1. Create or open `claude.md` in your project root:
+
+```bash
+touch claude.md
+```
+
+2. Add Oracle context section:
+
+```markdown
+# Project Documentation
+
+## Project Knowledge (Oracle)
+
+<!-- ORACLE_CONTEXT_START -->
+<!-- Auto-updated by Oracle - Do not edit manually -->
+
+Run to update:
+```bash
+python .claude/skills/oracle/scripts/generate_context.py --output claude.md --update
+```
+
+<!-- ORACLE_CONTEXT_END -->
+
+## Project Overview
+
+[Your project description...]
+```
+
+3. Update Oracle context:
+
+```bash
+python .claude/skills/oracle/scripts/generate_context.py --output claude.md --update
+```
+
+4. (Optional) Add to your workflow to auto-update after sessions.
+
+#### Auto-Update
+
+Add to your session workflow:
+
+```bash
+# After recording a session
+python .claude/skills/oracle/scripts/record_session.py --interactive
+python .claude/skills/oracle/scripts/generate_context.py --output claude.md --update
+```
+
+### 2. Session Start Hooks
+
+Load Oracle context automatically when Claude Code starts.
+
+#### Setup
+
+1. Create hooks directory:
+
+```bash
+mkdir -p .claude/hooks
+```
+
+2. Create session-start hook:
+
+```bash
+cat > .claude/hooks/session-start.sh << 'EOF'
+#!/bin/bash
+# Load Oracle context at session start
+
+python .claude/skills/oracle/scripts/load_context.py
+EOF
+
+chmod +x .claude/hooks/session-start.sh
+```
+
+3. Claude Code will run this hook at session start.
+
+### 3. Git Hooks Integration
+
+Track commits in Oracle timeline automatically.
+
+#### Setup
+
+1. Create post-commit hook:
+
+```bash
+cat > .git/hooks/post-commit << 'EOF'
+#!/bin/bash
+# Record commit in Oracle timeline
+
+python .claude/skills/oracle/scripts/record_commit.py
+EOF
+
+chmod +x .git/hooks/post-commit
+```
+
+2. Commits are now automatically tracked in `.oracle/timeline/project_timeline.md`.
+
+### 4. CI/CD Integration
+
+Update Oracle knowledge as part of your CI/CD pipeline.
+
+#### Example: GitHub Actions
+
+```yaml
+name: Update Oracle
+
+on:
+  push:
+    branches: [ main ]
+
+jobs:
+  update-oracle:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Update Oracle Timeline
+        run: |
+          python .claude/skills/oracle/scripts/record_commit.py
+
+      - name: Update claude.md
+        run: |
+          python .claude/skills/oracle/scripts/generate_context.py --output claude.md --update
+
+      - name: Commit changes
+        run: |
+          git config --local user.email "oracle@bot"
+          git config --local user.name "Oracle Bot"
+          git add claude.md
+          git diff --quiet && git diff --staged --quiet || git commit -m "Update Oracle context [skip ci]"
+          git push
+```
+
+## Workflow Patterns
+
+### Pattern 1: Active Learning
+
+**For:** Projects where you're learning and making frequent corrections.
+
+**Workflow:**
+1. Work on tasks
+2. When corrected, immediately record: `python .claude/skills/oracle/scripts/record_session.py --corrections "wrong->right"`
+3. Context auto-updates for next session
+4. Corrections are avoided in future
+
+**Best for:** New projects, learning new technologies
+
+### Pattern 2: Pattern Detection
+
+**For:** Mature projects with established patterns.
+
+**Workflow:**
+1. Record sessions regularly
+2. Weekly: Run pattern analysis `python .claude/skills/oracle/scripts/analyze_patterns.py --generate-scripts`
+3. Review and customize generated scripts
+4. Use scripts for repeated tasks
+
+**Best for:** Established projects, teams with repeated workflows
+
+### Pattern 3: Knowledge Sharing
+
+**For:** Team projects where knowledge needs to be shared.
+
+**Workflow:**
+1. Each team member records sessions
+2. Knowledge base synced via git
+3. `claude.md` updated and committed
+4. All team members benefit from shared learning
+
+**Best for:** Team projects, open source projects
+
+### Pattern 4: Documentation Sync
+
+**For:** Projects where documentation must stay current.
+
+**Workflow:**
+1. Record sessions with learnings
+2. Use Oracle with documentation skill/tool
+3. Auto-generate documentation updates from learnings
+4. Review and commit documentation
+
+**Best for:** Projects requiring up-to-date docs
+
+## Context Injection Strategies
+
+### Strategy 1: Minimal Context (Default)
+
+Load only critical and high-priority items.
+
+```bash
+python .claude/skills/oracle/scripts/generate_context.py --tier 1
+```
+
+**Pros:** Low token usage, fast loading
+**Cons:** May miss relevant context
+**Use when:** Token budget is tight
+
+### Strategy 2: Relevant Context
+
+Load context relevant to current task.
+
+```bash
+python .claude/skills/oracle/scripts/generate_context.py --task "implement authentication"
+```
+
+**Pros:** Highly relevant, moderate token usage
+**Cons:** Requires knowing the task upfront
+**Use when:** Starting a specific task
+
+### Strategy 3: Full Context
+
+Load all available knowledge.
+
+```bash
+python .claude/skills/oracle/scripts/generate_context.py --tier 3
+```
+
+**Pros:** Complete picture, no missing context
+**Cons:** High token usage, may be overwhelming
+**Use when:** Complex tasks, architecture decisions
+
+## Maintenance
+
+### Weekly Maintenance
+
+```bash
+# 1. Analyze patterns
+python .claude/skills/oracle/scripts/analyze_patterns.py
+
+# 2. Generate automation scripts
+python .claude/skills/oracle/scripts/analyze_patterns.py --generate-scripts
+
+# 3. Update claude.md
+python .claude/skills/oracle/scripts/generate_context.py --output claude.md --update
+
+# 4. Review knowledge base
+python .claude/skills/oracle/scripts/query_knowledge.py --summary
+```
+
+### Monthly Maintenance
+
+1. Review corrections - are patterns emerging?
+2. Update knowledge priorities
+3. Archive old sessions (optional)
+4. Review automation scripts - are they being used?
+5. Clean up duplicate knowledge entries
+
+### Knowledge Curation
+
+Periodically review and curate:
+
+```bash
+# Find rarely used knowledge
+python .claude/skills/oracle/scripts/query_knowledge.py --sort used
+
+# Find old corrections (may be outdated)
+python .claude/skills/oracle/scripts/query_knowledge.py --category corrections --sort recent
+```
+
+## Troubleshooting
+
+### Oracle Not Loading
+
+**Problem:** Context not appearing at session start.
+
+**Solutions:**
+1. Check `.claude/hooks/session-start.sh` exists and is executable
+2. Verify Oracle is initialized: `ls -la .oracle/`
+3. Test manually: `python .claude/skills/oracle/scripts/load_context.py --verbose`
+
+### Context Too Large
+
+**Problem:** Too much context being injected.
+
+**Solutions:**
+1. Use tier 1 context: `--tier 1`
+2. Increase priorities of only critical items
+3. Use task-specific context instead of session-start
+4. Review and archive old knowledge
+
+### Knowledge Not Relevant
+
+**Problem:** Loaded knowledge doesn't apply to current task.
+
+**Solutions:**
+1. Use task-specific context generation
+2. Improve tags on knowledge entries
+3. Use more specific queries
+4. Update priorities to better reflect importance
+
+### Scripts Not Generating
+
+**Problem:** Pattern analysis doesn't find automation candidates.
+
+**Solutions:**
+1. Lower threshold: `--threshold 2`
+2. Record more sessions
+3. Be consistent in activity descriptions
+4. Manually identify patterns and add as automation opportunities
+
+## Best Practices
+
+### 1. Record Sessions Consistently
+
+Don't wait until end of day - record immediately after completing work while details are fresh.
+
+### 2. Be Specific in Corrections
+
+Instead of: "That's wrong"
+Use: "Don't use innerHTML for user input -> use textContent to prevent XSS"
+
+### 3. Tag Thoughtfully
+
+Use consistent, meaningful tags. Review existing tags before creating new ones.
+
+### 4. Prioritize Ruthlessly
+
+Not everything is critical. Save high/critical priorities for things that truly matter.
+
+### 5. Review Regularly
+
+Knowledge bases become stale. Review and update monthly.
+
+### 6. Use Automation
+
+If pattern analysis suggests automation, implement it. Oracle works best when reducing repetitive LLM usage.
+
+### 7. Share Knowledge
+
+In team settings, commit Oracle knowledge to git (exclude sensitive session logs via .gitignore).
+
+---
+
+**Integration Version**: 1.0
+**Last Updated**: 2025-11-19

skills/oracle/References/knowledge-schema.md

@@ -0,0 +1,368 @@
+# Oracle Knowledge Schema
+
+This document defines the structure and schema for Oracle knowledge entries.
+
+## Knowledge Entry Structure
+
+### JSON Format
+
+```json
+{
+  "id": "unique-identifier",
+  "category": "pattern|preference|gotcha|solution|correction",
+  "priority": "critical|high|medium|low",
+  "title": "Brief descriptive title (max 100 chars)",
+  "content": "Detailed information about this knowledge",
+  "context": "When this knowledge applies",
+  "examples": [
+    "Example 1",
+    "Example 2"
+  ],
+  "learned_from": "session-id or source",
+  "created": "2025-11-19T10:30:00Z",
+  "last_used": "2025-11-19T10:30:00Z",
+  "use_count": 0,
+  "tags": ["tag1", "tag2", "tag3"]
+}
+```
+
+### Field Descriptions
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `id` | string (UUID) | Yes | Unique identifier for this entry |
+| `category` | enum | Yes | Category: pattern, preference, gotcha, solution, or correction |
+| `priority` | enum | Yes | Priority level: critical, high, medium, or low |
+| `title` | string | Yes | Brief, descriptive title (max 100 characters) |
+| `content` | string | Yes | Detailed information, explanation, or description |
+| `context` | string | No | When/where this knowledge applies |
+| `examples` | array[string] | No | Concrete examples demonstrating the knowledge |
+| `learned_from` | string | No | Session ID or source where this was learned |
+| `created` | ISO 8601 | Yes | When this entry was created |
+| `last_used` | ISO 8601 | No | When this knowledge was last recalled/used |
+| `use_count` | integer | No | Number of times this knowledge has been used |
+| `tags` | array[string] | No | Tags for categorization and search |
+
+## Categories Explained
+
+### Pattern
+
+**Purpose**: Capture code patterns, architectural decisions, and conventions
+
+**When to use**:
+- Established coding patterns in the project
+- Architecture decisions
+- Design patterns being used
+- Coding conventions and style
+
+**Example**:
+```json
+{
+  "category": "pattern",
+  "title": "Use factory pattern for database connections",
+  "content": "All database connections should be created through DatabaseFactory.create() which handles connection pooling, configuration, and error handling.",
+  "context": "When creating new database connections",
+  "examples": [
+    "const db = DatabaseFactory.create('postgres')",
+    "const cache = DatabaseFactory.create('redis')"
+  ],
+  "priority": "high",
+  "tags": ["database", "factory-pattern", "architecture"]
+}
+```
+
+### Preference
+
+**Purpose**: Capture user/team preferences and stylistic choices
+
+**When to use**:
+- Team coding style preferences
+- Tool choices
+- Workflow preferences
+- Naming conventions
+
+**Example**:
+```json
+{
+  "category": "preference",
+  "title": "Prefer functional programming over OOP",
+  "content": "Team prefers functional programming style with pure functions, immutability, and composition over object-oriented approaches.",
+  "context": "When designing new features or refactoring code",
+  "examples": [
+    "Use map/filter/reduce instead of for loops",
+    "Use pure functions without side effects"
+  ],
+  "priority": "medium",
+  "tags": ["coding-style", "functional-programming"]
+}
+```
+
+### Gotcha
+
+**Purpose**: Capture known issues, pitfalls, edge cases, and things to avoid
+
+**When to use**:
+- Known bugs or quirks
+- Common mistakes
+- Platform-specific issues
+- Performance pitfalls
+- Security concerns
+
+**Example**:
+```json
+{
+  "category": "gotcha",
+  "title": "Database connection pool must be explicitly closed",
+  "content": "The database connection pool doesn't close automatically. Failing to call pool.close() in shutdown handlers causes memory leaks and prevents clean exits.",
+  "context": "When setting up application lifecycle hooks",
+  "examples": [
+    "process.on('SIGTERM', () => pool.close())",
+    "app.on('shutdown', async () => await pool.close())"
+  ],
+  "priority": "critical",
+  "tags": ["database", "memory-leak", "lifecycle"]
+}
+```
+
+### Solution
+
+**Purpose**: Capture proven solutions to specific problems
+
+**When to use**:
+- Solutions to problems encountered
+- Best practices discovered
+- Successful implementations
+- Recommended approaches
+
+**Example**:
+```json
+{
+  "category": "solution",
+  "title": "Use cursor-based pagination for large datasets",
+  "content": "For datasets with millions of records, use cursor-based pagination instead of offset-based to avoid performance degradation and inconsistencies.",
+  "context": "When implementing pagination for large tables",
+  "examples": [
+    "?cursor=xyz&limit=100 instead of ?page=1&limit=100",
+    "SELECT * FROM users WHERE id > $cursor LIMIT $limit"
+  ],
+  "priority": "high",
+  "tags": ["pagination", "performance", "database"]
+}
+```
+
+### Correction
+
+**Purpose**: Capture mistakes Claude made and the correct approach
+
+**When to use**:
+- User corrected Claude's approach
+- Wrong assumptions were made
+- Incorrect implementations
+- Learning from mistakes
+
+**Example**:
+```json
+{
+  "category": "correction",
+  "title": "Don't use innerHTML for user content",
+  "content": "❌ Wrong: element.innerHTML = userInput\n✓ Right: element.textContent = userInput\n\nReason: innerHTML allows XSS attacks when used with user input.",
+  "context": "When displaying user-generated content",
+  "examples": [
+    "// Correct: element.textContent = comment.body",
+    "// Correct: element.appendChild(document.createTextNode(input))"
+  ],
+  "priority": "critical",
+  "tags": ["security", "xss", "dom"]
+}
+```
+
+## Priority Levels
+
+### Critical
+
+- Security vulnerabilities
+- Data loss risks
+- Production-breaking issues
+- Must be remembered and applied
+
+**Examples**:
+- Security best practices
+- Data integrity rules
+- Critical gotchas
+
+### High
+
+- Important patterns
+- Frequent corrections
+- Performance considerations
+- Should be remembered and applied
+
+**Examples**:
+- Core architectural patterns
+- Common gotchas
+- Team preferences
+
+### Medium
+
+- Helpful solutions
+- General preferences
+- Nice-to-know patterns
+- Could be remembered
+
+**Examples**:
+- Helper patterns
+- Coding style details
+- Useful solutions
+
+### Low
+
+- Optional information
+- Rare cases
+- Historical context
+- Reference only
+
+**Examples**:
+- Deprecated approaches
+- Rarely-used patterns
+- Historical decisions
+
+## Tags Best Practices
+
+### Effective Tags
+
+**Technology/Framework**:
+- `react`, `typescript`, `python`, `postgres`, `redis`
+
+**Domain**:
+- `authentication`, `api`, `database`, `testing`, `deployment`
+
+**Type**:
+- `security`, `performance`, `bug`, `refactoring`
+
+**Component**:
+- `frontend`, `backend`, `database`, `infrastructure`
+
+### Tag Naming Conventions
+
+- Use lowercase
+- Use hyphens for multi-word tags (`cursor-based-pagination`)
+- Be specific but not too granular
+- Reuse existing tags when possible
+- Limit to 3-5 tags per entry
+
+## Index Schema
+
+The `index.json` file maintains metadata for quick access:
+
+```json
+{
+  "created": "2025-11-19T10:00:00Z",
+  "last_updated": "2025-11-19T15:30:00Z",
+  "total_entries": 42,
+  "categories": {
+    "patterns": 10,
+    "preferences": 5,
+    "gotchas": 8,
+    "solutions": 15,
+    "corrections": 4
+  },
+  "sessions": [
+    "2025-11-19_session_001",
+    "2025-11-19_session_002"
+  ],
+  "version": "1.0"
+}
+```
+
+## Migration and Versioning
+
+If the schema changes in future versions:
+
+1. Update `version` field in index
+2. Provide migration scripts
+3. Maintain backward compatibility where possible
+4. Document breaking changes
+
+## Validation
+
+When adding entries programmatically, validate:
+
+1. **Required fields**: id, category, priority, title, content, created
+2. **Valid enums**: category and priority must be from allowed values
+3. **Type checking**: Ensure correct data types
+4. **UUID format**: id should be valid UUID
+5. **ISO 8601 dates**: created and last_used should be valid ISO 8601
+
+## Best Practices
+
+### Writing Good Titles
+
+✅ Good:
+- "Use bcrypt for password hashing"
+- "Database connections must use connection pool"
+- "API responses include timestamp and request_id"
+
+❌ Bad:
+- "Passwords" (too vague)
+- "This is how we handle database connections and everything related to databases" (too long)
+- "Thing about APIs" (not descriptive)
+
+### Writing Good Content
+
+✅ Good:
+- Clear, concise explanation
+- Includes the "why" not just "what"
+- Provides enough detail to apply the knowledge
+
+❌ Bad:
+- Just restating the title
+- Too verbose or includes irrelevant details
+- Missing the rationale
+
+### Choosing Priority
+
+Ask yourself:
+- **Critical**: Would ignoring this cause security issues, data loss, or production failures?
+- **High**: Would ignoring this cause bugs, poor performance, or violate team standards?
+- **Medium**: Would ignoring this make code harder to maintain or less optimal?
+- **Low**: Is this just nice to know or historical context?
+
+### When to Create New Entry vs Update Existing
+
+**Create new entry** when:
+- The knowledge is distinct and separate
+- Different context or use case
+- Different priority level
+
+**Update existing entry** when:
+- Adding examples to existing knowledge
+- Clarifying existing content
+- Updating outdated information
+
+## Example: Complete Entry
+
+```json
+{
+  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
+  "category": "gotcha",
+  "priority": "critical",
+  "title": "Redis client must handle connection failures",
+  "content": "Redis connections can fail intermittently in production. The client must implement exponential backoff retry logic and circuit breaker pattern to handle connection failures gracefully. Without this, the application will crash on Redis unavailability.",
+  "context": "When initializing Redis client or any external service connection",
+  "examples": [
+    "redisClient.on('error', handleError)",
+    "Use ioredis with retry_strategy option",
+    "Implement circuit breaker with state: closed, open, half-open"
+  ],
+  "learned_from": "2025-11-19_session_003",
+  "created": "2025-11-19T14:30:00Z",
+  "last_used": "2025-11-19T15:45:00Z",
+  "use_count": 3,
+  "tags": ["redis", "error-handling", "resilience", "circuit-breaker"]
+}
+```
+
+---
+
+**Schema Version**: 1.0
+**Last Updated**: 2025-11-19

skills/oracle/References/pattern-library.md

@@ -0,0 +1,443 @@
+# Oracle Pattern Library
+
+Common patterns, solutions, and best practices for the Oracle knowledge management system.
+
+## Knowledge Entry Patterns
+
+### Pattern: Security Critical
+
+**When:** Recording security-related knowledge
+
+**Structure:**
+```json
+{
+  "category": "gotcha" or "correction",
+  "priority": "critical",
+  "title": "Always [security practice]",
+  "content": "Security vulnerability description and correct approach",
+  "context": "When handling [user input/authentication/etc]",
+  "tags": ["security", "xss|sql-injection|csrf|etc"]
+}
+```
+
+**Example:**
+- Input validation
+- Authentication bypasses
+- Injection vulnerabilities
+- Data exposure
+
+### Pattern: Performance Optimization
+
+**When:** Recording performance-related learnings
+
+**Structure:**
+```json
+{
+  "category": "solution",
+  "priority": "high",
+  "title": "Use [optimized approach] for [use case]",
+  "content": "Performance problem and solution with metrics",
+  "examples": ["Before/after code"],
+  "tags": ["performance", "optimization"]
+}
+```
+
+**Example:**
+- Caching strategies
+- Query optimization
+- Algorithm improvements
+
+### Pattern: Common Mistake
+
+**When:** User corrects a repeated mistake
+
+**Structure:**
+```json
+{
+  "category": "correction",
+  "priority": "high",
+  "title": "Don't [wrong approach]",
+  "content": "❌ Wrong: [what not to do]\\n✓ Right: [correct approach]\\nReason: [why]",
+  "context": "When [situation]",
+  "tags": ["common-mistake"]
+}
+```
+
+**Example:**
+- API misuse
+- Framework gotchas
+- Language quirks
+
+## Session Recording Patterns
+
+### Pattern: Bug Fix Session
+
+**When:** Session focused on fixing a bug
+
+**Template:**
+```markdown
+## Summary
+Fixed [bug description]
+
+## Activities
+- Identified root cause in [location]
+- Implemented fix in [location]
+- Added tests to prevent regression
+
+## Changes Made
+- File: [path]
+  - Change: [what changed]
+  - Reason: Fix for [bug]
+
+## Learnings
+- 🟡 [HIGH] [Root cause and how to prevent]
+
+## Corrections (if applicable)
+- What was wrong: [incorrect assumption/approach]
+- What's right: [correct understanding/approach]
+```
+
+### Pattern: Feature Implementation
+
+**When:** Adding new functionality
+
+**Template:**
+```markdown
+## Summary
+Implemented [feature name]
+
+## Activities
+- Designed [component/system]
+- Implemented [components]
+- Added tests
+- Updated documentation
+
+## Decisions
+- Decision: [technical decision made]
+  - Rationale: [why this approach]
+  - Alternatives: [other options considered]
+
+## Learnings
+- [Patterns established]
+- [Solutions used]
+```
+
+### Pattern: Refactoring Session
+
+**When:** Improving existing code
+
+**Template:**
+```markdown
+## Summary
+Refactored [what] to [improvement]
+
+## Activities
+- Analyzed current implementation
+- Refactored [components]
+- Verified no breaking changes
+
+## Changes Made
+- [List of files and changes]
+
+## Learnings
+- [Patterns applied]
+- [Anti-patterns removed]
+```
+
+## Query Patterns
+
+### Pattern: Pre-Task Context
+
+**When:** Starting a new task
+
+**Command:**
+```bash
+python .claude/skills/oracle/scripts/query_knowledge.py --task "implement [feature]" --priority high
+```
+
+**What it does:**
+- Surfaces relevant patterns
+- Shows related solutions
+- Highlights potential gotchas
+
+### Pattern: Post-Correction
+
+**When:** After being corrected
+
+**Command:**
+```bash
+python .claude/skills/oracle/scripts/record_session.py --corrections "wrong->right"
+python .claude/skills/oracle/scripts/query_knowledge.py --category corrections --recent 10
+```
+
+**What it does:**
+- Records the correction
+- Shows recent corrections to identify patterns
+
+### Pattern: Weekly Review
+
+**When:** Regular maintenance
+
+**Commands:**
+```bash
+# See what we've learned
+python .claude/skills/oracle/scripts/query_knowledge.py --recent 20
+
+# Find automation opportunities
+python .claude/skills/oracle/scripts/analyze_patterns.py
+
+# Update documentation
+python .claude/skills/oracle/scripts/generate_context.py --output claude.md --update
+```
+
+## Integration Patterns
+
+### Pattern: Continuous Learning
+
+**Setup:**
+1. `claude.md` with Oracle section
+2. Session start hook loads context
+3. After each session: record learnings
+4. Weekly: analyze patterns
+
+**Benefit:** Continuous improvement, knowledge compounds
+
+### Pattern: Team Knowledge Base
+
+**Setup:**
+1. Oracle in git repository
+2. `.gitignore` excludes sensitive session logs
+3. `claude.md` committed and shared
+4. Team members contribute learnings
+
+**Benefit:** Shared institutional knowledge
+
+### Pattern: Documentation Sync
+
+**Setup:**
+1. Record sessions with learnings
+2. Oracle context in `claude.md`
+3. Use learnings to update docs
+4. Keep docs and knowledge in sync
+
+**Benefit:** Documentation stays current
+
+## Automation Patterns
+
+### Pattern: Repeated Command
+
+**Detection:**
+Activity appears 3+ times: "Run tests"
+
+**Action:**
+```bash
+# Oracle generates
+./auto_run_tests.sh
+
+# Which contains
+#!/bin/bash
+npm test
+# or pytest
+# or cargo test
+```
+
+**Usage:** Use script instead of asking Claude
+
+### Pattern: Multi-Step Process
+
+**Detection:**
+Same sequence appears repeatedly:
+1. "Build project"
+2. "Run linter"
+3. "Run tests"
+
+**Action:**
+```bash
+# Oracle generates
+./auto_pre_commit.sh
+
+# Which contains
+#!/bin/bash
+npm run build && npm run lint && npm test
+```
+
+### Pattern: Context Generation
+
+**Detection:**
+Repeatedly asking about same topic
+
+**Action:**
+Add to claude.md auto-inject:
+```markdown
+## Authentication Context
+
+[Relevant knowledge auto-injected]
+```
+
+## Anti-Patterns (What NOT to Do)
+
+### Anti-Pattern: Recording Everything
+
+❌ **Don't:** Record every tiny action
+✓ **Do:** Record meaningful learnings and corrections
+
+**Why:** Bloats knowledge base, harder to find relevant info
+
+### Anti-Pattern: Vague Entries
+
+❌ **Don't:** "Something about databases"
+✓ **Do:** "Use connection pooling for database connections to prevent connection exhaustion"
+
+**Why:** Vague entries aren't useful for recall
+
+### Anti-Pattern: Duplicate Knowledge
+
+❌ **Don't:** Create new entry for same knowledge
+✓ **Do:** Update existing entry or add examples
+
+**Why:** Duplicates cause confusion and bloat
+
+### Anti-Pattern: Wrong Priorities
+
+❌ **Don't:** Mark everything as critical
+✓ **Do:** Save critical for security, data loss, breaking issues
+
+**Why:** Dilutes importance, everything seems urgent
+
+### Anti-Pattern: No Tags
+
+❌ **Don't:** Skip tags thinking title is enough
+✓ **Do:** Add 2-4 relevant tags
+
+**Why:** Tags enable better search and categorization
+
+### Anti-Pattern: Never Reviewing
+
+❌ **Don't:** Set and forget
+✓ **Do:** Review monthly, update priorities, archive old entries
+
+**Why:** Stale knowledge becomes misleading
+
+### Anti-Pattern: Ignoring Automations
+
+❌ **Don't:** Keep asking LLM for same repeated task
+✓ **Do:** Use or create automation scripts
+
+**Why:** Wastes tokens and time on deterministic tasks
+
+## Common Use Cases
+
+### Use Case 1: Onboarding New Developers
+
+**Situation:** New team member joining project
+
+**Solution:**
+```bash
+# Generate comprehensive onboarding context
+python .claude/skills/oracle/scripts/generate_context.py --tier 2 > onboarding.md
+
+# Include:
+# - Critical gotchas
+# - Key patterns
+# - Team preferences
+# - Common solutions
+```
+
+### Use Case 2: Context Switching
+
+**Situation:** Coming back to project after time away
+
+**Solution:**
+```bash
+# Load session start context
+python .claude/skills/oracle/scripts/load_context.py
+
+# Review recent sessions
+python .claude/skills/oracle/scripts/query_knowledge.py --recent 10
+
+# Review project timeline
+cat .oracle/timeline/project_timeline.md | tail -50
+```
+
+### Use Case 3: Bug Investigation
+
+**Situation:** Investigating a bug
+
+**Solution:**
+```bash
+# Search for related issues
+python .claude/skills/oracle/scripts/query_knowledge.py "bug-related-keywords"
+
+# Check if similar bug was fixed before
+python .claude/skills/oracle/scripts/query_knowledge.py --category gotchas --tags bug
+
+# After fix, record to prevent recurrence
+python .claude/skills/oracle/scripts/record_session.py --interactive
+```
+
+### Use Case 4: Architecture Decision
+
+**Situation:** Making important architectural choice
+
+**Solution:**
+```bash
+# Review existing patterns
+python .claude/skills/oracle/scripts/query_knowledge.py --category patterns
+
+# Review past decisions
+grep "Decision:" .oracle/sessions/*.md
+
+# After deciding, record rationale
+python .claude/skills/oracle/scripts/record_session.py \
+  --summary "Decided to use [approach]" \
+  --learnings "Use [approach] because [rationale]"
+```
+
+## Success Metrics
+
+Track these to measure Oracle effectiveness:
+
+### Metric 1: Correction Reduction
+
+**Measure:** Count corrections per week
+
+**Target:** Declining trend (learning from mistakes)
+
+**How:**
+```bash
+grep -c "## Corrections" .oracle/sessions/*.md
+```
+
+### Metric 2: Knowledge Reuse
+
+**Measure:** use_count in knowledge entries
+
+**Target:** Increasing use counts on valuable entries
+
+**How:**
+```bash
+python .claude/skills/oracle/scripts/query_knowledge.py --sort used
+```
+
+### Metric 3: Automation Adoption
+
+**Measure:** Generated scripts being used
+
+**Target:** High usage of automation scripts
+
+**How:**
+Check git history for manual vs scripted operations
+
+### Metric 4: Context Relevance
+
+**Measure:** How often injected context is actually useful
+
+**Target:** High relevance rate
+
+**How:**
+Subjective assessment during sessions
+
+---
+
+**Pattern Library Version**: 1.0
+**Last Updated**: 2025-11-19

skills/oracle/References/session-log-template.md

@@ -0,0 +1,72 @@
+# Session: YYYY-MM-DD HH:MM
+
+**Session ID**: `session-id-here`
+
+## Summary
+
+[Brief 1-2 sentence summary of what was accomplished this session]
+
+## Activities
+
+- [Activity 1]
+- [Activity 2]
+- [Activity 3]
+
+## Changes Made
+
+- **File**: `path/to/file.ts`
+  - Change: [Description of what changed]
+  - Reason: [Why this change was made]
+
+- **File**: `path/to/another/file.py`
+  - Change: [Description of what changed]
+  - Reason: [Why this change was made]
+
+## Decisions
+
+- **Decision**: [What was decided]
+  - Rationale: [Why this decision was made]
+  - Alternatives considered: [What other options were considered]
+  - Impact: [What this affects]
+
+## Learnings
+
+- 🔴 **[CRITICAL]** [Critical learning - security, data loss, etc.]
+  - Context: [When this applies]
+  - Applied to: [What this affects]
+
+- 🟡 **[HIGH]** [Important learning - patterns, gotchas]
+  - Context: [When this applies]
+
+- 🔵 **[MEDIUM]** [Helpful learning - solutions, preferences]
+
+## Corrections
+
+- **Correction**: [What was wrong → what's right]
+  - ❌ Wrong: [What Claude did incorrectly]
+  - ✓ Right: [The correct approach]
+  - Context: [When this applies]
+  - Prevention: [How to avoid in future]
+
+## Questions Asked
+
+- **Q**: [Question that was asked]
+  - **A**: [Answer provided]
+  - Relevant knowledge: [Links to related knowledge entries]
+
+## Automation Opportunities
+
+- **Task**: [Repeated task that could be automated]
+  - Frequency: [How often this occurs]
+  - Candidate for: [Script/template/pattern]
+  - Complexity: [Simple/Medium/Complex]
+
+## Next Session Preparation
+
+- [Thing to remember for next time]
+- [Context to load at next session start]
+- [Follow-up task]
+
+---
+
+*Recorded: YYYY-MM-DDTHH:MM:SSZ*