Plan

Plan Skill

Creates detailed implementation plan from validated research.

Purpose

The Plan skill transforms validated research into an actionable implementation plan:

┌─────────────────────────────────────────────────────────────────────────┐
│                         PLANNING FRAMEWORK                               │
├─────────────────────────────────────────────────────────────────────────┤
│                                                                         │
│  ┌─────────────┐   ┌─────────────┐   ┌─────────────┐   ┌────────────┐  │
│  │  RESEARCH   │──▶│  ARCHITECT  │──▶│    TASK     │──▶│   VERIFY   │  │
│  │   INPUT     │   │  DECISIONS  │   │  BREAKDOWN  │   │    PLAN    │  │
│  └─────────────┘   └─────────────┘   └─────────────┘   └────────────┘  │
│        │                 │                  │                │         │
│        ▼                 ▼                  ▼                ▼         │
│   • Requirements    • Approach        • Atomic tasks    • Traceability│
│   • Codebase map    • Patterns        • Dependencies    • Completeness│
│   • Risks           • Components      • Sequence        • Feasibility │
│                                                                        │
└────────────────────────────────────────────────────────────────────────┘

Agent Compatibility

• AskUserQuestion: use the tool in Claude Code; in Codex CLI, ask the user directly and record the answer.
• OUTPUT_DIR: .claude/output for Claude Code, .codex/output for Codex CLI.

Planning Phases

Phase 1: Architectural Decisions

Before task breakdown, make key architectural decisions:

Phase 1.5: MANDATORY Edge Case Review

CRITICAL: This phase is BLOCKING. Cannot proceed to Phase 2 until all edge cases are clarified.

Before proceeding to task breakdown:

1. List all edge cases discovered during planning:
   • Empty states
   • Error states
   • Boundary conditions
   • Null/zero values
   • Missing data scenarios

P-Checkpoints (Plan Questions)

P1: Edge Case Behavior For each edge case without explicit PRD guidance:

AskUserQuestion(
  questions: [
    {
      question: "Edge case: '{scenario}'. What should happen?",
      header: "Edge Case",
      options: [
        { label: "Show empty state", description: "Display 'No data' or similar message" },
        { label: "Show default value", description: "Display '--' or 0" },
        { label: "Hide element", description: "Don't render the component at all" },
        { label: "Show error", description: "Display error message to user" }
      ],
      multiSelect: false
    }
  ]
)

P2: Architecture Decision For each architectural choice with trade-offs:

AskUserQuestion(
  questions: [
    {
      question: "For '{component}', should we use '{Option A}' or '{Option B}'?",
      header: "Architecture",
      options: [
        { label: "Option A", description: "Benefits: X. Trade-off: Y" },
        { label: "Option B", description: "Benefits: Y. Trade-off: X" },
        { label: "Discuss further", description: "Need more context to decide" }
      ],
      multiSelect: false
    }
  ]
)

P3: Scope Boundary When scope is unclear:

AskUserQuestion(
  questions: [
    {
      question: "Should '{feature X}' be included in this implementation?",
      header: "Scope",
      options: [
        { label: "Yes, include", description: "Add to current implementation scope" },
        { label: "No, defer", description: "Create follow-up ticket for later" },
        { label: "Partial", description: "Include basic version only, enhance later" }
      ],
      multiSelect: false
    }
  ]
)

2. Document in plan:

   ## Edge Case Decisions (User Confirmed)
   | Checkpoint | Edge Case | User Decision | Date |
   |------------|-----------|---------------|------|
   | P1 | All items defective | Show "–" | 2024-01-01 |
   | P2 | State management | Use existing controller | 2024-01-01 |
   | P3 | Export feature | Defer to next sprint | 2024-01-01 |
   

Rules:

1. NEVER assume edge case behavior - ASK
2. NEVER proceed with unconfirmed edge cases
3. Document all user decisions with checkpoint ID
4. Each P-checkpoint MUST be resolved before Phase 2

