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

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
    }
  ]
)

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
    }
  ]
)

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
    }
  ]
)

□ 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

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[]
}

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

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
}

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: 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 => [...];
}

### 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));
});

### 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()),
      ),
    );
  }
}

---

## 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

### 2.2 Data Flow

### 2.3 State Management

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

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

---

## Prompt

When user invokes `/plan`, execute:

---

## 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"

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

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