/ia-deepen-plan

name: ia-deepen-plan
description: Expand each section of a plan via parallel research agents that add framework specifics, library conventions, and concrete implementation steps
argument-hint: "[path to plan file]"

Deepen Plan - Power Enhancement Mode

Plan File

<plan_path> #$ARGUMENTS </plan_path>

**If the plan path above is empty:** 1. Check for recent plans: `ls -la docs/plans/` 2. Ask the user: "Which plan would you like to deepen? Please provide the path (e.g., `docs/plans/2026-01-15-feat-my-feature-plan.md`)."

Do not proceed until you have a valid plan file path.

Main Tasks

1. Parse and Analyze Plan Structure

<thinking> First, read and parse the plan to identify each major section that can be enhanced with research. </thinking>

**Read the plan file and extract:**

• [ ] Overview/Problem Statement
• [ ] Proposed Solution sections
• [ ] Technical Approach/Architecture
• [ ] Implementation phases/steps
• [ ] Code examples and file references
• [ ] Acceptance criteria
• [ ] Any UI/UX components mentioned
• [ ] Technologies/frameworks mentioned (React, Python, TypeScript, Laravel, etc.)
• [ ] Domain areas (data models, APIs, UI, security, performance, etc.)

**Create a section manifest:**

Section 1: [Title] - [Brief description of what to research]
Section 2: [Title] - [Brief description of what to research]
...

2. Discover All Available Skills and Agents

Discover everything once upfront. Match skills and agents to plan sections, then spawn sub-agents in later steps.

# Skills: project-local, user-global, all plugins
ls .claude/skills/ 2>/dev/null
ls ~/.claude/skills/ 2>/dev/null
find ~/.claude/plugins/cache -type d -name "skills" 2>/dev/null

# Agents: project-local, user-global, all plugins (skip workflow/ orchestrators)
find .claude/agents -name "*.md" 2>/dev/null
find ~/.claude/agents -name "*.md" 2>/dev/null
find ~/.claude/plugins/cache -path "*/agents/*.md" -not -path "*/workflow/*" 2>/dev/null

Read each discovered SKILL.md description and agent frontmatter. Build a manifest:

Skills:  [name] -> [description] -> [matching plan sections]
Agents:  [name] -> [description] -> [matching plan sections]

3. Apply Matched Skills

For each skill that matches plan content, spawn a sub-agent to apply it:

Task general-purpose: "Read [skill-path]/SKILL.md and follow its instructions.
Apply the skill to this plan content: [relevant section or full plan].
Return the skill's full output."

Spawn all skill sub-agents in parallel, one per matched skill. Cap at 10 skill agents -- if more than 10 match, select the 10 most directly relevant to the plan's core domain.

4. Discover and Apply Learnings/Solutions

Dispatch the `ia-learnings-researcher` agent with the plan content. It handles the full flow: scanning `docs/solutions/` (and fallbacks in `.claude/docs/` or `~/.claude/docs/`), reading frontmatter, filtering by tag/category/module/symptom against the plan, and returning only learnings that apply with a specific explanation of how.

Task ia-learnings-researcher("Plan content:\n---\n[full plan content]\n---\n\nFind documented learnings in docs/solutions/ that apply to this plan. For each relevant learning: quote the key insight, explain how it applies, and suggest where to incorporate it. Skip non-applicable learnings with a one-line reason.")

These learnings are institutional knowledge — applying them prevents repeating past mistakes. The agent encapsulates the filter logic so this command doesn't need to restate it.

5. Launch Per-Section Research Agents

<thinking> For each major section in the plan, spawn dedicated sub-agents to research improvements. Use the Explore agent type for open-ended research. </thinking>

**For each identified section, launch parallel research:**

Task Explore: "Research best practices, patterns, and real-world examples for: [section topic].
Find:
- Industry standards and conventions
- Performance considerations
- Common pitfalls and how to avoid them
- Documentation and tutorials
Return concrete, actionable recommendations."

**Also use Context7 MCP for framework documentation:**

For any technologies/frameworks mentioned in the plan, query Context7:

mcp__plugin_whetstone_context7__resolve-library-id: Resolve [framework] to a Context7 library ID
mcp__plugin_whetstone_context7__query-docs: Fetch current docs for that library ID, scoped to a query

**Use WebSearch for current best practices:**

Search for recent (within the last 2 years) articles, blog posts, and documentation on topics in the plan.

6. Run Review and Research Agents

Using the agent manifest from Step 2, launch review and research agents against the plan. Skip `workflow/` agents (orchestrators, not reviewers).

For each matched agent:

Task [agent-name]: "Review this plan using your expertise. Apply all your checks and patterns. Plan content: [full plan content]"

Launch all agents in a single message with multiple Task tool calls. Cap at 10 review agents -- if more match, select those most relevant to the plan's domain. Research agents (`ia-best-practices-researcher`, `ia-repo-research-analyst`, `ia-git-history-analyzer`) run in addition to the review cap.

7. Wait for ALL Agents and Synthesize Everything

<thinking> Wait for ALL parallel agents to complete - skills, research agents, review agents, everything. Then synthesize all findings into a comprehensive enhancement. </thinking>

**Collect outputs from ALL sources:**

1. **Skill-based sub-agents** - Each skill's full output (code examples, patterns, recommendations) 2. **Learnings/Solutions sub-agents** - Relevant documented learnings from /ia-compound 3. **Research agents** - Best practices, documentation, real-world examples 4. **Review agents** - All feedback from every reviewer (architecture, security, performance, simplicity, etc.) 5. **Context7 queries** - Framework documentation and patterns 6. **Web searches** - Cu