implement-plan

Implement Plan

You are tasked with implementing an approved technical plan from thoughts/shared/plans/. These plans contain phases with specific changes and success criteria.

Getting Started

When given a plan path:

Step 1: Extract Plan Context Efficiently

For large plans (most plans), use the dex:plan-extractor agent first:

Task(
  subagent_type: "dex:plan-extractor",
  prompt: "Extract implementation context from: {plan_path}.
           Identify the current phase to implement and return discoveries
           from previous phases, current phase details, and files to modify."
)

The dex:plan-extractor agent will return a condensed summary (~2,000-5,000 tokens) containing:

• Plan overview and completion status
• Discoveries from all completed phases
• Current phase details (overview, files to modify, success criteria)
• List of files the implementer should read

Only read the full plan directly when:

• Plan is small (<300 lines)
• You need to understand overall architecture
• Validating plan completeness after implementation

Step 2: Read Referenced Files

After receiving the dex:plan-extractor summary:

• Read the files listed in "Files Referenced (for implementer to read)"
• Read files fully - never use limit/offset parameters, you need complete context
• Think deeply about how the pieces fit together

Step 3: Create Implementation Todo List

Immediately create a todo list with:

• Each file that needs to be created or modified (from the extraction summary)
• Group files by phase if the plan has multiple phases
• Include the specific change description for each file

Step 4: Begin Implementation

Start implementing if you understand what needs to be done.

If no plan path provided, ask for one.

Implementation Philosophy

Plans are carefully designed, but reality can be messy. Your job is to:

• Follow the plan's intent while adapting to what you find
• Implement each phase fully before moving to the next
• Update function docstrings when changing function signatures or behavior
• Verify your work makes sense in the broader codebase context
• Update checkboxes in the plan as you complete sections

When things don't match the plan exactly, think about why and communicate clearly. The plan is your guide, but your judgment matters too.

Always Update Documentation:

• Function Docstrings: When changing function signatures, always update the docstring to reflect new parameters
• Type Annotations: Ensure all new parameters have proper type hints
• Args Section: Update the Args section in docstrings when adding parameters
• Examples: Update any code examples in docstrings to use new patterns

If you encounter a mismatch:

• STOP and think deeply about why the plan can't be followed
• Present the issue clearly with what you expected vs what you found

Phase-by-Phase Implementation Workflow

Phase Implementation Pattern:

1. Review Previous Discoveries:

   • Read all "Discoveries and Notable Information" sections from completed phases
   • Note any constraints, workarounds, or patterns that affect current phase

2. Setup and Understanding:

   • Mark phase as in_progress in your tracking
   • Read all relevant existing code thoroughly

3. Implementation:

   • Create/modify files as specified in the plan
   • Follow established patterns from similar implementations
   • Handle edge cases and real-world discrepancies from plan

4. Pre-Verification Checkpoint: Before running any verification commands:

   a) Report changes to the developer:

   ## Changes Completed in Phase [N]
   
   **Files Modified:**
   - `path/to/file1` - [brief description of changes]
   
   **Files Created:**
   - `path/to/new_file` - [brief description]
   

   b) Track each verification command in your todo list before running them.

   c) Report commands about to run:

   ## Verification Commands
   
   I will now run the following verification commands (tracked in todo list above):
   1. Type checking on modified files
   2. Unit tests for related components
   3. Linting
   
   Proceeding with verification...
   

5. Verification and Testing:

   • Run each verification command, marking it as in_progress then completed in your tracking
   • Test functionality manually if needed
   • Fix any issues discovered
   • Update plan with checkmarks for completed items

6. Document Discoveries:

   • Update the "Discoveries and Notable Information" section in the plan
   • Document any unexpected findings, constraints, or patterns discovered

7. Documentation and Commit:

   • Update plan file to reflect actual implementations
   • Mark phase as completed in your tracking
   • Prompt user to commit changes with the commit skill

