ask-oracle

# Ask Oracle Skill

Leverage the Oracle CLI to tap into GPT-5 Pro / GPT-5.1 for hard problems that benefit from extended reasoning and large code context.

## When to Use

Invoke this skill when:
- Problem requires deep reasoning beyond single-response analysis
- Debugging complex issues across large codebases (100k+ lines)
- Architectural decisions need careful evaluation with full context
- Performance optimization requires comprehensive code analysis
- Security reviews need thorough codebase inspection
- Standard Claude analysis feels insufficient
- Problem statement includes "hard", "complex", "architectural", "across the codebase"

## Core Capabilities

The Oracle CLI (`bunx @steipete/oracle`) provides:
- **GPT-5 Pro** (default): Advanced reasoning for difficult problems
- **GPT-5.1**: Experimental model with different reasoning approach
- **File context**: Attach entire directories/files (up to ~196k tokens)
- **Sessions**: Long-running background sessions with resume capability
- **Token reporting**: Inspect file token costs before calling API

## Workflow

### Step 1: Assess the Problem

Determine if oracle is needed:
- Is the problem genuinely hard/complex?
- Does it benefit from seeing more code context?
- Would standard Claude response be insufficient?

If yes, proceed. If it's a simple question, just answer directly.

### Step 2: Gather Relevant Context

Identify files/directories to attach using `--file`:
- Architecture files (README, package.json, main entry points)
- Relevant source directories (`src/`, `lib/`, etc.)
- Configuration files (tsconfig, build config, etc.)
- Tests if they illuminate the problem
- Error logs or reproduction scripts

Exclude:
- Node modules (`node_modules/`)
- Build artifacts (`dist/`, `build/`)
- Large vendored code
- Binary files

### Step 3: Choose Model and Preview

**For most hard problems**, use default GPT-5 Pro:
```bash
bunx @steipete/oracle --prompt "Your question here" --file src/ docs/ --preview
```

**For experimental approach**, try GPT-5.1:
```bash
bunx @steipete/oracle --prompt "Your question here" --file src/ docs/ --model gpt-5.1 --preview
```

**Always preview first** to check token usage:
```bash
bunx @steipete/oracle --prompt "Question" --file src/ --files-report --preview
```

### Step 4: Review Token Report

When using `--files-report`, output shows token costs per file:
```
Files Report:
  src/components/form.tsx: 3,245 tokens
  src/utils/helpers.ts: 1,023 tokens
  src/api/client.ts: 2,156 tokens
  Total: 6,424 tokens (under ~196k budget)
```

If total exceeds budget:
- Remove less relevant files
- Focus on key directories only
- Exclude verbose files (logs, generated code)
- Ask a more specific question to reduce needed context

### Step 5: Execute Query

Once satisfied with preview, run without `--preview` to actually call the model:
```bash
bunx @steipete/oracle --prompt "Your question here" --file src/ docs/ --slug "my-problem"
```

Oracle runs as **background session** - terminal can close without losing work.

### Step 6: Monitor or Resume Session

**To attach to running session:**
```bash
bunx @steipete/oracle session <session-id>
```

**To list recent sessions (last 24h):**
```bash
bunx @steipete/oracle status
```

**To specify custom session slug** (easier to remember):
```bash
bunx @steipete/oracle --slug "auth-flow-design" --prompt "..." --file src/
```

Later, attach via slug:
```bash
bunx @steipete/oracle session auth-flow-design
```

## Key Options

| Option | Purpose | Example |
|--------|---------|---------|
| `--prompt` | The question to ask | `--prompt "Why does this auth flow fail?"` |
| `--file` | Attach files/dirs (repeatable) | `--file src/ docs/ --file error.log` |
| `--slug` | Human-memorable session name | `--slug "perf-optimization-review"` |
| `--model` | Which model to use | `--model gpt-5.1` (default: gpt-5-pro) |
| `--engine` | api or browser | `--engine api` (default: auto-detect) |
| `--files-report` | Show token per file | Helps optimize context |
| `--preview` | Validate without calling API | Test before spending tokens |
| `--dry-run` | Show token estimates only | Safer than preview |
| `--heartbeat` | Progress updates (seconds) | `--heartbeat 30` (default) |

