Oracle

---
name: oracle
argument-hint: "[advice|risks|compare] [question]"
description: Expert advice, risk review, or weighted comparison. Triggers "what should I", "advice on", "what could go wrong", "premortem", "compare approaches", "which is better", "tech selection".
context: fork
---

# Oracle

Three-mode expert consultation: **Advice** for architectural guidance, **Risks** for premortem analysis, **Compare** for weighted approach evaluation.

Product-direction asks ("what should we build", positioning, market fit) belong to `/strategist` — a standing persona that explores the codebase for vision framing; this skill is a single-shot engineering consult.

## Mode: Advice

### How to Answer

1. **Understand the context** - What is the user trying to achieve?
2. **Consider trade-offs** - What are the pros/cons of different approaches?
3. **Recommend clearly** - Give a definitive recommendation
4. **Explain why** - Justify your recommendation
5. **Provide examples** - Show, don't just tell

### Response Format

```
## Recommendation
[Clear recommendation]

## Why
[Reasoning and trade-offs]

## Example
[Code or implementation example]

## Alternatives
[Other valid approaches and when to use them]
```

### Remember

- Prioritize Darkroom conventions
- Store valuable insights as learnings

---

## Mode: Risks

Analyze potential failure modes before they happen.

### Purpose

Imagine the project has failed. What went wrong?

This technique surfaces risks that optimism bias might hide.

### Analysis Framework

#### 1. Technical Risks
- What could break?
- What dependencies might fail?
- What edge cases are unhandled?
- What performance issues might emerge?

#### 2. Integration Risks
- How might this affect other parts of the system?
- What backwards compatibility issues exist?
- What migration challenges are there?

#### 3. Operational Risks
- What could go wrong in production?
- What monitoring is missing?
- What recovery procedures are needed?

#### 4. User Experience Risks
- How might users misuse this?
- What accessibility issues exist?
- What confusion might arise?

### Output Format

```
## Premortem: [Feature/Change]

### High Risk
- [Critical failure mode]
  → Mitigation: [How to prevent]

### Medium Risk
- [Significant issue]
  → Mitigation: [How to address]

### Low Risk
- [Minor concern]
  → Mitigation: [Simple fix]

### Recommendations
1. [Priority action]
2. [Secondary action]
3. [Nice to have]
```

### When to Run

- Before large refactoring
- Before deploying new features
- Before architectural changes
- When something feels risky

### Remember

- Be genuinely pessimistic
- Consider non-obvious failure modes
- Propose concrete mitigations
- Store risks as learnings for future reference

---

## Mode: Compare

Structured approach to comparing multiple solutions using parallel evaluation, weighted scoring, and ADR output.

### When to Use

- Choosing between technologies (e.g., Zustand vs Jotai vs Redux)
- Evaluating architecture patterns (e.g., monorepo vs polyrepo)
- Comparing implementation approaches for a feature
- Any decision with 2+ viable options and meaningful trade-offs

### When NOT to Use

- One option is clearly superior (just recommend it)
- Trivial decisions (formatting, naming)
- Already decided by team convention

### Workflow

#### 1. Define Criteria

Establish evaluation criteria with weights (must sum to 100):

```
| Criterion        | Weight | Description                        |
|------------------|--------|------------------------------------|
| Performance      | 25     | Runtime speed, bundle size         |
| DX               | 20     | Developer experience, API quality  |
| Maintainability  | 20     | Long-term code health              |
| Ecosystem        | 15     | Community, plugins, docs           |
| Migration Cost   | 10     | Effort to adopt                    |
| Type Safety      | 10     | TypeScript integration quality     |
```

**Preset Criteria Sets:**

- **Frontend**: Performance (25), DX (20), Bundle Size (20), Accessibility (15), Ecosystem (10), Type Safety (10)
- **Backend**: Performance (25), Scalability (20), Maintainability (20), Security (15), Ops Complexity (10), Cost (10)
- **Infrastructure**: Reliability (25), Cost (20), Scalability (20), Ops Complexity (15), Vendor Lock-in (10), Migration (10)

