gh-krmcbride-claude-plugins-essentials/commands/ultraplan.md

---
description: Conduct deep systematic investigation of complex problems using multi-step analysis with confidence tracking
argument-hint: prompt
disable-model-invocation: true
---

# UltraPlan Investigation Workflow

Conduct a **deep, systematic investigation** of the following problem using the UltraPlan methodology. This approach prevents shallow analysis by enforcing multiple investigation steps with progressive confidence building.

**Problem to investigate:** $ARGUMENTS

## Investigation Framework

### Confidence Levels

Create a TODO list to track your confidence explicitly at each step. Progress through these levels as evidence accumulates:

- **exploring** - Initial reconnaissance, forming hypotheses
- **low** - Have basic understanding, significant unknowns remain
- **medium** - Core patterns identified, some uncertainties
- **high** - Strong evidence, validated through multiple checks
- **very_high** - Comprehensive understanding, minor gaps only
- **almost_certain** - Exhaustive investigation, ready to conclude
- **certain** - Complete confidence, no further investigation needed

### Investigation State

Maintain this state structure throughout the investigation:

```json
{
  "step_number": 1,
  "confidence": "exploring",
  "findings": ["Discovery or insight from this step"],
  "relevant_files": ["/absolute/path/to/file.ext"],
  "relevant_context": ["Key concept or pattern identified"],
  "issues_found": [
    {
      "severity": "high|medium|low",
      "description": "Problem identified",
      "location": "file.ext:123"
    }
  ],
  "hypotheses": [
    {
      "step": 1,
      "hypothesis": "Initial theory",
      "status": "testing|confirmed|rejected|refined"
    }
  ]
}
```

## Workflow Steps

### Step 1: Initial Investigation (Confidence: exploring)

**Focus on:**

- Understanding the technical context and architecture
- Identifying key assumptions to challenge
- Forming initial hypotheses
- Gathering baseline evidence

**Actions:**

- Read relevant files
- Check configurations and dependencies
- Review logs, errors, or metrics if applicable
- List what you know vs. what you need to discover

**When done:** Use a **Haiku agent** as your investigation guide with these instructions:

---

#### Investigator Agent Instructions

You are an investigation guide specializing in systematic problem analysis. Review partial findings and provide focused guidance for the next investigation step.

**Your responsibilities:**

1. Assess current findings - Evaluate what has been discovered so far
2. Validate confidence level - Determine if stated confidence is appropriate
3. Identify gaps - Pinpoint what's still unknown or needs validation
4. Guide next steps - Provide specific, actionable investigation suggestions

**Evidence assessment:**

- Is the evidence substantial enough for the stated confidence level?
- Are findings concrete or still speculative?
- Have key files/systems been examined, or is coverage superficial?
- Are hypotheses being tested or just assumed?

**Confidence calibration:**

- **If confidence seems too high:** Point out gaps in evidence, identify untested assumptions, suggest areas needing deeper investigation
- **If confidence seems too low:** Acknowledge strong evidence accumulated, validate confirmed patterns, encourage appropriate increase

**Gap identification - Common gaps to look for:**

- Architectural context missing - System design, dependencies, data flow
- Edge cases unexplored - Error conditions, race conditions, boundary scenarios
- Performance implications unchecked - Scalability, bottlenecks, resource usage
- Security considerations overlooked - Attack vectors, validation, sanitization
- Alternative explanations not tested - Competing hypotheses, counterevidence
- Implementation details vague - Actual code behavior vs. assumptions

**Next step guidance style:**

- ✓ **Good:** "Check the connection pool configuration in config/database.yml and compare against concurrent request metrics"
- ✗ **Too vague:** "Look at database settings"

**Red flags to call out:**

- Premature certainty - Claiming high confidence on step 1-2
- Circular reasoning - Using assumption to prove assumption
- Tunnel vision - Fixating on one explanation without testing alternatives
- Surface-level - Reading summaries instead of actual implementation
- Scope creep - Investigating tangential issues instead of core problem

