/structured-plan-mode

name: structured-plan-mode
description: This skill should be used when planning and tracking complex feature implementations that require systematic task decomposition. Use this skill to break down large features into manageable, well-documented tasks with clear dependencies, action items, and success criteria. The skill provides a structured template and methodology for iterative planning and tracking throughout implementation.

Structured Plan Mode Skill

Purpose

This skill provides a structured approach for planning and tracking complex feature implementations through systematic task decomposition. It helps break down large, multi-component features into manageable tasks with clear goals, dependencies, and success criteria.

When to Use This Skill

Use this skill when:

• **Complex features**: Features requiring multiple components or integration points
• **Multi-step implementations**: Work spanning several days with interdependent tasks
• **Pattern-setting work**: Features that will establish patterns for future development
• **Research required**: Work where multiple approaches need evaluation

Do NOT use this skill for:

• Simple bug fixes
• Trivial feature additions
• One-off scripts or experiments
• Work with single, clear implementation path

How to Use the Skill

**IMPORTANT**: This is a PHASED approach. Complete each phase BEFORE moving to the next.

Phase 1: Initial Setup

**Actions:** 1. Create `.plans/[feature-name]/` directory (in current project directory) 2. Copy `assets/plan-template.md` to `.plans/[feature-name]/plan.md` 3. Create `.plans/[feature-name]/tasks/` directory for task files 4. Replace `[Feature Name]` with your feature name in plan.md 5. Fill in basic overview and context 6. Create Research section with:

• Goal
• Context
• Strategy Proposals (leave empty for now)
• **Leave "Selected Approach" EMPTY**

7. Register phases 1-4 using TaskCreate (native task system):

TaskCreate: subject="Phase 1: Setup template with Research section", activeForm="Setting up plan template"
TaskCreate: subject="Phase 2: Conduct research and iterate with user", activeForm="Researching codebase"
TaskCreate: subject="Phase 3: Finalize selected approach", activeForm="Finalizing approach"
TaskCreate: subject="Phase 4: Create implementation tasks (T01-T0N)", activeForm="Creating implementation tasks"

**Mark Phase 1 as completed via TaskUpdate (status: completed)**

**Output**: Skeleton plan document with Research section defined and native tasks created for phases 1-4

---

Phase 2: Conduct Research and Iterate with User

**Research Process (Iterative):** 1. **Explore codebase**: Read relevant files, find similar patterns 2. **Document findings incrementally**: Add to "Key Findings" as you discover 3. **Identify 2-3 approach options**: Add to "Strategy Proposals" section 4. **ITERATE with user on EACH proposal**:

• Present each proposal with trade-offs (pros/cons)
• Use `AskUserQuestion` to clarify requirements and constraints
• **User may correct assumptions** - update research based on feedback
• Refine understanding through questions (typically 3-5 questions, but quality over quantity)
• **If user strongly prefers one approach early**, you may skip detailed discussion of remaining options

5. **Proactively ask if research is complete**: Once you've explored all options and answered clarifying questions, explicitly ask: "Are you ready to select an approach?"

**CRITICAL**:

• This is an ITERATIVE process - expect back-and-forth discussion on each proposal
• Use AskUserQuestion frequently to refine understanding
• Don't wait for user to say research is done - ASK them proactively

**Mark Phase 2 as in_progress via TaskUpdate when starting, completed when user confirms research is complete**

**Output**: Research with 2-3 Strategy Proposals documented and reviewed with user

---

Phase 3: Finalize Selected Approach

**Actions:** 1. **Ask the user to select an approach** using AskUserQuestion (present the 2-3 researched approaches as formal selection options) 2. **Once user confirms their selection**, fill "Selected Approach" section with:

• **Decision**: Which approach was selected (must match user's confirmed preference)
• **Rationale**: Why this approach was chosen over alternatives
• **Key Findings**: Summarize important discoveries from research
• **Implementation Plan**: High-level steps (5-7 bullet points)

3. Mark all research action items as [x] completed 4. Change research status to ✅ **Completed** 5. Update Progress Summary to show research complete

**Mark Phase 3 as in_progress via TaskUpdate when starting, completed once Selected Approach section is fully documented**

**Output**: Research fully documented with clear decision and rationale

---

Phase 4: Create Implementation Tasks (ONLY AFTER Phase 1-3 Complete)

**IMPORTANT**: Before creating tasks, read `references/task-planning-guide.md` to understand:

• How to break down work into appropriate task sizes
• Task file structure and required sections
• Best practices for defining clear requirements and action items
• How to set proper dependencies between tasks

**Actions:** **NOW create T01, T02, T03, ...T0N** as separate files in `.plans/[feature-name]/tasks/` based on selected approach

• Number of tasks depends on complexity (simple: 1-2, medium: 3-5, complex: 5+)
• Break down into manageable chunks (2-5 days each)

**Step-by-Step: Creating a Task File**

For each task you need to create:

1. **Copy the template**:

   cp [path-to-task-template.md] .plans/[feature-name]/tasks/T01.md

2. **Update task header**: Replace `T0X` with actual task number (T01, T02, etc.) 3. **Fill in core sections**:

• Goal: One clear, measurable objective
• Context: How it relates to the feature and selected approach
• Requirements: Detailed specifications with implementation steps
• Action Items: Specific checkboxes for work to comple