8. Pause for User Verification and Context Management:

   • Present completed work summary and automated verification results
   • Display Manual Verifications: Extract and clearly present ALL manual verification items from the current phase's "Manual Verification" section in the plan. Format them as a checklist the user can work through:

     ## Phase [N] Complete
     
     **Automated verification**: All [X] checks passed.
     
     **Manual verification required before proceeding:**
     - [ ] [Manual verification item 1 from plan]
     - [ ] [Manual verification item 2 from plan]
     - [ ] [Manual verification item N from plan]
     
     Please complete the manual verifications above, then run the commit skill to commit these changes before proceeding.
     

   • If the phase has no manual verification items, note that explicitly: "No manual verification required for this phase."
   • Wait for user confirmation that manual verifications pass before proceeding to the next phase
   • After user commits, prompt for context clearing if needed

Automated Verification Commands:

Run verification commands from repository root:

• Type checking on changed files: Run your project's type checker on the specific changed files
• Unit tests for changed components: Run your project's test suite for relevant test files
• Integration tests if applicable: Run your project's integration test suite
• Linting: Run your project's linter
• Full type checking: Run type checker on full codebase
• Full test suite: Run all tests
• Application startup: Verify the application starts without errors

Manual Verification (prompt user to test):

• Extract the manual verification items from the current phase's success criteria in the plan
• Present them as a clear checklist in the phase completion summary (step 8)
• Wait for user confirmation that all manual checks pass before proceeding

Progress Updates:

• Fix any issues before proceeding to the next phase
• Update checkboxes in the plan file using Edit tool (change - [ ] to - [x])
• Update the "Discoveries and Notable Information" section with findings
• Update your tracking to mark current phase as completed
• Document any changes made that differ from the original plan

Documenting Discoveries and Notable Information

During each phase implementation, you MUST update the "Discoveries and Notable Information" section in the plan file.

What to Document:

Technical Discoveries:

• Unexpected Code Patterns: Patterns different from what was planned
• Hidden Dependencies: Dependencies not obvious from initial research
• Performance Constraints: Bottlenecks or optimization opportunities
• Integration Challenges: Difficulties integrating with existing systems

Implementation Adaptations:

• Workarounds Implemented: Solutions for issues not covered in the plan
• Pattern Deviations: When and why you deviated from established patterns
• Type System Issues: Complex typing scenarios requiring special handling
• Configuration Discoveries: New configuration requirements

Future Considerations:

• Technical Debt Identified: Areas needing future refactoring
• Refactoring Opportunities: Code that could be improved
• Edge Cases: Edge cases handled that weren't in the plan
• Testing Insights: Testing patterns that worked well

Documentation Format:

### Discoveries and Notable Information

**Technical Discoveries:**
- Found that [specific component] uses [pattern] instead of expected [pattern] (file:123)

**Implementation Adaptations:**
- Had to use [workaround] because [constraint]

**Future Considerations:**
- [Component] could benefit from refactoring in future phases

Reading Previous Discoveries

Before starting implementation of any phase, you MUST actively read and incorporate discoveries from all previous phases.

How to Use Previous Discoveries:

At Phase Start:

The dex:plan-extractor agent handles this automatically. From the extracted discoveries:

1. Identify patterns and constraints that affect your current work
2. Note any workarounds that should be applied to similar situations
3. Understand technical debt that may impact your implementation approach

During Implementation:

• Apply discovered patterns rather than rediscovering them
• Use established workarounds for known constraints
• Follow naming conventions discovered in previous phases
• Leverage existing configurations and setup patterns

If You Get Stuck

When something isn't working as expected:

• First, make sure you've read and understood all the relevant code
• Consider if the codebase has evolved since the plan was written
• Present the mismatch clearly and ask for guidance

Use sub-tasks sparingly - mainly for targeted debugging or exploring unfamiliar territory.

Resuming Work

If the plan has existing checkmarks:

• Use the dex:plan-extractor agent to efficiently get all discoveries and identify the current phase
• Trust that completed work is done but understand the context and learnings
• Pick up from the first unchecked item identified by the extractor
• Apply patterns and workarounds discovered in previous phases
• Verify previous work only if something seems off

Remember: You're implementing a solution, not just checking boxes. Keep the end goal in mind and maintain forward momentum.