Phase Elaboration Skill

Elaborate a single phase from a high-level migration plan into a complete, self-contained implementation plan. The plan should contain all background context needed for implementation.

When to Use

• User says "elaborate phase", "elaborate phase 0", "elaborate phase 1", etc.
• User wants to create a detailed implementation plan for a specific migration phase
• User says "phase elaboration" or "detail phase N"
• After implementing a phase, when ready to elaborate the next one

Critical Constraints

NEVER:

• Modify any source code files
• Implement any part of the plan
• Add backward compatibility to the plan (unless a cleanup phase explicitly removes it)
• Add fallback mechanisms that hide bugs
• Add deprecation notes, stubs, warnings
• Include rollback mechanisms
• Add stakeholder sections or PR breakdowns
• Elaborate multiple phases at once - one phase per invocation
• Make assumptions about codebase state without verifying
• Read previous Phase#.md files unless you have a specific question that requires looking up a detail

ALWAYS:

• Assess current codebase state with subagents FIRST
• Write output to the plan directory (e.g., {plan_dir}/Phase#.md)
• Run /dry-walkthrough on the written Phase#.md to validate
• Make the plan self-contained with all background context needed
• Include verification commands and success criteria
• Report findings to terminal output
• Update the master plan if dry walkthrough reveals issues affecting subsequent phases

Plan Directory Structure

All plans live in a dedicated directory:

{plan_directory}/
├── {master_plan_name}.md    # Unique name (e.g., feature_migration_plan.md)
├── Phase0.md                # Elaborated phase 0 (if exists)
├── Phase1.md                # Elaborated phase 1 (if exists)
├── Phase2.md                # etc.
└── ...

• Master plan: Has a unique descriptive name, contains the high-level multi-phase plan
• Phase plans: All named Phase#.md, contain detailed implementation instructions

Understanding Phase Types

First Phase (Phase 0 or Phase 1)

When elaborating the first phase:

• No previous phase .md files exist in the directory
• No previous phases have been implemented
• Assess the current (original) state of the codebase
• The master plan describes the starting state

User message example:

Here's the plan directory: {plan_dir}/ with master plan {master_plan}.md. Elaborate phase 0.

Subsequent Phases (Phase 1, 2, 3, ...)

When elaborating subsequent phases:

• Previous phases have been implemented
• The codebase has changed since the master plan was written
• Must assess the CURRENT state (post-implementation)
• Do NOT read previous Phase#.md files - assess from codebase directly

User message example:

Same directory. Phase 0 is implemented. Elaborate phase 1.

Workflow

Step 1: Parse User Request

Extract from user message:

1. Phase number to elaborate (0, 1, 2, etc.)
2. Plan directory containing the master plan and phase plans
3. Master plan filename (the unique-named high-level plan)
4. Is this the first phase? (no existing Phase#.md files)

Step 2: Read the Master Plan

Load and understand:

• Master plan: The complete high-level migration plan
• Identify the specific phase to elaborate
• Understand dependencies on previous phases
• Note files and systems affected

IMPORTANT: Do NOT read previous Phase#.md files. They exist in the directory but reading them wastes context. Only look up a specific detail from a previous phase if you encounter a concrete question during assessment that cannot be answered from the codebase itself.

Step 3: Assess Current Codebase State

Launch parallel Explore subagents to understand the current state:

Subagent 1: Affected Files Assessment
  - Read all files that will be touched by this phase
  - Document their current state (structure, dependencies, imports)
  - Identify any deviations from what the master plan expected

Subagent 2: Dependency Analysis
  - Trace imports and dependencies for affected files
  - Identify all consumers of code being moved/changed
  - Map the dependency graph

Subagent 3: Test Coverage
  - Find tests related to affected code
  - Understand what test changes will be needed
  - Identify any integration tests that may break

Subagent 4: Pattern Discovery
  - Search for similar patterns in the codebase
  - Identify conventions that should be followed
  - Note any existing utilities that should be reused

Subagent 5: State Verification (for subsequent phases)
  - Verify previous phases were implemented correctly
  - Check that expected files/directories exist
  - Confirm imports were updated as planned

Output assessment summary to terminal:

## Codebase Assessment Complete

### Current State
- {component}: {current status}
- {file}: {current location and state}

### Key Findings
- {finding that affects the plan}
- {deviation from master plan expectations}

### Dependencies Mapped
- {affected file} imports: {list of imports}
- {affected file} imported by: {list of consumers}

Step 4: Write Elaborated Phase Plan

Create a complete implementation plan at the output location. The plan should include all necessary background context.

Plan Structure:

markdown
1# Phase {N}: {Phase Name}
2
3## Executive Summary
4
5{2-3 sentences describing what this phase accomplishes and why}
6
7{Any critical changes from the original master plan, with rationale}
8
9---
10
11## Prerequisites
12
13Before starting Phase {N}:
14
15- [ ] {Prerequisite check}
16- [ ] {Required state verification}
17- [ ] Previous phases implemented
18- [ ] All tests pass: run the project's test suite
19- [ ] No uncommitted changes: `git status`
20
21---
22
23## Background Context
24
25{Everything the implementer needs to know that isn't in other sections}
26
27### Relevant Code Locations
28
29| Component | Current Location | Purpose |
30|-----------|------------------|---------|
31| {component} | {path} | {brief description} |
32
33### Key Dependencies
34
35{Description of important dependencies and why they matter}
36
37---
38
39## Phase {N} Tasks
40
41### Task {N}.1: {Task Name}
42
43{Description of what this task accomplishes}
44
45**Files to Modify:**
46- `{path}`: {what changes}
47
48**Implementation Steps:**
491. {Specific action with details}
502. {Specific action with details}
51
52**Verification:**
53```bash
54{command to verify task completion}

Task {N}.2: {Task Name}

{Same structure as above}

Verification Checklist

After completing Phase {N}, verify:

• {Verification item}
• Run linting and formatting checks
• All tests pass: run the project's test suite

Files Created/Modified in Phase {N}

What Phase {N} Does NOT Do

Phase {N} explicitly avoids:

1. {Thing that might be expected but isn't done here}
2. {Clarification of scope boundaries}

Implementation Guidelines

{Project-specific guidelines relevant to this phase}

1. No useless comments - Do not use the codebase as a notepad
2. No backward compatibility code - unless cleanup is explicitly planned
3. Clean cuts only - Move code completely, update all imports atomically

Next Phase Preview

Phase {N+1}: {Name}

{Brief description of what comes next, so implementer understands boundaries}

### Step 5: Dry Walkthrough

Invoke `/dry-walkthrough` on the `Phase{N}.md` file just written.

### Step 6: Update Master Plan (If Required)

If the dry walkthrough reveals issues that affect subsequent phases:
1. Update the master plan to reflect corrections
2. Report changes to terminal

### Step 7: Report to Terminal

After writing the plan, output summary:

Phase Elaboration Complete

Phase: {N} - {Phase Name} Plan Directory: {plan_directory} Output: Phase{N}.md Status: {READY / REVISED from master plan}

Changes from Master Plan

{List any modifications made during elaboration}

• {change}: {reason}

Master Plan Updates

{If master plan was updated due to downstream impact}

• {subsequent phase}: {what was changed} OR
• No updates required

Key Implementation Notes

• {Important note for implementer}
• {Gotcha to watch out for}

Ready for implementation.

## Output Location

Phase plans are written to the same directory as the master plan:

{plan_directory}/Phase{N}.md

Where `{N}` is replaced with the phase number (0, 1, 2, etc.).

Example directory after elaborating phases 0 and 1:

/path/to/plans/ ├── feature_migration_plan.md # Master plan ├── Phase0.md # Elaborated phase 0 └── Phase1.md # Elaborated phase 1

## Backward Compatibility Policy

**Backward compatibility code is only acceptable when:**
1. There is an explicit cleanup phase in the migration plan
2. The cleanup phase explicitly lists removal of the compatibility code
3. The compatibility code is clearly marked for removal

**If not planned for cleanup, do NOT add:**
- Import shims or re-exports for old paths
- Deprecation warnings
- Compatibility adapters
- Fallback mechanisms

## Example Usage

### First Phase Example

**User:** "Here's the plan directory: /path/to/plans/ with master plan feature_migration_plan.md. Elaborate phase 0."

**Process:**
1. Read master plan from `/path/to/plans/feature_migration_plan.md`
2. No existing `Phase#.md` files (first phase)
3. Launch subagents to assess current codebase state
4. Write elaborated plan to `/path/to/plans/Phase0.md`
5. Run `/dry-walkthrough` on `Phase0.md`
6. Update master plan if dry walkthrough reveals downstream issues
7. Report findings and status

### Subsequent Phase Example

**User:** "Same directory. Phase 0 is implemented. Elaborate phase 1."

**Process:**
1. Read master plan from `/path/to/plans/feature_migration_plan.md`
2. Launch subagents to assess:
   - Current state (post Phase 0 implementation)
   - Files touched by Phase 1
   - Dependencies and consumers
3. Write elaborated plan to `/path/to/plans/Phase1.md`
4. Run `/dry-walkthrough` on `Phase1.md`
5. Update master plan if dry walkthrough reveals downstream issues
6. Report findings and status

## Related Skills

- **`/dry-walkthrough`** - Used internally for validation
- **`/make-plan`** - Creates new plans (this skill elaborates existing ones)
- **`/implement-worktree`** - Implements elaborated plans