Plan Phase Complete Criteria:

□ All P1 checkpoints resolved (all edge cases have defined behavior)
□ All P2 checkpoints resolved (architecture decisions made)
□ All P3 checkpoints resolved (scope boundaries clear)

Decision Framework:
├── Approach Selection
│   ├── What pattern to follow?
│   ├── Create new vs extend existing?
│   └── Which components to use?
│
├── Data Flow Design
│   ├── API → Repository → Service → Controller → UI
│   └── State management approach
│
├── UI Architecture
│   ├── Screen structure
│   ├── Widget decomposition
│   └── Navigation flow
│
└── Integration Points
    ├── Existing services to use
    ├── New services needed
    └── External dependencies

Phase 2: Task Decomposition

Break implementation into atomic, sequential tasks:

Task Properties

Task {
  id: string              // T1, T2, T3...
  title: string           // Short description
  description: string     // Detailed description
  type: enum {
    model,               // Data models (Equatable + ReturnValue)
    api,                 // API client methods
    repository,          // Repository layer
    service,             // Service layer
    controller,          // StateNotifier controller
    state,               // State class
    screen,              // Screen widget
    widget,              // Reusable widget
    navigation,          // Routing
    test,                // Unit/widget tests
    integration          // Integration/cleanup
  }
  layer: enum {
    data,
    domain,
    application,
    presentation
  }
  files: string[]         // Files to create/modify
  requirements: string[]  // Requirement IDs this addresses
  dependencies: string[]  // Task IDs this depends on
  complexity: enum {
    trivial,             // < 30 min
    low,                 // 30 min - 1 hr
    medium,              // 1-2 hrs
    high                 // 2+ hrs
  }
  risks: string[]
  acceptanceCriteria: string[]
}

Task Ordering Rules

1. Foundation First
   - Models before services
   - Services before controllers
   - Controllers before screens

2. Data Layer → Domain → Application → Presentation
   - Response models (data/)
   - Domain models (domain/)
   - Services & mappers (application/)
   - Controllers & screens (presentation/)

3. Dependencies Respected
   - Task cannot start until dependencies complete
   - No circular dependencies

4. Test Adjacent
   - Unit tests with related code
   - Integration tests after feature complete

Phase 3: File Planning

For each file to create/modify:

File Plan {
  path: string           // Full file path
  action: enum {
    create,              // New file
    modify,              // Existing file
    delete               // Remove file (rare)
  }
  purpose: string        // Why this file
  contentOutline: string // High-level structure
  patterns: string[]     // Patterns to apply (from AGENTS.md)
  references: string[]   // Similar files to reference
}

Phase 4: Test Strategy

Define testing approach:

Test Strategy {
  unitTests: [
    {
      target: string,        // Class/function to test
      scenarios: string[],   // Test scenarios
      mocks: string[]        // Dependencies to mock
    }
  ],
  widgetTests: [
    {
      target: string,        // Widget to test
      interactions: string[] // User interactions to test
    }
  ],
  integrationTests: [
    {
      flow: string,          // User flow to test
      steps: string[]        // Test steps
    }
  ]
}

Task Templates by Type

Model Task (Equatable + ReturnValue)

### Task: Create {ModelName} Response Model

**Type**: model | **Layer**: data | **Complexity**: low

**Files**:
- Create: `lib/src/features/{feature}/data/{model_name}_response.dart`

**Description**:
Create response model for {API endpoint} using Equatable + ReturnValue pattern.

**Implementation**:
```dart
class {ModelName}Response extends Equatable {
  // Properties from API

  const {ModelName}Response({...});

  factory {ModelName}Response.fromJson(Map<String, dynamic> json) {
    return {ModelName}Response(
      // Use ReturnValue for all fields
    );
  }

  Map<String, dynamic> toJson() => {...};

  {ModelName}Response copyWith({...}) => {...};

  @override
  List<Object?> get props => [...];
}

Acceptance Criteria:

• All API fields mapped
• Uses ReturnValue for JSON parsing
• Has copyWith method
• Has props for Equatable

### Controller Task (StateNotifier)

```markdown
### Task: Create {Feature}Controller

