name: oracle-integration
description: Provides Oracle CLI integration for GPT-5.2 Pro review loops. Use when running external model reviews, multi-model consensus, or structured issue extraction from Oracle outputs.
triggers:
- oracle review
- gpt-5 review
- external review
- multi-model
- second opinion
- oracle lens
- browser oracle

Oracle Integration Skill

Integrate GPT-5.2 Pro reviews into your development workflow via the Oracle CLI.

Overview

Oracle bundles your artifacts and runs them through GPT-5.2 Pro (browser mode) with specialized review lenses. This skill guides the integration process.

Key Principles

1. Browser mode only: Oracle runs use your ChatGPT session, not API (cheaper, fully automated)
2. 8 specialized lenses: product, ux, architecture, security, performance, tests, simplicity, ops
3. Structured output: All reviews produce normalized issues.json with consistent schema
4. Fully autonomous: Run Oracle scripts directly - DO NOT ask user to run commands

⚠️ MANDATORY FIRST STEP — CHECK EXISTING STATE ⚠️

BEFORE running any Oracle script, ALWAYS check what already exists:

# 1. What Oracle output exists?
ls -la artifacts/06-oracle/<kind>/ 2>/dev/null || echo "No Oracle output yet"

# 2. Convergence state?
cat artifacts/06-oracle/<kind>/convergence-history.json 2>/dev/null || echo "No history"

# 3. Latest feedback files?
ls -t artifacts/06-oracle/<kind>/*.md 2>/dev/null | head -3

Decision tree:

How to tell if feedback is unapplied:
- Oracle files newer than artifact
- Issues in Oracle output still visible in artifact

STEP 1: Run Oracle (only if needed per above)

DO NOT ask the user to run commands. Execute directly:

# Run this directly - DO NOT print and ask user to run
./scripts/oracle_converge.sh ux artifacts/02-ux.md artifacts/01-prd.md

This takes 60-90 minutes. The script:
1. Calls GPT-5.2 Pro via browser automation
2. GPT-5.2 Pro has extended thinking (30-60 min silence is normal)
3. Returns structured feedback
4. Loops until convergence (0 blockers, ≤2 majors)

Oracle CLI Reference

Full Lens Pack

Run all 8 lenses for a phase:

./scripts/oracle_lens_pack.sh <kind> <files...>

Single Lens

Run one specific lens:

./scripts/oracle_single_lens.sh <kind> <lens> <files...>

Lenses: product, ux, architecture, security, performance, tests, simplicity, ops

Fallback (Manual Paste)

If browser automation fails:

npx -y @steipete/oracle --render --copy-markdown \
  --engine browser \
  --browser-manual-login \
  --browser-no-cookie-sync \
  --model gpt-5.2-pro \
  --prompt "$(cat prompts/<kind>/<lens>.txt)" \
  --file "<files...>"

Then paste into ChatGPT (GPT-5.2 Pro) and save response to:
artifacts/06-oracle/<kind>/<timestamp>_<lens>.md

Issue Schema

All issues follow this structure:

{
  "id": "abc123",
  "severity": "blocker|major|minor|nit",
  "category": "product|ux|arch|security|perf|tests|simplicity|ops",
  "title": "Short description",
  "evidence": "Quote or reference from artifact",
  "recommendation": "Concrete change to make",
  "acceptanceTest": "How to verify the fix",
  "files": ["optional/affected/paths.ts"]
}

When to Use Oracle

Integration with Compound Engineering

Oracle complements Compound Engineering's Claude-native review:

┌─── Compound Engineering ───┐   ┌─── Oracle Extension ───┐
│ /workflows:review          │   │ /oracle code           │
│ 13 Claude agents parallel  │ + │ GPT-5.2 Pro external   │
│ (security-sentinel, etc.)  │   │ (fresh perspective)    │
└────────────────────────────┘   └────────────────────────┘

Troubleshooting

Browser automation fails

1. Keep Chromium window OPEN during Oracle runs
2. Use --browser-manual-login (now default in Oracle Swarm)
3. Log into ChatGPT in the Chromium window that opens
4. Close other ChatGPT tabs

Setup: Persistent Chromium Profile (Recommended)

Create ~/.oracle/config.json:

{
  "browser": {
    "manualLogin": true,
    "noCookieSync": true,
    "chromePath": "/Applications/Chromium.app/Contents/MacOS/Chromium",
    "chromeProfile": null
  }
}

This:
- Uses persistent profile at ~/.oracle/browser-profile
- No cookie sync (no Keychain prompts!)
- Log in once, reuse forever

Issues not parsing

1. Check Oracle output for valid JSON in code fence
2. Run normalizer manually:
   bash node scripts/normalize_oracle_output.js <dir> <out.json>

Too many issues

1. Focus on blockers and majors first
2. Use single lens for specific concerns
3. Increase issue quality by improving artifacts