/ia-plan

name: ia-plan
description: Transform feature descriptions into well-structured project plans following conventions
argument-hint: "[feature description, bug report, or improvement idea]"

Create a plan for a new feature or bug fix

Follow the `ia-planning` skill for methodology (file persistence in `.plan/`, phase sizing, context management rules). This command adds structured research, issue templates, and `docs/plans/` output on top of that methodology.

Introduction

Transform feature descriptions, bug reports, or improvement ideas into well-structured markdown files issues that follow project conventions and best practices. This command provides flexible detail levels to match your needs.

Feature Description

<feature_description> #$ARGUMENTS </feature_description>

**If the feature description above is empty, ask the user:** "What would you like to plan? Please describe the feature, bug fix, or improvement you have in mind."

Do not proceed until you have a clear feature description from the user.

0. Idea Refinement

**Check for brainstorm output first.** Look for recent relevant brainstorms in `docs/brainstorms/`:

ls -la docs/brainstorms/*.md 2>/dev/null | head -10

A brainstorm is relevant if its topic matches the feature description, created within the last 14 days, and (if multiple match) prefer the most recent.

**If a relevant brainstorm exists:** Read it thoroughly, announce "Found brainstorm from [date]: [topic]. Using as foundation." and carry forward all decisions, constraints, success criteria, and technical choices into the plan. Skip baseline idea refinement and run a gap-analysis interview focused only on implementation concerns the brainstorm didn't cover (deployment/rollback, monitoring, data migration, performance, security at the implementation level). The brainstorm is the origin document — reference it with `(see brainstorm: docs/brainstorms/<filename>)` throughout the plan and scan each brainstorm section before finalizing to verify nothing was dropped.

If multiple brainstorms could match, use `AskUserQuestion` to ask which to use.

**If no brainstorm found (or not relevant):** Run idea refinement using the `ia-brainstorming` skill's Phase 1 interview protocol and the deep interview protocol in CLAUDE.md. Use `AskUserQuestion` for all prompts. Continue until the idea is clear OR the user says "proceed."

**Gather signals for the research decision** during refinement: user familiarity with the codebase, intent (speed vs thoroughness), topic risk (security/payments/external APIs warrant more caution), and uncertainty level.

**Skip option:** If the feature description is already detailed, offer: "Your description is clear. Should I proceed with research, or refine further?"

Main Tasks

1. Local Research (Always Runs - Parallel)

<thinking> First, I need to understand the project's conventions, existing patterns, and any documented learnings. This is fast and local - it informs whether external research is needed. </thinking>

Run these agents **in parallel** to gather local context:

• Task ia-repo-research-analyst(feature_description)
• Task ia-learnings-researcher(feature_description)

**What to look for:**

• **Repo research:** existing patterns, CLAUDE.md guidance, technology familiarity, pattern consistency
• **Learnings:** documented solutions in `docs/solutions/` that might apply (gotchas, patterns, lessons learned)

These findings inform the next step.

1.5. Research Decision

Based on signals from Step 0 and findings from Step 1, decide on external research.

**High-risk topics → always research.** Security, payments, external APIs, data privacy. The cost of missing something is too high. This takes precedence over speed signals.

**Strong local context → skip external research.** Codebase has good patterns, CLAUDE.md has guidance, user knows what they want. External research adds little value.

**Uncertainty or unfamiliar territory → research.** User is exploring, codebase has no examples, new technology. External perspective is valuable.

**Announce the decision and proceed.** Brief explanation, then continue. User can redirect if needed.

Examples:

• "Your codebase has solid patterns for this. Proceeding without external research."
• "This involves payment processing, so I'll research current best practices first."

1.5b. External Research (Conditional)

**Only run if Step 1.5 indicates external research is valuable.**

Run these agents in parallel:

• Task ia-best-practices-researcher(feature_description)

1.6. Consolidate Research

After all research steps complete, consolidate findings:

• Document relevant file paths from repo research (e.g., `src/services/ExampleService.ts:42`)
• **Include relevant institutional learnings** from `docs/solutions/` (key insights, gotchas to avoid)
• Note external documentation URLs and best practices (if external research was done)
• List related issues or PRs discovered
• Capture CLAUDE.md conventions

**Optional validation:** Briefly summarize findings and ask if anything looks off or missing before proceeding to planning.

2. Plan Structure & Naming

Draft a clear, searchable title using conventional format (`feat:`, `fix:`, `refactor:`) and convert it to a filename: `YYYY-MM-DD-<type>-<kebab-case-title>-plan.md`. Keep the descriptive portion 3-5 words so plans are findable by context.

Example: `feat: Add User Authentication` → `2026-01-21-feat-add-user-authentication-plan.md`

Choose the detail level in Step 4 based on scope. The `ia-planning` skill's Plan Template owns the section structure — do not restate sections here.

3. SpecFlow Analysis

After planning the issue structure, run SpecFlow Analyzer to validate and refine the feature specification:

• Task ia-spec-flow-analyzer(feature_description, research_findings)

**SpecFlow Analyzer Output:**

• [ ] Review SpecFlow analysis results
• [ ] Incorporate any identified gaps or edge cases into the