**Type**: controller | **Layer**: presentation | **Complexity**: medium

**Files**:
- Create: `lib/src/features/{feature}/presentation/{name}/{name}_controller.dart`
- Create: `lib/src/features/{feature}/presentation/{name}/{name}_state.dart`

**Description**:
Create StateNotifier controller for {feature} screen.

**Implementation Pattern**:
```dart
// State
class {Feature}State {
  final AsyncValue<Data> dataValue;
  // other state properties

  const {Feature}State({...});

  {Feature}State copyWith({...}) => {...};
}

// Controller
class {Feature}Controller extends StateNotifier<{Feature}State> {
  {Feature}Controller({required this.service}) : super(const {Feature}State());

  final {Feature}Service service;

  Future<void> loadData() async {
    state = state.copyWith(dataValue: const AsyncLoading());
    final result = await service.getData();
    result.when(
      success: (data) => state = state.copyWith(dataValue: AsyncData(data)),
      failure: (error) => state = state.copyWith(errorMessage: error.message),
    );
  }
}

// Provider
final {feature}ControllerProvider = StateNotifierProvider<{Feature}Controller, {Feature}State>((ref) {
  return {Feature}Controller(service: ref.read({feature}ServiceProvider));
});

Acceptance Criteria:

• Follows StateNotifier pattern
• Has loading/error/success states
• Provider properly defined

### Screen Task

```markdown
### Task: Create {Feature}Screen

**Type**: screen | **Layer**: presentation | **Complexity**: medium

**Files**:
- Create: `lib/src/features/{feature}/presentation/{name}/{name}_screen.dart`

**Description**:
Create screen widget for {feature}.

**Implementation Pattern**:
```dart
class {Feature}Screen extends ConsumerWidget {
  const {Feature}Screen({super.key});

  static const routeName = '/{feature}';

  @override
  Widget build(BuildContext context, WidgetRef ref) {
    final state = ref.watch({feature}ControllerProvider);

    return Scaffold(
      appBar: AppBarWidget(...),
      body: state.dataValue.when(
        data: (data) => _buildContent(data),
        loading: () => const LoadingWidget(),
        error: (e, _) => ErrorWidget(message: e.toString()),
      ),
    );
  }
}

UI Components (separate widget classes):

• {Feature}Header
• {Feature}Content
• {Feature}Footer

Acceptance Criteria:

• Uses ConsumerWidget
• Handles loading/error/data states
• Uses project styling (TypographyTheme, ColorApp, Gap)
• Separate widget classes (no _buildX methods)

---

## Output Template

Generate `OUTPUT_DIR/plan-{feature}.md`:

```markdown
# Implementation Plan: {Feature Name}

## Metadata
- **Date**: {YYYY-MM-DD}
- **Based On**: research-{feature}.md
- **PRD Reference**: {URL/source}
- **Estimated Tasks**: {count}
- **Complexity**: {low/medium/high}

---

## 1. Executive Summary

### Feature Overview
{Brief description of what will be implemented}

