oracle

Ask the oracle (GPT-5.2 with deep reasoning) strategic technical questions. Use for architecture decisions, complex debugging, security analysis, or when you need a second expert opinion. Supports background execution for long-running queries.

⭐2stars🔀1forks📁View on GitHub🕐Updated Jan 8, 2026⬇️1downloads

When & Why to Use This Skill

The Oracle skill is a high-level strategic technical advisor powered by a GPT-5.2 reasoning model, designed to provide expert guidance on complex engineering decisions. It specializes in deep-dive technical analysis, architecture evaluation, and security threat modeling, offering a safe, read-only environment to explore codebases and provide actionable, tiered recommendations without risking unintended modifications.

Use Cases

  • Architecture Decision Making: Evaluating complex trade-offs between different technology stacks, such as choosing between specialized search engines versus relational database extensions for large-scale datasets.
  • Strategic Security Analysis: Performing deep-reasoning threat modeling and vulnerability assessments on authentication flows and sensitive system components.
  • Complex Debugging & Root Cause Analysis: Investigating multi-system bottlenecks, race conditions, and performance issues that require high-level technical synthesis.
  • Codebase Evolution Strategy: Determining whether to extend custom internal frameworks or migrate to industry-standard libraries based on long-term maintenance and scalability.
  • Expert Second Opinions: Providing high-stakes code reviews and post-implementation validations for significant architectural changes to ensure alignment with best practices.
nameoracle
descriptionAsk the oracle (GPT-5.2 with deep reasoning) strategic technical questions. Use for architecture decisions, complex debugging, security analysis, or when you need a second expert opinion. Supports background execution for long-running queries.
allowed-toolsBash, TaskOutput, KillShell

Oracle - Strategic Technical Advisor

The oracle is a GPT-5.2 reasoning model configured for deep technical analysis. Use it when you need expert-level guidance on complex decisions.

Capabilities & Restrictions

Can do:

  • Read files and explore the codebase
  • Run shell commands for investigation
  • Search the web for current information
  • Provide strategic technical advice

Cannot do (by design):

  • Edit or write files (read-only sandbox)
  • Make changes to the codebase
  • Execute destructive commands

This makes oracle safe to consult without risk of unintended modifications.

When to Use Oracle

  • Architecture decisions: System design, technology choices, scaling strategies
  • Complex debugging: Multi-system issues, race conditions, performance bottlenecks
  • Security analysis: Threat modeling, vulnerability assessment, auth patterns
  • Trade-off analysis: When multiple valid approaches exist and you need to weigh them
  • Code review: Getting a second opinion on significant implementations
  • Post-implementation review: Validating decisions after the fact

How to Invoke

Script location: ${CLAUDE_PLUGIN_ROOT}/skills/oracle/scripts/oracle.sh

Foreground (quick questions, <30 seconds expected)

Use Bash tool directly:

${CLAUDE_PLUGIN_ROOT}/skills/oracle/scripts/oracle.sh "What's the best way to implement rate limiting for this API?"

Background (complex questions, longer reasoning)

For questions that require deep reasoning, run in background and poll:

  1. Start the query with run_in_background=true:

    ${CLAUDE_PLUGIN_ROOT}/skills/oracle/scripts/oracle.sh "Analyze the security implications of this authentication flow and suggest improvements"
    
  2. Continue working on other tasks while oracle thinks

  3. Poll for status using TaskOutput with block=false:

    • Check periodically if the oracle has finished
    • When status shows completed, retrieve the result
  4. Get result - for long responses, use tail to avoid context flooding:

    # Get last 100 lines of output
    tail -100 /path/to/output
    

Response Format

Oracle responses follow a tiered structure:

Essential (Always Present)

  • Bottom Line: 1-2 sentence direct answer
  • Action Plan: Numbered concrete next steps
  • Effort Estimate: Quick (<1h) | Short (1-4h) | Medium (1-2d) | Large (3d+)

Expanded (When Relevant)

  • Reasoning: Why this approach over alternatives
  • Trade-offs: What you gain vs sacrifice
  • Dependencies: Prerequisites and external factors

Edge Cases (When Applicable)

  • Escalation Triggers: When to reconsider
  • Alternatives: Backup options
  • Gotchas: Common mistakes to avoid

Example Questions

Good oracle questions are:

  • Specific and contextualized
  • About decisions rather than implementations
  • Complex enough to benefit from deep reasoning

Examples:

  • "Given our PostgreSQL + Redis stack, should we add Elasticsearch for full-text search or use pg_trgm? We have 10M records, 100 QPS expected."
  • "This codebase uses a custom event system. Should we migrate to a standard library or continue extending it?"
  • "Review this authentication flow for security issues: [paste code]"