structured-plan-mode

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:
7. Goal
8. Context
9. Strategy Proposals (leave empty for now)
10. Leave "Selected Approach" EMPTY
11. 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:
5. Present each proposal with trade-offs (pros/cons)
6. Use AskUserQuestion to clarify requirements and constraints
7. User may correct assumptions - update research based on feedback
8. Refine understanding through questions (typically 3-5 questions, but quality over quantity)
9. If user strongly prefers one approach early, you may skip detailed discussion of remaining options
10. 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:
3. Decision: Which approach was selected (must match user's confirmed preference)
4. Rationale: Why this approach was chosen over alternatives
5. Key Findings: Summarize important discoveries from research
6. Implementation Plan: High-level steps (5-7 bullet points)
7. Mark all research action items as [x] completed
8. Change research status to ✅ Completed
9. 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:

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

1. Update task header: Replace T0X with actual task number (T01, T02, etc.)
2. Fill in core sections:
3. Goal: One clear, measurable objective
4. Context: How it relates to the feature and selected approach
5. Requirements: Detailed specifications with implementation steps
6. Action Items: Specific checkboxes for work to complete
7. Update metadata: Set Status (🟡 Planned), Effort (Small/Medium/Large), Blocked By
8. Add to Progress Summary: Update plan.md with link: - [ ] [T01: Task Name](tasks/T01.md) - Status: 🟡 Planned
9. Register in native task system: For each task file, call TaskCreate:

`` TaskCreate: subject="T01: [Task Name]", description="[Goal from task file]", activeForm="Implementing [task name]" ` If tasks have dependencies, use TaskUpdate to set addBlockedBy` relationships matching the plan.

Mark Phase 4 as completed via TaskUpdate

Output: Complete task breakdown (T01.md - T0N.md files) in tasks/ folder, all linked from plan.md Progress Summary, all registered as native tasks

Phase 5: Working with Tasks (Implementation)

Note: Phase 5 tasks are tracked in task files, plan.md, AND the native task system via TaskUpdate.

IMPORTANT: Before starting work on ANY task, read references/task-planning-guide.md for:

• Task structure guidance and best practices
• How to maintain task files during execution
• Examples of effective task documentation
• Common pitfalls to avoid

When to consult task-planning-guide.md:

• Before starting a new task (every time)
• When unclear about task file structure or what to document
• When encountering challenges during task execution
• When adding new tasks mid-implementation

Task Execution Discipline

CRITICAL RULE: Work on ONE task at a time. Do NOT start the next task until the current task is FULLY completed.

Task Status Flow:

1. 🟡 Planned → Task created but not started
2. 🟢 In Progress → Currently working on this task (only ONE task should be in this state)
3. ✅ Completed → All action items done, both locations updated, Execution Summary filled
4. 🔴 Blocked → Cannot proceed due to dependency or external issue (move to next task until unblocked)

Task Lifecycle: Step-by-Step

Starting a Task:

1. Read references/task-planning-guide.md - Review relevant sections before beginning work
2. Choose next task from plan.md Progress Summary (respecting dependencies)
3. Update status to 🟢 In Progress in THREE places:
4. Task file metadata: Status: 🟢 In Progress
5. plan.md Progress Summary: - [ ] [T01: Task Name](tasks/T01.md) - Status: 🟢 In Progress
6. Native task system: TaskUpdate: taskId=[id], status=in_progress

During Task Execution: 4.