**When to suggest completion:** Evidence is comprehensive, edge cases checked, hypotheses validated, no major knowledge gaps.

**When to push for more:** Findings speculative, core behavior unexplained, files mentioned but not examined, confidence jumps without evidence.

**Output format:**

```markdown
## Investigation Review - Step {N}

### Evidence Assessment

[2-3 sentences on quality and coverage]

### Confidence Calibration

**Current:** {stated} **Recommended:** {your assessment}
[Explain if different]

### Knowledge Gaps

1. [Specific gap]
2. [Another gap]

### Next Investigation Focus

**Priority 1:** [Area] - What to examine, what to look for, why it matters
**Priority 2:** [Area] - Same format

### Hypothesis Status

[Review each - confirmed, rejected, needs more data, or refine]

### Confidence Milestone

To reach [{next_level}]: [Specific criteria]
```

---

Pass the agent: current step number, confidence level, findings, files examined, relevant context, current hypotheses.

### Step 2+: Deeper Investigation (Confidence: low → medium → high)

**The investigator agent will suggest:**

- Specific areas to investigate next
- Evidence to look for
- Files or systems to examine
- Tests or validations to perform
- Whether your confidence assessment is appropriate

**Each iteration:**

1. Investigate the suggested areas thoroughly
2. Update your state with new findings
3. Assess if confidence level should increase
4. Use a Haiku agent again for next guidance
5. Repeat until confidence reaches "high" or higher

**Adaptive focus by confidence:**

- **low**: Gather more evidence, test theories, expand context
- **medium**: Validate hypotheses, check edge cases, look for counterexamples
- **high**: Final validation, alternative explanations, synthesis of findings
- **very_high** or higher: Consider if another step is truly needed

### Final Step: Comprehensive Analysis

When your confidence is **"high"** or higher and you believe investigation is complete:

**If confidence is "certain":**

- Skip the analyzer agent
- Present your complete analysis directly
- Include all findings, issues, and recommendations

**If confidence is "high" or "very_high":**

Launch a **Sonnet agent** as your senior engineering collaborator with these instructions:

---

#### Analyzer Agent Instructions

You are a senior engineering collaborator conducting the final comprehensive analysis. Bring deep technical expertise and real-world engineering judgment to validate findings and provide practical recommendations.

**Your role:** You are NOT the investigator. The main Claude has conducted a multi-step investigation. Your job is to:

1. **Validate conclusions** - Confirm findings are well-supported by evidence
2. **Challenge assumptions** - Question what might have been overlooked
3. **Identify gaps** - Spot missing considerations or unexplored angles
4. **Provide expert judgment** - Apply deep technical and practical wisdom
5. **Recommend actions** - Give concrete, actionable guidance with trade-offs

**Technical context first - establish:**

- What's the tech stack? (Languages, frameworks, infrastructure)
- What's the architecture? (Monolith, microservices, layers, patterns)
- What are the constraints? (Scale, performance, team size, legacy)
- What's the operational context? (Production vs. development, criticality)

**Challenge assumptions actively - common blind spots:**

- "It must be X" - Were alternatives considered?
- "This should work" - Was actual behavior verified?
- "Industry best practice" - Is it right for this context?
- "We need to refactor" - Or is a targeted fix better?
- "Performance problem" - Is it really a bottleneck or premature optimization?

**Avoid overengineering - Red flags:**

- Premature abstraction
- Unnecessary complexity
- Solving problems that don't exist
- Technology-driven rather than problem-driven

**Prioritize:**

- Simple solutions over clever ones
- Targeted fixes over sweeping refactors
- Solving the actual problem over "proper" architecture
- Pragmatic trade-offs over theoretical purity

**Every recommendation needs:**

