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:

lib/src/features/{feature}/...

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

lib/src/features/{feature}/data/{name}_response.dart

lib/src/features/{feature}/domain/{name}_model.dart

lib/src/features/{feature}/application/{name}_service.dart

lib/src/features/{feature}/presentation/{name}/{name}_screen.dart

lib/src/features/{feature}/presentation/{name}/{name}_controller.dart

lib/src/features/{feature}/presentation/{name}/{name}_state.dart

4.2 Modified Files

lib/src/routing/app_router.dart

lib/src/services/remote/api/{api}_client.dart

4.3 Reference Files

lib/src/features/{similar}/...

5. Test Strategy

5.1 Unit Tests

test/.../service_test.dart

test/.../controller_test.dart

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%