Deepen Plan - Power Enhancement Mode

Introduction

Note: The current year is 2026. Use this when searching for recent documentation and best practices.

This command takes an existing plan (from /workflows-plan) and enhances each section with parallel research subagents. Each major element gets its own dedicated research subagent to find:

•Best practices and industry patterns
•Performance optimizations
•UI/UX improvements (if applicable)
•Quality enhancements and edge cases
•Real-world implementation examples

The result is a deeply grounded, production-ready plan with concrete implementation details.

Plan File

<plan_path> #$ARGUMENTS </plan_path>

If the plan path above is empty:

•Check for recent plans: ls -la docs/plans/
•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 (Rails, React, Python, TypeScript, etc.)
• Domain areas (data models, APIs, UI, security, performance, etc.)

Create a section manifest:

code

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

2. Discover and Apply Available Skills

<thinking> Dynamically discover all available skills and match them to plan sections. Don't assume what skills exist - discover them at runtime. </thinking>

Step 1: Discover ALL available skills from ALL sources

bash

# 1. Project-local skills (highest priority - project-specific)
ls .claude/skills/

# 2. User's global skills (~/.claude/)
ls ~/.claude/skills/

# 3. compound-engineering plugin skills
ls ~/project/agent-scripts/skills/

# 4. ALL other installed plugins - check every plugin for skills
find ~/.claude/plugins/cache -type d -name "skills" 2>/dev/null

# 5. Also check installed_plugins.json for all plugin locations
cat ~/.claude/plugins/installed_plugins.json

Important: Check EVERY source. Don't assume there is the only plugin. Use skills from ANY installed plugin that's relevant.

Step 2: For each discovered skill, read its SKILL.md to understand what it does

bash

# For each skill directory found, read its documentation
cat [skill-path]/SKILL.md

Step 3: Match skills to plan content

For each skill discovered:

•Read its SKILL.md description
•Check if any plan sections match the skill's domain
•If there's a match, spawn a subagent to apply that skill's knowledge

Step 4: Spawn a subagent in paralle for EVERY matched skill

CRITICAL: For EACH skill that matches, spawn a parallel subagent and instruct it to USE that skill.

For each matched skill:

code

Task general-purpose: "You have the [skill-name] skill available at [skill-path].

YOUR JOB: Use this skill on the plan.

1. Read the skill: cat [skill-path]/SKILL.md
2. Follow the skill's instructions exactly
3. Apply the skill to this content:

[relevant plan section or full plan]

4. Return the skill's full output

The skill tells you what to do - follow it. Execute the skill completely."

Spawn ALL subagents in PARALLEL:

•1 subagent per matched skill
•Each subagent reads and uses its assigned skill
•All run simultaneously
•10, 20, 30 skill subagents is fine

Each subagent:

•Reads its skill's SKILL.md
•Follows the skill's workflow/instructions
•Applies the skill to the plan
•Returns whatever the skill produces (code, recommendations, patterns, reviews, etc.)

Example spawns:

code

Task general-purpose: "Use the frontend-design skill at ~/.claude/plugins/.../frontend-design. Read SKILL.md and apply it to: [UI sections of plan]"

Task general-purpose: "Use the design-agent-native skill at ~/.claude/plugins/.../design-agent-native. Read SKILL.md and apply it to: [agent/tool sections of plan]"

Task general-purpose: "Use the security-patterns skill at ~/.claude/skills/security-patterns. Read SKILL.md and apply it to: [full plan]"

No limit on skill subagents. Spawn one for every skill that could possibly be relevant.

3. Discover and Apply Learnings/Solutions

<thinking> Check for documented learnings from /workflows-compound. These are solved problems stored as markdown files. Spawn a subagent for each learning to check if it's relevant. </thinking>

LEARNINGS LOCATION - Check these exact folders:

code

docs/solutions/           <-- PRIMARY: Project-level learnings (created by /workflows-compound)
├── performance-issues/
│   └── *.md
├── debugging-patterns/
│   └── *.md
├── configuration-fixes/
│   └── *.md
├── integration-issues/
│   └── *.md
├── deployment-issues/
│   └── *.md
└── [other-categories]/
    └── *.md

Step 1: Find ALL learning markdown files

Run these commands to get every learning file:

bash

# PRIMARY LOCATION - Project learnings
find docs/solutions -name "*.md" -type f 2>/dev/null

# If docs/solutions doesn't exist, check alternate locations:
find ~/projects/agent-scripts/docs -name "*.md" -type f 2>/dev/null

Step 2: Read frontmatter of each learning to filter

Each learning file has YAML frontmatter with metadata. Read the first ~20 lines of each file to get:

yaml