## Common Patterns

### Hard Debugging Question
```bash
bunx @steipete/oracle \
  --prompt "Why does this auth flow fail on mobile? Trace through the code flow." \
  --file src/auth/ src/api/ docs/AUTH.md \
  --slug "mobile-auth-debug" \
  --files-report \
  --preview
```

### Architectural Review
```bash
bunx @steipete/oracle \
  --prompt "Review the state management architecture. What are risks and improvements?" \
  --file src/store/ src/components/ README.md \
  --slug "state-arch-review"
```

### Performance Analysis
```bash
bunx @steipete/oracle \
  --prompt "Where are the performance bottlenecks in this renderer?" \
  --file src/renderer/ performance-logs.txt \
  --slug "renderer-perf" \
  --files-report
```

### Security Review
```bash
bunx @steipete/oracle \
  --prompt "Identify security concerns in the authentication and API layers." \
  --file src/auth/ src/api/ src/middleware/ \
  --slug "security-audit"
```

## Best Practices

1. **Always preview first**: Use `--preview` or `--files-report` to inspect tokens before committing budget
2. **Use memorable slugs**: Makes it easier to resume and reference later
3. **Ask focused questions**: More specific = better reasoning. Avoid "review everything"
4. **Provide context in prompt**: "We're building X in domain Y, and problem is Z"
5. **Attach key architecture docs**: READMEs, design docs help oracle understand intent
6. **Keep files under 1MB**: Automatic rejection, so plan accordingly
7. **Use browser engine for API-less runs**: Falls back to browser if no OPENAI_API_KEY set
8. **Check token budget**: ~196k tokens max per request (files + prompt)

## Examples

### Example 1: Complex Bug Investigation
```bash
bunx @steipete/oracle \
  --prompt "This form submission intermittently fails with 'network timeout'. Walk through the request/response cycle, check timeout configs, and trace where it might stall." \
  --file src/components/Form.tsx src/api/client.ts src/hooks/useSubmit.ts \
  --files-report \
  --preview
```

### Example 2: Design Review with Alternatives
```bash
bunx @steipete/oracle \
  --prompt "We're using redux for state management in a 50k LOC codebase. Is this still optimal? What are 2-3 alternatives worth considering?" \
  --file src/store/ docs/ARCHITECTURE.md package.json \
  --slug "state-mgmt-design"
```

### Example 3: Resume Previous Session
```bash
# Earlier you ran:
bunx @steipete/oracle --prompt "..." --slug "my-problem"

# Now attach to it:
bunx @steipete/oracle session my-problem
```

## Edge Cases & Troubleshooting

**Files too large (>1MB):**
- Exclude vendored code, logs, or split context
- Focus on key files only

**Token budget exceeded (~196k):**
- Show `--files-report` to see cost per file
- Reduce number of files or directories
- Ask more specific question to require less context

**Session doesn't exist:**
- Check spelling of slug/ID
- Run `bunx @steipete/oracle status` to list recent sessions
- Create new session if needed

**OPENAI_API_KEY not set:**
- Oracle falls back to browser engine
- Use `--engine browser` explicitly if preferred
- Set API key to use API engine for background sessions

**Preview shows too many tokens:**
- Exclude directories with large generated files
- Keep only most relevant source files
- Split into multiple focused queries

## Implementation Notes

- Oracle CLI is installed via `bunx @steipete/oracle` (no local install needed)
- Sessions run in background; terminal close doesn't stop them
- Responses stream via heartbeat (default 30s intervals)
- Use `--slug` for easier session management in team workflows
- Token budget is per-request (~196k combined), not per session

## When NOT to Use Oracle

- Simple questions answerable in seconds
- Trivial code changes or minor bugs
- Context < 10k tokens
- Answers need immediate turnaround (background sessions take time)
- No code context needed (use standard Claude instead)