--- 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 ```