---
title: "N+1 Query Fix for Briefs"
category: performance-issues
tags: [activerecord, n-plus-one, includes, eager-loading]
module: Briefs
symptom: "Slow page load, multiple queries in logs"
root_cause: "Missing includes on association"
---

For each .md file, quickly scan its frontmatter:

bash

# Read first 20 lines of each learning (frontmatter + summary)
head -20 docs/solutions/**/*.md

Step 3: Filter - only spawn subagents for LIKELY relevant learnings

Compare each learning's frontmatter against the plan:

•tags: - Do any tags match technologies/patterns in the plan?
•category: - Is this category relevant? (e.g., skip deployment-issues if plan is UI-only)
•module: - Does the plan touch this module?
•symptom: / root_cause: - Could this problem occur with the plan?

SKIP learnings that are clearly not applicable:

•Plan is frontend-only → skip database-migrations/ learnings
•Plan is Python → skip rails-specific/ learnings
•Plan has no auth → skip authentication-issues/ learnings

SPAWN subagents for learnings that MIGHT apply:

•Any tag overlap with plan technologies
•Same category as plan domain
•Similar patterns or concerns

Step 4: Spawn subagents for filtered learnings

For each learning that passes the filter:

code

Task general-purpose: "
LEARNING FILE: [full path to .md file]

1. Read this learning file completely
2. This learning documents a previously solved problem

Check if this learning applies to this plan:

---
[full plan content]
---

If relevant:
- Explain specifically how it applies
- Quote the key insight or solution
- Suggest where/how to incorporate it

If NOT relevant after deeper analysis:
- Say 'Not applicable: [reason]'
"

Example filtering:

code

# Found 15 learning files, plan is about "Rails API caching"

# SPAWN (likely relevant):
docs/solutions/performance-issues/n-plus-one-queries.md      # tags: [activerecord] ✓
docs/solutions/performance-issues/redis-cache-stampede.md    # tags: [caching, redis] ✓
docs/solutions/configuration-fixes/redis-connection-pool.md  # tags: [redis] ✓

# SKIP (clearly not applicable):
docs/solutions/deployment-issues/heroku-memory-quota.md      # not about caching
docs/solutions/frontend-issues/stimulus-race-condition.md    # plan is API, not frontend
docs/solutions/authentication-issues/jwt-expiry.md           # plan has no auth

Spawn subagents in PARALLEL for all filtered learnings.

These learnings are institutional knowledge - applying them prevents repeating past mistakes.

4. Launch Per-Section Research Subagents

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

For each identified section, launch parallel research:

code

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 Ref or Context7 MCP for framework documentation:

For any technologies/frameworks mentioned in the plan, query Ref (1st) or Context7 (if Ref is unavailable).

Use WebSearch for current best practices:

Search for recent (2025-2026) articles, blog posts, and documentation on topics in the plan.

5. Discover and Run ALL Review SubAgents (Only if you are running from Claude Code, CODEX skip 5. )

<thinking> Dynamically discover every available agent and run them ALL against the plan. Don't filter, don't skip, don't assume relevance. 40+ parallel subagents is fine. Use everything available. </thinking>

Step 1: Discover ALL available agents from ALL sources

bash

# 1. Project-local agents (highest priority - project-specific)
find .claude/agents -name "*.md" 2>/dev/null

# 2. User's global agents (~/.claude/)
find ~/.claude/agents -name "*.md" 2>/dev/null

# 3. ALL other installed plugins - check every plugin for agents
find ~/.claude/plugins/cache -path "*/agents/*.md" 2>/dev/null

# 4. Check installed_plugins.json to find all plugin locations
cat ~/.claude/plugins/installed_plugins.json

# 5. For local plugins (isLocal: true), check their source directories
# Parse installed_plugins.json and find local plugin paths

Important: Check EVERY source. Include agents from:

•Project .claude/agents/
•User's ~/.claude/agents/
•ALL other installed plugins (agent-sdk-dev, frontend-design, etc.)
•Any local plugins

Step 2: For each discovered agent, read its description

Read the first few lines of each agent file to understand what it reviews/analyzes.

Step 3: Launch ALL agents in parallel

For EVERY agent discovered, launch a Task in parallel:

code

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

CRITICAL RULES:

•Do NOT filter subagents by "relevance" - run them ALL
•Do NOT skip subagents because they "might not apply" - let them decide
•Launch ALL subagents in a SINGLE message with multiple Task tool calls
•20, 30, 40 parallel subagents is fine - use everything
•Each agent may catch something others miss
•The goal is MAXIMUM coverage, not efficiency

Step 4: Also discover and run research skill subagents

Research skill subagents (like research-best-practices, framework-docs-researcher, git-history-analyzer, research-repo) should also be run for relevant plan sections.

