oracle

# Oracle - Second Opinion Model

Invokes OpenAI's GPT-5.2 extra high reasoning model via CLI for complex analysis tasks. It excels at debugging, code review, architecture analysis, and finding better solutions.

**Prerequisite:** Codex CLI installed and authenticated (`codex login`).

**Trade-offs:** Slower and more expensive than the main agent, but significantly better at complex reasoning. Use deliberately, not for every task.

## Invocation

Use `codex exec --profile oracle` to run the reasoning model:

```bash
codex exec --profile oracle "Review @src/auth/jwt.ts for security vulnerabilities"
```

### Examples

```bash
# Security review
codex exec --profile oracle "Review @src/auth/jwt.ts for security vulnerabilities. Provide specific fixes."

# Debugging
codex exec --profile oracle "Find why memory leak in @src/DataFetcher.tsx. Component doesn't clean up on unmount."

# Architecture analysis
codex exec --profile oracle "Analyze how @src/services/payment.ts and @src/services/order.ts interact. Propose refactoring plan."

# Complex bug investigation
codex exec --profile oracle "Bug: Users see stale data after updates. Check @src/cache/invalidation.ts for race conditions."
```

## Prompting for Reasoning Models

Reasoning models work differently from completion models. Follow these guidelines:

**Keep prompts simple and direct:**

- State the goal clearly without excessive context
- Let the model explore and discover relevant information
- Avoid step-by-step instructions - the model reasons on its own

**Focus on WHAT, not HOW:**

- Bad: "First read the file, then analyze each function, then check for..."
- Good: "Review this code for security vulnerabilities"

**Use `@` syntax for file references:**

- Include relevant files directly: `@src/auth/login.ts`
- The model will read and understand the code

**Be specific about expected output:**

- "Provide specific fixes" > "Is this correct?"
- "List all race conditions" > "Are there any bugs?"

## Example Prompts

### Security Review

```text
Review @src/auth/jwt.ts for security vulnerabilities.
Provide specific fixes for any issues found.
```

### Debugging

```text
Find why the memory leak occurs in @src/components/DataFetcher.tsx.
The component fetches data but doesn't clean up on unmount.
```

### Architecture Analysis

```text
Analyze how @src/services/payment.ts and @src/services/order.ts interact.
Propose a refactoring plan that maintains backward compatibility.
```

### Complex Bug Investigation

```text
Bug: Users intermittently see stale data after updates.
Related files: @src/api/update.ts @src/cache/invalidation.ts @src/hooks/useData.ts

Identify race conditions or cache invalidation issues and provide a fix.
```

## Workflow

Think step-by-step:

1. **Gather context first**: Identify relevant files and the specific problem
2. **Formulate a focused prompt**: Include file references with `@`, state the goal directly
3. **Invoke the oracle**: Run `codex exec --profile oracle "prompt"`
4. **Continue if needed**: Use `codex exec resume SESSION_ID "follow-up"` to refine analysis
5. **Act on the analysis**: Implement recommendations from the oracle's response

## Continuing Conversations

Use `codex exec resume SESSION_ID` to continue until satisfied. The session ID is returned from the initial invocation.

```bash
# Initial analysis (returns session ID)
codex exec --profile oracle "Review @src/auth/jwt.ts for security vulnerabilities"
# Output includes: Session ID: abc123...

# Continue with follow-up questions using the session ID
codex exec resume abc123 "Also check for timing attacks in the token validation"

# Keep refining with the same session
codex exec resume abc123 "What about the refresh token rotation logic?"
```

| Argument | Description |
| -------- | ----------- |
| `SESSION_ID` | Session ID returned from the initial invocation |
| `PROMPT` | Follow-up instruction to send after resuming |

## Rules

- Use the oracle for complex problems that require deep reasoning
- Keep prompts focused - one problem per invocation
- Include file references with `@` syntax for relevant code
- Request specific, actionable output
- Chain with main agent: oracle for analysis, main agent for implementation
- Oracle is read-only; use the main agent to implement changes