oracle

# 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: ```bash ${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`: ```bash ${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: ```bash # 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]"