6. Wait for ALL subagents and Synthesize Everything

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

Collect outputs from ALL sources:

•Skill-based subagents - Each skill's full output (code examples, patterns, recommendations)
•Learnings/Solutions subagents - Relevant documented learnings from /workflows-compound
•Research subagents - Best practices, documentation, real-world examples
•Review subagents - All feedback from every reviewer (architecture, security, performance, simplicity, etc.)
•Ref (1st) or Context7 (if Ref is unavailable) queries - Framework documentation and patterns
•Web searches - Current best practices and articles

For each agent's findings, extract:

• Concrete recommendations (actionable items)
• Code patterns and examples (copy-paste ready)
• Anti-patterns to avoid (warnings)
• Performance considerations (metrics, benchmarks)
• Security considerations (vulnerabilities, mitigations)
• Edge cases discovered (handling strategies)
• Documentation links (references)
• Skill-specific patterns (from matched skills)
• Relevant learnings (past solutions that apply - prevent repeating mistakes)

Deduplicate and prioritize:

•Merge similar recommendations from multiple subagents
•Prioritize by impact (high-value improvements first)
•Flag conflicting advice for human review
•Group by plan section

7. Enhance Plan Sections

<thinking> Merge research findings back into the plan, adding depth without changing the original structure. </thinking>

Enhancement format for each section:

markdown

## [Original Section Title]

[Original content preserved]

### Research Insights

**Best Practices:**
- [Concrete recommendation 1]
- [Concrete recommendation 2]

**Performance Considerations:**
- [Optimization opportunity]
- [Benchmark or metric to target]

**Implementation Details:**
```[language]
// Concrete code example from research

Edge Cases:

•[Edge case 1 and how to handle]
•[Edge case 2 and how to handle]

References:

•[Documentation URL 1]
•[Documentation URL 2]

code


### 8. Add Enhancement Summary

At the top of the plan, add a summary section:

```markdown
## Enhancement Summary

**Deepened on:** [Date]
**Sections enhanced:** [Count]
**Research subagents used:** [List]

### Key Improvements
1. [Major improvement 1]
2. [Major improvement 2]
3. [Major improvement 3]

### New Considerations Discovered
- [Important finding 1]
- [Important finding 2]

9. Update Plan File

Write the enhanced plan:

•Preserve original filename
•Add -deepened suffix if user prefers a new file
•Update any timestamps or metadata

Output Format

Update the plan file in place (or if user requests a separate file, append -deepened after -plan, e.g., 2026-01-15-feat-auth-plan-deepened.md).

Quality Checks

Before finalizing:

• All original content preserved
• Research insights clearly marked and attributed
• Code examples are syntactically correct
• Links are valid and relevant
• No contradictions between sections
• Enhancement summary accurately reflects changes

Post-Enhancement Options

After writing the enhanced plan, use the AskUserQuestion tool to present these options:

Question: "Plan deepened at [plan_path]. What would you like to do next?"

Options:

•View diff - Show what was added/changed
•Run /review-technical - Get feedback from reviewers on enhanced plan
•Start /workflows-work - Begin implementing this enhanced plan
•Deepen further - Run another round of research on specific sections
•Revert - Restore original plan (if backup exists)

Based on selection:

•View diff → Run git diff [plan_path] or show before/after
•/review-technical → Call the /review-technical command with the plan file path
•/workflows-work → Call the /workflows-work command with the plan file path
•Deepen further → Ask which sections need more research, then re-run those agents
•Revert → Restore from git or backup

Example Enhancement

Before (from /workflows-plan):

markdown

## Technical Approach

Use React Query for data fetching with optimistic updates.

After (from /plan-deepen):

markdown

## Technical Approach

Use React Query for data fetching with optimistic updates.

### Research Insights

**Best Practices:**
- Configure `staleTime` and `cacheTime` based on data freshness requirements
- Use `queryKey` factories for consistent cache invalidation
- Implement error boundaries around query-dependent components

**Performance Considerations:**
- Enable `refetchOnWindowFocus: false` for stable data to reduce unnecessary requests
- Use `select` option to transform and memoize data at query level
- Consider `placeholderData` for instant perceived loading

**Implementation Details:**
```typescript
// Recommended query configuration
const queryClient = new QueryClient({
  defaultOptions: {
    queries: {
      staleTime: 5 * 60 * 1000, // 5 minutes
      retry: 2,
      refetchOnWindowFocus: false,
    },
  },
});

Edge Cases:

•Handle race conditions with cancelQueries on component unmount
•Implement retry logic for transient network failures
•Consider offline support with persistQueryClient

References:

code


NEVER CODE! Just research and enhance the plan.