strategic-investigation

Original source / Raw SKILL.md

---
name: strategic-investigation
description: >
  Proactive recovery using plan mode and subagents. After 1-2 failed attempts,
  STOP trying variations. Enter plan mode and launch parallel Explore/Plan agents
  to find idiomatic solutions instead of spinning wheels.
---

# Strategic Investigation: Plan Mode Recovery

**CORE PRINCIPLE: After 1-2 failed attempts, STOP trying variations. Enter plan mode and investigate properly using parallel subagents.**

## When to Use This Skill

Use this skill when:
- You've tried 1-2 approaches and they didn't work
- You don't understand WHY something isn't working
- You're tempted to try "just one more thing" or add a hacky workaround
- The error message doesn't make sense
- Multiple approaches seem valid and you're unsure which is idiomatic
- You find yourself guessing instead of knowing

**Warning signs you should have used this earlier:**
- You've been trying variations of the same approach for 5+ minutes
- You're adding workarounds or "temporary" hacks
- The code is getting messier instead of cleaner
- You're saying "this should work but doesn't"

## The Process

### Step 1: STOP and Acknowledge

When you recognize you're stuck:

1. **Stop immediately** - Don't try "just one more thing"
2. **Tell the user:**
   ```
   "I've tried [X approaches] and they're not working. Instead of continuing
   to guess, I'm going to step back and investigate this systematically using
   parallel subagents. This should find the idiomatic solution."
   ```

### Step 2: Enter Plan Mode

Request plan mode to structure your investigation. Plan mode signals you're stepping back from implementation to investigate properly.

### Step 3: Launch Parallel Subagents

Spawn 2-4 focused Explore agents **in parallel** to gather information:

**Subagent Design Principles:**
- Each agent gets ONE focused question
- Agents explore DIFFERENT angles (not variations of same thing)
- Agents are read-only (Explore type)
- Each returns concrete findings with file paths and code snippets

**Common Explore Agent Types:**

```
Explore Agent 1: Pattern Search
- Search labs/packages/patterns/ for similar patterns
- Search patterns/examples/ for curated examples
- Look for patterns that solve similar problems
- Return: file paths, relevant code snippets, patterns used

Explore Agent 2: Documentation Deep-Dive
- Read relevant sections of ~/Code/labs/docs/common/
- Focus on DEBUGGING.md, PATTERNS.md, CELLS_AND_REACTIVITY.md
- Look for exact guidance on this situation
- Return: relevant doc sections, warnings, recommended approaches

Explore Agent 3: Community Knowledge
- Search community-docs/superstitions/ for similar issues
- Check if others have hit this problem
- Return: relevant superstitions, known workarounds

Explore Agent 4: Framework Conventions
- Study how working patterns structure similar code
- What's the "frameworky" way to do this?
- Return: conventions observed, idioms to follow
```

### Step 4: Synthesize Findings

After agents complete:

1. **Review gathered information:**
   - What patterns did similar code use?
   - What exactly do the docs say?
   - What community knowledge exists?

2. **Identify the idiomatic solution:**
   - Which approach follows framework conventions?
   - What do working examples do differently?
   - What would a framework expert do?

3. **Understand WHY this is the right solution:**
   - Don't just copy-paste from examples
   - Be able to explain why this works
   - Understand the underlying principle

### Step 5: Execute with Confidence

Now implement the chosen approach:
- You understand WHY this approach is right
- You've verified it matches framework conventions
- You're not guessing anymore

### Step 6: Handle Continued Failure

**If the solution doesn't work after investigation:**

1. Return to Step 3 with NEW context: "Approach X didn't work because Y"
2. Investigate why the expected solution failed
3. This often reveals the real underlying issue

**After 2 plan-mode investigation cycles without resolution:**
- Escalate to user
- Summarize what you investigated
- Show approaches you tried
- Explain what you learned
- This gives user actionable context to help

## Example Investigation

### Scenario: "Cell not updating reactively"

**Failed attempts:** Changed dependencies, added .get() calls, restructured code

**Investigation plan (launch in parallel):**

```
Explore Agent 1: Pattern Search
"Search labs/packages/patterns/ for computed() usage patterns.
Find 3+ examples of computed cells that update correctly.
Note what they do differently from my failing code."

Explore Agent 2: Documentation
"Read ~/Code/labs/docs/common/CELLS_AND_REACTIVITY.md thoroughly.
Focus on computed() section and any gotchas.
Look for 'don't do X' warnings."

Explore Agent 3: Community Knowledge
"Search community-docs/superstitions/ for 'computed', 'reactive', 'update'.
Check if this is a known edge case with solutions."

Explore Agent 4: Framework Behavior
"Study how other patterns structure reactive computations.
What cell access patterns do working examples use?"
```

**Likely synthesis:**
- Reactivity requires direct cell access, not derived values
- Creating new cells inside computed() breaks tracking
- Need to maintain stable cell references
- Idiomatic approach: lift cell creation to pattern body level

## Good vs Bad Uses

### GOOD - Use Strategic Investigation

- "I've tried computed() and derive() and neither updates. Let me investigate."
- "The type error doesn't make sense. Let me understand what the framework expects."
- "This feels hacky. Let me find the idiomatic way."
- "I'm not sure which approach is right. Let me explore the options properly."

### BAD - Don't Use Strategic Investigation

- Simple typos - just fix them
- Missing imports - just add them
- Error message tells you exactly what's wrong - just apply the fix
- Problem you've solved before - apply known pattern

## Key Principle: Idiomatic Over Working

The goal is not just to find SOMETHING that works, but to find the IDIOMATIC solution:

- **Hacky:** "I'll just cast to any and suppress the error"
- **Idiomatic:** "The framework expects X pattern, let me use that"

If investigation reveals the "right" way is significantly different from your approach, that's valuable - even if your hack might have worked.

## Integration with Other Skills

| Skill | Relationship |
|-------|-------------|
| **community-docs** | Quick check FIRST. If doesn't help after 1-2 attempts → strategic-investigation |
| **recovery-strategies** | Strategic investigation is Step 2.5 in that flow |
| **issue-filing** | Use AFTER investigation if problem is a framework limitation |
| **pattern-dev** | Contains development practices. This skill is for when you're stuck |

## Remember

**Investigation time is NOT wasted time.**

A 5-minute proper investigation often saves 30 minutes of trial-and-error on wrong approaches. Don't skip plan mode thinking "this should be simple" - that's often when you need it most.

**When in doubt, investigate.** It's better to investigate a simple problem than to spin wheels on a complex one.