Oracle Agent

{
  "model": "gpt-5.2",
  "variant": "high",
  "temperature": 0.1,
  "reasoningEffort": "medium",
  "textVerbosity": "high"
}

{
  "model": "claude-opus-4-6",
  "variant": "max",
  "temperature": 0.1,
  "thinking": {
    "type": "enabled",
    "budgetTokens": 32000
  }
}

{
  "model": "gemini-3.1-pro",
  "variant": "high",
  "temperature": 0.1
}

// User: "Should we use microservices for this feature?"

// Oracle response:
"Bottom line: No. A modular monolith is sufficient for your current scale.

Reasoning:
- Current traffic: 100 req/min (well within single-process capacity)
- Team size: 3 developers (microservices add coordination overhead)
- Deployment complexity: Would require Docker, K8s, service mesh
- Current pain point: None - existing monolith performing well

Recommendation: Organize code into clear module boundaries within monolith. 
Revisit when traffic exceeds 10K req/min or team grows beyond 10 developers."

## Bottom Line
2-3 sentences capturing the recommendation

## Action Plan
1. First concrete step (1-2 sentences)
2. Second step
3. ...

## Effort Estimate
Quick / Short / Medium / Large

## Why This Approach
- Key trade-off 1
- Key trade-off 2
- Rationale for recommendation

## Watch Out For
- Risk 1 and mitigation
- Risk 2 and mitigation
- Edge case considerations

## Escalation Triggers
Conditions that would justify a more complex solution:
- Trigger 1 (e.g., "Traffic exceeds 50K req/min")
- Trigger 2 (e.g., "Team grows beyond 15 developers")

## Alternative Sketch
High-level outline of advanced path (not full design)

// After implementing authentication system

task(
  subagent_type="oracle",
  run_in_background=false,
  description="Review authentication implementation",
  prompt="I just implemented JWT authentication for our API.
          
          Files changed:
          - src/services/auth/token.ts (JWT generation/validation)
          - src/middleware/auth.ts (Express middleware)
          - src/routes/auth.ts (Login/register endpoints)
          
          Please review for:
          1. Security vulnerabilities
          2. Architecture issues
          3. Performance concerns
          4. Missing error handling"
)

// Oracle response:
"## Bottom Line
Implementation is fundamentally sound but has 2 critical security gaps 
and 1 performance issue that need immediate attention.

## Critical Issues

1. **JWT secret in code** (Security - Critical)
   - Location: token.ts:12
   - Issue: Secret hardcoded as 'my-secret-key'
   - Fix: Move to environment variable, use crypto.randomBytes(32)
   - Effort: Quick (10min)

2. **No token expiration validation** (Security - High)  
   - Location: middleware/auth.ts:25
   - Issue: Expired tokens still accepted
   - Fix: Check exp claim, reject if Date.now() > exp
   - Effort: Quick (15min)

3. **Synchronous password hashing** (Performance - Medium)
   - Location: routes/auth.ts:45
   - Issue: bcrypt.hashSync blocks event loop
   - Fix: Use bcrypt.hash (async) with await
   - Effort: Quick (5min)

## Additional Recommendations

4. **Add rate limiting** (Security - Medium)
   - Routes need rate limiting to prevent brute force
   - Use express-rate-limit on /login and /register
   - Effort: Short (30min)

5. **Missing refresh token logic** (Architecture - Low)
   - Only access tokens, no refresh mechanism
   - Users must re-login every 15 minutes
   - Consider: Add refresh token endpoint
   - Effort: Medium (2-3h)

## What's Good

✓ Password hashing with bcrypt (proper salt rounds)
✓ Token structure follows JWT standards
✓ Middleware properly extracts from Authorization header
✓ Error handling in routes is comprehensive

## Next Steps

1. Fix issues 1-3 immediately (Critical/High priority)
2. Add rate limiting (#4) before deploying to production  
3. Plan refresh token implementation (#5) for next sprint"

// After 3 failed attempts to fix race condition

task(
  subagent_type="oracle",
  description="Debug race condition in user registration",
  prompt="I'm hitting a race condition in user registration flow.
          
          Problem: Duplicate users created when rapid parallel registrations
          
          Attempts so far:
          1. Added mutex lock - caused deadlock under load
          2. Used database transaction - race still occurred  
          3. Added optimistic locking - performance degraded badly
          
          Context:
          - PostgreSQL database
          - Express API with 4 worker processes (cluster mode)
          - Registration flow: validate → check exists → create user
          
          Full code attached. What's the correct approach?"
)

// Oracle response:
"## Bottom Line
Your attempts addressed symptoms, not root cause. The issue is a 
TIME-OF-CHECK to TIME-OF-USE (TOCTOU) race in the check-then-create 
pattern. Fix: Use database-level unique constraint + INSERT conflict handling.

## Root Cause Analysis

The race happens here:
```typescript
// Thread 1 and Thread 2 both execute simultaneously
const existingUser = await User.findOne({ email }) // Both see null
if (!existingUser) {
  await User.create({ email }) // Both create! 
}

### Example 3: Performance Analysis

```typescript
task(
  subagent_type="oracle",
  description="Analyze slow API endpoint",
  prompt="Our GET /api/users endpoint is slow (800ms avg response time).
          
          Endpoint: Returns list of users with their recent activity
          
          Current implementation:
          - Fetches all users from PostgreSQL
          - For each user, queries activities table
          - Joins with other tables for user details
          
          Users table: 50K rows
          Activities table: 2M rows
          
          What's the bottleneck and how to fix?"
)

// Oracle response:
"## Bottom Line
Classic N+1 query problem. 50K users × 1 activity query = 50,001 total 
queries. Fix with JOIN or separate bulk query. Target: {`<`}100ms response.

## Action Plan

1. **Replace N+1 with single JOIN** (Effort: Short - 1h)
   ```sql
   -- Current: 50,001 queries
   SELECT * FROM users; -- 1 query
   -- Then for each user:
   SELECT * FROM activities WHERE user_id = ?; -- 50K queries
   
   -- Fixed: 1 query
   SELECT 
     u.*,
     json_agg(a.*) as activities
   FROM users u
   LEFT JOIN activities a ON a.user_id = u.id
   GROUP BY u.id;

## Output Verbosity

Oracle follows strict verbosity constraints:

<ResponseField name="Bottom line" type="string">
  2-3 sentences maximum. No preamble.
</ResponseField>

<ResponseField name="Action plan" type="array">
  ≤7 numbered steps. Each step ≤2 sentences.
</ResponseField>

<ResponseField name="Why this approach" type="array">
  ≤4 bullets when included.
</ResponseField>

<ResponseField name="Watch out for" type="array">
  ≤3 bullets when included.
</ResponseField>

<ResponseField name="Edge cases" type="array">
  Only when genuinely applicable; ≤3 bullets.
</ResponseField>

## Configuration

Customize Oracle in `oh-my-opencode.jsonc`:

```jsonc
{
  "agents": {
    "oracle": {
      "model": "openai/gpt-5.2",
      "variant": "high",
      "temperature": 0.1,
      "reasoningEffort": "medium",
      "textVerbosity": "high",
      "prompt_append": "Additional consultation guidelines...",
      "disable": false
    }
  }
}