--- name: warden-second-opinion description: Two-tier diagnostic protocol — spawns fresh subagents to analyze problems when stuck. Invoke manually or triggered by rabbit hole detection. user-invokable: true --- # Second Opinion Protocol > **Policy Area:** WORKFLOW > **Version:** 1.0 > **Status:** Active > **Enforcement:** Tier 1 SHOULD, Tier 2 MUST (per RFC 2119) > **Purpose:** When Claude is stuck in a loop of failed fixes, spawn a fresh subagent with no context baggage to diagnose the root cause. Two tiers escalate from voluntary self-check to mandatory human handoff. --- ## 1. Overview The Second Opinion protocol breaks the cycle of compounding failed fixes by bringing in fresh perspective. Instead of continuing to guess, Claude spawns a separate agent that reads the code without inherited assumptions and delivers an independent diagnosis. Two tiers exist: | Tier | Trigger | Nature | Outcome | |------|---------|--------|---------| | **Tier 1** | 3 edits to same file, or manual | Voluntary (SHOULD) | Structured diagnosis, Claude acts on it | | **Tier 2** | 5 edits to same file | Mandatory (MUST) | Deep diagnosis + human-pasteable summary, Claude STOPS | --- ## 2. Tier 1: Structured Thinking Partner ### 2.1 When It Triggers - **Automatic:** Claude has edited the same file 3 times to fix the same issue, OR - **Manual:** Human invokes `/second-opinion`, OR Claude recognizes it is going in circles Tier 1 is a SHOULD — Claude is expected to use it but may justify skipping if the situation is genuinely different on each attempt. ### 2.2 Step 1: Prepare the Problem Brief Claude prepares a structured brief containing ONLY facts, not theories: ``` PROBLEM BRIEF Goal: [What we are trying to accomplish] What I've tried: 1. [Approach] → [Result] 2. [Approach] → [Result] 3. [Approach] → [Result] Current error: [Exact error message or incorrect behavior] Assumptions I'm making: - [Assumption 1] - [Assumption 2] Key files: - [path/to/file] — [role in the problem] - [path/to/file] — [role in the problem] ``` ### 2.3 Step 2: Spawn the Subagent Spawn a Task agent with the following parameters: - **`subagent_type`:** `general-purpose` - **Description:** `Second opinion: diagnose [brief description of issue]` - **Prompt:** ``` You are a senior engineer providing a second opinion. Another developer has been stuck on a problem and needs fresh eyes. Here is their problem brief: [INSERT PROBLEM BRIEF] Your job: 1. Read the key files listed in the brief 2. Analyze the problem WITHOUT the context baggage of previous attempts 3. Identify the most likely root cause 4. Suggest 1-2 alternative approaches that differ from what was already tried Do NOT try to fix the code. Diagnose only. Return your analysis in this exact format: ROOT CAUSE: [What is actually causing the problem] WHY PREVIOUS APPROACHES FAILED: [What each attempt got wrong or missed] SUGGESTED APPROACH: [1-2 concrete alternative approaches with reasoning] WATCH OUT FOR: [Gotchas, edge cases, or assumptions that may be wrong] ``` ### 2.4 Step 3: Act on the Analysis When the subagent returns its analysis, Claude: 1. Reads the diagnosis carefully 2. Evaluates whether the root cause identification is credible 3. Either: - **Acts on it** — implements the suggested approach, OR - **Escalates to Tier 2** — if the diagnosis does not resolve the issue or the problem is more complex than expected --- ## 3. Tier 2: Root Cause Analyst + Human Handoff ### 3.1 When It Triggers - **Automatic:** Claude has edited the same file 5 times to fix the same issue — this is MANDATORY - **Escalation:** Tier 1 analysis did not resolve the problem - **Manual:** Human requests deep analysis Tier 2 is a MUST — when triggered by the 5-edit threshold, Claude cannot skip it. ### 3.2 Step 1: Prepare the Expanded Problem Brief Same structure as Tier 1, but expanded to include ALL attempts: ``` PROBLEM BRIEF (EXPANDED) Goal: [What we are trying to accomplish] What I've tried (ALL attempts): 1. [Approach] → [Result] 2. [Approach] → [Result] ... N. [Approach] → [Result] Current error: [Exact error message or incorrect behavior] Assumptions I'm making: - [Assumption 1] - [Assumption 2] Key files: - [path/to/file] — [role in the problem] - [path/to/file] — [role in the problem] Previous diagnosis (if Tier 1 ran): - Root cause identified: [what Tier 1 found] - Why it didn't help: [what happened when we tried] ``` ### 3.3 Step 2: Spawn the Deep Diagnosis Subagent Spawn a Task agent with the following parameters: - **`subagent_type`:** `general-purpose` - **Description:** `Second opinion (deep): root cause analysis for [brief description of issue]` - **Prompt:** ``` You are a senior engineer performing a deep root cause analysis. Another developer has been stuck on this problem through multiple failed fix attempts and needs a thorough diagnosis. Here is their expanded problem brief: [INSERT EXPANDED PROBLEM BRIEF] Your job: 1. Read ALL relevant files — not just the ones listed, follow imports and dependencies 2. Trace the execution path or data flow end-to-end 3. Identify which assumptions the developer is making that are WRONG 4. Determine the TRUE root cause, not just the surface symptom 5. Do NOT suggest quick fixes — this needs a real solution Return your analysis in this exact format: ROOT CAUSE: [The actual, underlying cause — be specific and reference exact code] WRONG ASSUMPTIONS: [List each assumption the developer made that is incorrect, and what the reality is] EVIDENCE: [Specific code references, line numbers, or behaviors that prove the root cause] INVESTIGATION PATH: [How you arrived at this conclusion — what you checked and what you found] COMPLEXITY ASSESSMENT: [Is this a simple fix hiding behind symptoms, or a genuine architectural issue? What is the realistic effort to fix it properly?] ``` ### 3.4 Step 3: Generate the Human-Pasteable Summary After the subagent returns its analysis, Claude generates a summary formatted for easy copy-paste into external channels (Slack, forum, colleague chat, etc.): ``` 🔍 SECOND OPINION REQUEST Context: [project, file, what we're building] Problem: [precise description] What was tried (N attempts): 1. [Approach] → [Result] ... Current error: [exact error] Relevant code: [key snippets] Automated analysis found: Root cause: [from subagent] Wrong assumptions: [from subagent] Question: What is the actual root cause and what approach would you recommend? ``` ### 3.5 Step 4: STOP and Present Claude MUST stop all fix attempts and present both artifacts to the human: 1. **The full subagent analysis** — root cause, wrong assumptions, evidence, investigation path, complexity assessment 2. **The human-pasteable summary** — ready to copy into Slack, a forum post, or send to a colleague Claude does NOT attempt further fixes. The human decides next steps. --- ## 4. Key Principles ### Fresh eyes are the point Do not pollute the subagent prompt with your theories about what is wrong. Give it the facts — what you tried, what happened, what the error is. Let it form its own conclusions. The value of a second opinion is destroyed if you lead the witness. ### Diagnosis before treatment The goal is to understand WHY the problem exists, not to generate more fixes. Every failed attempt that came before was a "treatment." What is needed now is a diagnosis. Resist the urge to jump to solutions. ### The human-pasteable summary is a bridge Not every problem can be solved by AI alone. The Tier 2 summary is deliberately formatted so the human can paste it into Slack, a Stack Overflow question, or a message to a colleague. It is a bridge between the AI-assisted workflow and external human expertise. ### Tier 1 is voluntary, Tier 2 is mandatory Tier 1 (SHOULD): Claude is expected to invoke this at 3 edits, but may use judgment. Sometimes the third edit genuinely is the fix. Tier 2 (MUST): At 5 edits to the same file for the same issue, Claude must stop and run the full protocol. No exceptions, no "just one more try." --- *Enforced by rabbit hole detection in warden-post-check.sh. Tier 1 triggers at 3-edit warning. Tier 2 triggers at 5-edit hard stop.*