#### 2. Spawn Parallel Evaluators

This step needs the `Agent` tool, which is why oracle no longer binds to the `explore` agent (explore's own tools list has no Agent/Task) — the skill runs in its forked context with the default full toolset instead. Spawn one `explore` agent per approach in a SINGLE message:

```
Agent(explore, "Evaluate [Approach A] against criteria: [criteria list with weights]. Score 1-10 per criterion. Include concrete examples, code samples, and evidence.")
Agent(explore, "Evaluate [Approach B] against criteria: [criteria list with weights]. Score 1-10 per criterion. Include concrete examples, code samples, and evidence.")
Agent(explore, "Evaluate [Approach C] against criteria: [criteria list with weights]. Score 1-10 per criterion. Include concrete examples, code samples, and evidence.")
```

Each evaluator must return:
- Score (1-10) per criterion with justification
- Concrete code example
- Key risks and mitigations
- Best-case and worst-case scenarios

#### 3. Collect and Score

Build the comparison matrix from evaluator responses.

#### 4. Synthesize Recommendation

Produce the final output in ADR format.

### Output Format

#### Comparison Matrix

```
## Comparison: [Decision Title]

| Criterion (Weight)      | Option A | Option B | Option C |
|-------------------------|----------|----------|----------|
| Performance (25)        | 8 (200)  | 6 (150)  | 7 (175)  |
| DX (20)                 | 9 (180)  | 7 (140)  | 6 (120)  |
| Maintainability (20)    | 7 (140)  | 8 (160)  | 5 (100)  |
| Ecosystem (15)          | 8 (120)  | 9 (135)  | 4 (60)   |
| Migration Cost (10)     | 6 (60)   | 8 (80)   | 3 (30)   |
| Type Safety (10)        | 9 (90)   | 7 (70)   | 8 (80)   |
| **TOTAL**               | **790**  | **735**  | **565**  |

Score format: raw (weighted) where weighted = raw * weight
```

> **When the call is close or taste-heavy, prefer pairwise judgment over absolute scores.** Absolute 1–10 scoring drifts and compresses — everything clusters at 6–8, and the "winner" can hinge on one evaluator's mood. Comparative judgment is more reliable: have evaluators judge A-vs-B head-to-head and run a small tournament (each comparison its own call). The weighted matrix above stays right for criteria-driven calls with hard trade-offs; reach for pairwise when the totals land within a few points of each other or the decision is about taste (naming, design, API feel).

> This extends the base ADR template from `agents/planner.md` with scoring matrix and detailed risk sections.

#### ADR Template

```markdown
# ADR-NNN: [Decision Title]

## Status
Proposed

## Context
[Why this decision is needed. What problem we're solving.]

## Options Considered
1. **Option A** - [one-line summary]
2. **Option B** - [one-line summary]
3. **Option C** - [one-line summary]

## Decision
We will use **Option A** because [primary reasons].

## Scoring Summary
[Comparison matrix from above]

## Consequences

### Positive
- [benefit 1]
- [benefit 2]

### Negative
- [trade-off 1]
- [trade-off 2]

### Risks
- [risk 1] → Mitigation: [approach]

## References
- [relevant links, docs, benchmarks]
```

### Examples

#### Example: State Management Selection

```
User: "Which state management should we use for this Next.js app?"

→ Define criteria (Frontend preset)
→ Agent(explore, "Evaluate Zustand against frontend criteria...")
  + Agent(explore, "Evaluate Jotai against frontend criteria...")
  + Agent(explore, "Evaluate Redux Toolkit against frontend criteria...")
→ Build comparison matrix
→ Output ADR recommendation
```

#### Example: Monorepo Tooling

```
User: "Compare Turborepo vs Nx for our monorepo"

→ Define criteria (Infrastructure preset)
→ Agent(explore, "Evaluate Turborepo...") + Agent(explore, "Evaluate Nx...")
→ Build comparison matrix
→ Output ADR recommendation
```