### Scope
- **In Scope**: {what's included}
- **Out of Scope**: {what's not included}

### Key Decisions
| Decision | Choice | Rationale |
|----------|--------|-----------|
| {decision} | {choice} | {why} |

---

## 2. Architecture

### 2.1 Component Diagram

┌─────────────────────────────────────────────────────────┐ │ PRESENTATION │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ Screen │ │ Controller │ │ State │ │ │ └─────────────┘ └─────────────┘ └─────────────┘ │ ├─────────────────────────────────────────────────────────┤ │ APPLICATION │ │ ┌─────────────┐ ┌─────────────┐ │ │ │ Service │ │ Mapper │ │ │ └─────────────┘ └─────────────┘ │ ├─────────────────────────────────────────────────────────┤ │ DOMAIN │ │ ┌─────────────┐ │ │ │ Model │ │ │ └─────────────┘ │ ├─────────────────────────────────────────────────────────┤ │ DATA │ │ ┌─────────────┐ ┌─────────────┐ │ │ │ Response │ │ Repository │ │ │ └─────────────┘ └─────────────┘ │ └─────────────────────────────────────────────────────────┘

### 2.2 Data Flow

API Response ↓ {Feature}Response (data/) ↓ {Feature}Model (domain/) [via Mapper] ↓ {Feature}Service (application/) ↓ {Feature}Controller (presentation/) ↓ {Feature}Screen (presentation/)

### 2.3 State Management

```dart
// State structure
{Feature}State {
  dataValue: AsyncValue<{Model}>
  // other fields
}

3. Task Breakdown

3.1 Task Summary

3.2 Task Sequence

Phase 1: Data Layer
├── T1: Create response models
└── T2: Create/update repository

Phase 2: Domain Layer
└── T3: Create domain models

Phase 3: Application Layer
├── T4: Create mapper
└── T5: Create service

Phase 4: Presentation Layer
├── T6: Create state
├── T7: Create controller
├── T8: Create widgets
└── T9: Create screen

Phase 5: Integration
├── T10: Add navigation
├── T11: Add tests
└── T12: Integration testing

3.3 Detailed Tasks

T1: {Task Title}

Type: {type} | Layer: {layer} | Complexity: {complexity}

Dependencies: {none or task IDs}

Requirements Addressed: R1, R2

Files:

Description: {Detailed description of what to implement}

Implementation Notes:

• {specific guidance}
• {patterns to follow}

Acceptance Criteria:

• {criterion 1}
• {criterion 2}

T2: {Next Task}

...

4. File Inventory

4.1 New Files

4.2 Modified Files

4.3 Reference Files

5. Test Strategy

5.1 Unit Tests

5.2 Widget Tests

5.3 Integration Tests

6. Requirement Traceability

7. Risk Mitigation

8. Checklist Before Implementation

• Research validated (audit passed)
• All requirements traced to tasks
• Dependencies are clear
• File paths verified (no conflicts)
• Patterns match AGENTS.md
• User approved plan

---

## Prompt

When user invokes `/plan`, execute:

I will now create an implementation plan from the validated research.

Prerequisites Check

1. Checking for research file: research-{feature}.md
2. Verifying research was audited and passed

Phase 1: Architectural Decisions

Making key decisions:

• Pattern approach: {decision}
• Data flow: {decision}
• Component structure: {decision}

Phase 2: Task Decomposition

Breaking down implementation into atomic tasks...

[Generate task list with dependencies]

Phase 3: File Planning

Identifying files to create/modify:

• New files: {count}
• Modified files: {count}

Phase 4: Test Strategy

Defining test approach:

• Unit tests: {count}
• Widget tests: {count}
• Integration tests: {count}

Output

[Generate plan-{feature}.md]

Summary

Ready for plan audit? [Proceeding to /audit plan]

---

## Progress Tracking (MANDATORY when called from RPI)

**If this skill is invoked as part of an RPI workflow, you MUST update progress:**

### On Plan Start
```bash
~/.claude/skills/scripts/rpi-progress.sh --phase plan --status in_progress --last "Starting planning" --next "Complete implementation plan"

On Plan Complete (before audit)

~/.claude/skills/scripts/rpi-progress.sh --phase plan --status complete --last "Plan complete" --next "Plan audit"

After Plan Audit Pass

~/.claude/skills/scripts/rpi-progress.sh --audit plan --passed true --score {score} --last "Plan audit passed" --next "Await user approval"

Progress Values

• Plan started: 20%
• Plan complete: 25%
• Plan audit pass: 30%
• User approval: 35%