gh-overlord-z-claudeshack/skills/oracle/References/integration-guide.md

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:

touch claude.md

2. Add Oracle context section:

# 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

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:

# 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:

mkdir -p .claude/hooks

2. Create session-start hook:

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:

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

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.

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.

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.

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

# 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:

# 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