deepen-plan

Dynamic-workflow alternative (opt-in). A Workflow-tool port of this skill lives at [workflows/deepen-plan.workflow.js](./workflows/deepen-plan.workflow.js) — deterministic fan-out, journaled resume, schema-validated output. Run it with Workflow({ scriptPath: "plugins/soleur/skills/deepen-plan/workflows/deepen-plan.workflow.js", args: ... }). The prose skill below stays the default; the two coexist during calibration. See [knowledge-base/project/specs/feat-review-workflow-prototype/spec.md](../../../../knowledge-base/project/specs/feat-review-workflow-prototype/spec.md).

Deepen Plan - Power Enhancement Mode

Introduction

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

This skill takes an existing plan (from the soleur:plan skill) and enhances each section with parallel research agents. Each major element gets its own dedicated research sub-agent 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:

1. Check for recent plans: ls -la knowledge-base/project/plans/
2. Ask the user: "Which plan would you like to deepen? Please provide the path (e.g., knowledge-base/project/plans/2026-01-15-feat-my-feature-plan.md)."

Do not proceed until a valid plan file path is provided.

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:

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

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

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

# 3. soleur plugin skills
ls ~/.claude/plugins/cache/*/soleur/*/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 soleur 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

# 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 sub-agent to apply that skill's knowledge

Step 4: Spawn a sub-agent for EVERY matched skill

CRITICAL: For EACH skill that matches, spawn a separate sub-agent and instruct it to USE that skill.

For each matched skill:

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 skill sub-agents in PARALLEL:

• 1 sub-agent per matched skill
• Each sub-agent reads and uses its assigned skill
• All run simultaneously
• 10, 20, 30 skill sub-agents is fine

Each sub-agent:

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

Example spawns:

Task general-purpose: "Use the dhh-rails-style skill at ~/.claude/plugins/.../dhh-rails-style. Read SKILL.md and apply it to: [Rails sections of plan]"

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 agent-native-architecture skill at ~/.claude/plugins/.../agent-native-architecture. 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 sub-agents. Spawn one for every skill that could possibly be relevant.

3. Discover and Apply Learnings/Solutions

<thinking> Check for documented learnings from the soleur:compound skill. These are solved problems stored as markdown files. Spawn a sub-agent for each learning to check if it's relevant. </thinking>

LEARNINGS LOCATION - Check these exact folders:

knowledge-base/project/learnings/           <-- PRIMARY: Project-level learnings (created by soleur: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:

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

# If docs/solutions doesn't exist, check alternate locations:
find .claude/docs -name "*.md" -type f 2>/dev/null
find ~/.claude/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:

---
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:

# Read first 20 lines of each learning (frontmatter + summary)
head -20 knowledge-base/project/learnings/**/*.md

Step 3: Filter - only spawn sub-agents 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 sub-agents for learnings that MIGHT apply:

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

Step 4: Spawn sub-agents for filtered learnings

For each learning that passes the filter:

Task general-purpose: "
LEARNING FILE: [f