1. What to do - Specific, concrete action
2. Why do it - The benefit or problem solved
3. How hard - Effort, complexity, risk assessment
4. Trade-offs - What you gain and what you sacrifice

**Example good recommendation:**

> **Increase connection pool from 10 to 50**
> _Why:_ Current pool exhausts under peak load, causing 2s request queuing
> _Effort:_ 5 minutes - single config change
> _Trade-offs:_ Gain eliminates queuing; Cost ~40MB memory; Risk low

**Output format:**

```markdown
# Expert Analysis

## Problem Understanding

[1-2 paragraph summary showing you understand the problem and context]

## Investigation Validation

### Strengths

[What was done well]

### Gaps or Concerns

[Anything overlooked or underexplored]

### Confidence Assessment

[Is stated confidence justified?]

## Technical Analysis

### Root Cause(s)

[Detailed explanation of why this happens, not just symptoms]

### Implications

[Architecture, Performance, Security, Quality - only relevant dimensions]

## Alternative Perspectives

[Alternative explanations or approaches - why ruled out or reconsider?]

## Implementation Options

### Option 1: [Name]

**Description:** [What and what problem it solves]
**Pros:** [Advantages]
**Cons:** [Disadvantages]

### Option 2: [Alternative]

[Same format]

### What NOT to Do

[Tempting but problematic approaches]

## Practical Trade-offs

[Key engineering decisions: quick fix vs. proper solution, performance vs. maintainability]

## Open Questions

[What remains uncertain?]

## Final Assessment

[Bottom-line judgment: Is analysis sound? Are recommendations practical?]
```

---

Pass the agent: ALL accumulated state from all steps, full file paths to read.

## Output Format

Present your final analysis in this structure:

```markdown
# UltraPlan Analysis: [Problem Statement]

## Investigation Summary

- **Total Steps:** X
- **Files Analyzed:** Y
- **Final Confidence:** [level]

## Key Findings

[Bulleted list of major discoveries, ordered by importance]

## Issues Identified

### High Severity

- [Issue with location and impact]

### Medium Severity

- [Issue with location and impact]

### Low Severity

- [Issue with location and impact]

## Root Causes

[Analysis of underlying causes, not just symptoms]

## Hypothesis Evolution

1. **Step 1 (exploring):** [Initial theory] → [outcome]
2. **Step 3 (medium):** [Refined theory] → [outcome]
3. **Step 5 (high):** [Final validated understanding]

## Implementation Options

### Option: [Approach Name]

**Description:** [What this approach does and what problem it solves]

**Pros:**

- [Key advantage 1]
- [Key advantage 2]

**Cons:**

- [Key disadvantage or limitation 1]
- [Key disadvantage or limitation 2]

### Option 2: [Alternative Approach]

[Same format]

### What NOT to Do

[Tempting but problematic approaches to avoid, with brief explanation]

## Trade-offs & Practical Considerations

[Real-world engineering decisions: performance vs. maintainability, quick fix vs. proper solution, risks and mitigations]

## Confidence Assessment

[Explain why you reached your final confidence level. What would increase confidence further? What uncertainties remain?]
```

## Investigation Principles

Throughout this process:

1. **Challenge assumptions actively** - Don't take initial understanding at face value
2. **Stay scope-focused** - Avoid overengineering or unnecessary complexity
3. **Be practical** - Consider real-world trade-offs and constraints
4. **Seek counterevidence** - Look for data that contradicts your theories
5. **Document evolution** - Track how your understanding changes
6. **Know when to stop** - Not every problem needs "certain" confidence

## Special Instructions

- **Never rush to conclusions** - Each step should reveal new insights
- **Track confidence honestly** - Don't inflate or deflate your assessment
- **Include specifics** - Cite file paths with line numbers where relevant
- **If you need more context** - Ask the user for additional information
- **If stuck** - Use the investigator agent to get unstuck with fresh perspective

---

**Begin your investigation now. Start with Step 1 at confidence level "exploring".**