plan-improvements

Plan Improvements Command

Perform a comprehensive analysis of the current codebase to identify improvement opportunities, then generate detailed recommendations and a phased implementation plan.

See also: /create-plan for requirements-driven planning from BRD/PRD/TDD documents. /ultra-plan for issue/bug lists requiring deep investigation.

Optional Arguments

Argument	Alias	Description
--recommendations-only	--no-plan	Stop after generating RECOMMENDATIONS.md — skip implementation plan generation. Enables a two-stage workflow where you review/edit recommendations before running /create-plan RECOMMENDATIONS.md to generate the plan.
--max-phases <n>		Maximum number of phases to generate (default: 8). If analysis yields more phases than this limit, group related items to stay within bounds or suggest splitting into multiple plan files.

Argument detection: Check if the user's message includes --recommendations-only or --no-plan. If either is present, set the internal flag RECOMMENDATIONS_ONLY = true. Otherwise, RECOMMENDATIONS_ONLY = false. Check for --max-phases <n> and set MAX_PHASES accordingly (default: 8).

Input Validation

Before proceeding, verify:

• This is a code project with meaningful source files (not empty or purely documentation)
• The repository structure is readable and accessible
• There is sufficient existing code to analyze for improvements

For trivial projects or fresh repositories, ask the user if they want a full improvement plan or just architectural guidance.

Instructions

Phase 1: Deep Codebase Analysis

Thoroughly analyze the codebase with extended thinking enabled.

Root Cause and Interrelationship Analysis

Critical: Do not just catalog surface-level symptoms. For every issue identified during analysis, aggressively investigate to understand:

1. Root cause — Why does this problem exist? Is it a design flaw, an oversight, a dependency issue, or accumulated drift? Understanding the root cause determines whether the fix is a config change or an architectural refactor.
2. Impact and risk — What is the blast radius? Does this issue affect one file or cascade across modules? What happens if we fix it incorrectly?
3. Interrelationships — After cataloging all findings, map the connections between them. Issues that share root causes or affect overlapping code paths must be addressed together. A recommendation that fixes problem A but exacerbates problem B is not a recommendation — it's a liability.
4. Architectural fit — Every recommendation must produce changes that fit within the project's overall architecture and intent. Do not propose isolated patches that create technical debt or trigger a whack-a-mole fix cycle. Design integrated, cohesive solutions where a single well-designed change addresses multiple related concerns.