PLAN.md

IMPORTANT: YOU MUST FOLLOW BELOW TEMPLATE ON PLANNING MODE

plan.md

Task Overview

Objective

[Clear, single-sentence description of what needs to be accomplished]

Type

[debugging | implementation | refactoring | architecture | optimization | migration | research]

Scope

[Specific boundaries of what is included and excluded from this task]

Context Analysis

Current State

[Description of existing codebase/system state relevant to the task]

Target State

[Description of desired end state after task completion]

Constraints

• Technical: [language versions, dependencies, performance requirements]
• Structural: [existing architecture patterns, code conventions]
• Functional: [must maintain compatibility, specific APIs to use/avoid]

Task-Specific Analysis

Debugging

Problem Symptoms:

• [Observable behavior/error]
• [When it occurs]
• [Frequency/conditions]

Hypothesis:

1. [Potential cause]: [Why this might be the issue]
2. [Potential cause]: [Why this might be the issue]

Investigation Path:

• [Where to look first]
• [What to test]
• [How to isolate]

Implementation

Feature Requirements:

• Core: [Must-have functionality]
• Extended: [Additional capabilities]

Integration Points:

• [Existing system/API to connect with]
• [Data flow direction and format]

New Components:

• [Component name]: [Purpose and responsibility]
• [Component name]: [Purpose and responsibility]

Architecture

Design Decisions:

• Pattern: [Pattern choice and rationale]
• Structure: [How components will be organized]
• Communication: [How components will interact]

Scalability Considerations:

• [Current load requirements]
• [Future growth vectors]
• [Bottleneck mitigation]

Trade-offs:

• [Option A] vs [Option B]: [Decision and reasoning]

Refactoring

Code Smells Identified:

• [Issue]: [Why it needs refactoring]
• [Issue]: [Why it needs refactoring]

Refactoring Strategy:

• [Technique]: [How it improves the code]
• [Technique]: [How it improves the code]

Preservation Requirements:

• [What behavior must remain unchanged]
• [What interfaces must stay compatible]

Optimization

Performance Baseline:

• Current Metrics: [Measured performance data]
• Bottlenecks: [Identified slow points]

Optimization Targets:

• [Metric]: [Current] -> [Target]
• [Metric]: [Current] -> [Target]

Optimization Approaches:

• [Technique]: [Expected improvement]
• [Technique]: [Expected improvement]

Migration

Source System:

• Technology: [Current stack/version]
• Data Structure: [How data is organized]
• Dependencies: [What relies on current system]

Target System:

• Technology: [New stack/version]
• Data Structure: [How data will be organized]
• Benefits: [Why migrating]

Migration Strategy:

• [Phase]: [What gets migrated]
• Rollback Plan: [How to revert if needed]

Research

Knowledge Gaps:

• [What needs to be understood]
• [Technologies to evaluate]

Research Questions:

1. [Specific question to answer]
2. [Specific question to answer]

Evaluation Criteria:

• [How to measure/compare options]
• [Decision factors]

Expected Deliverables:

• [Documentation/POC/Recommendation]

Technical Breakdown

Components Affected

1. [Component/Module/File path]: [Brief description of changes needed]
2. [Component/Module/File path]: [Brief description of changes needed]

Dependencies Map

[Component A] -> [Component B]: [Dependency relationship] [Component B] -> [Component C]: [Dependency relationship]

Risk Assessment

• High: [Critical areas that could break existing functionality]
• Medium: [Areas requiring careful attention but manageable]
• Low: [Routine changes with minimal risk]

Implementation Strategy

Approach

[High-level strategy: bottom-up, top-down, parallel development, iterative refinement]

Order of Operations

Phase 1: [Foundation/Prerequisites] Phase 2: [Core Implementation] Phase 3: [Integration/Connection] Phase 4: [Verification/Cleanup]

Execution Steps

Phase 1: [Phase Name]

1.1 Task: [Specific action] - Input: [What's needed to start] - Action: [Exact steps to perform] - Output: [What will be produced] - Validation: [How to verify completion]

1.2 Task: [Specific action] - Input: [What's needed to start] - Action: [Exact steps to perform] - Output: [What will be produced] - Validation: [How to verify completion]

Phase 2: [Phase Name]

2.1 Task: [Specific action] - Input: [What's needed to start] - Action: [Exact steps to perform] - Output: [What will be produced] - Validation: [How to verify completion]

Phase 3: [Phase Name]

3.1 Task: [Specific action] - Input: [What's needed to start] - Action: [Exact steps to perform] - Output: [What will be produced] - Validation: [How to verify completion]

Phase 4: [Phase Name]

4.1 Task: [Specific action] - Input: [What's needed to start] - Action: [Exact steps to perform] - Output: [What will be produced] - Validation: [How to verify completion]

Execution Guidelines

Critical Checkpoints

After Phase 1: [What must be verified before proceeding] After Phase 2: [What must be verified before proceeding] After Phase 3: [What must be verified before proceeding]

Rollback Points

Phase 1: [How to undo if needed] Phase 2: [How to undo if needed] Phase 3: [How to undo if needed]

Decision Trees

If [condition] at [phase.step]: -> Then: [action path A] -> Else: [action path B]

Validation Criteria

Acceptance Tests

1. [Test scenario]: [Expected outcome]
2. [Test scenario]: [Expected outcome]
3. [Test scenario]: [Expected outcome]

Success Metrics

• Functional: [What must work correctly]
• Performance: [Measurable improvements if applicable]
• Quality: [Code standards met, no regressions]

Definition of Done

Core Requirements

• All execution steps completed successfully
• Target state achieved as specified
• All acceptance tests passing
• Success metrics met or exceeded

Code Quality

• Code follows established patterns and conventions
• No commented-out code or debug statements remain
• Error handling implemented for edge cases
• Code is readable and self-documenting where possible

Testing

• Unit tests written/updated for new/modified code
• Integration tests passing
• Manual testing completed for user-facing changes
• No regression in existing functionality

Documentation

• Code comments added for complex logic
• README updated if applicable
• API documentation updated if interfaces changed
• Configuration changes documented

Cleanup

• Temporary files/code removed
• Unused imports/dependencies removed
• Build artifacts cleaned
• Development/debug configurations reverted

Final Verification

• Solution works in clean environment
• No unintended side effects observed
• Performance impact acceptable
• Security considerations addressed

Task-Specific Completion

Debugging

• Root cause identified and documented
• Fix applied and tested
• Cannot reproduce original issue
• Related issues prevented

Implementation

• All feature requirements implemented
• Integration points connected and tested
• Edge cases handled
• Feature usable end-to-end

Architecture

• Design patterns consistently applied
• Component interfaces defined and stable
• Scalability goals achievable
• Technical debt minimized

Refactoring

• Code structure improved without behavior changes
• Test coverage maintained or improved
• Performance metrics equal or better
• Code complexity reduced

Optimization

• Performance targets achieved
• Benchmarks documented
• No functional regressions
• Resource usage improved

Migration

• Data successfully migrated and verified
• All functionality working in new system
• Rollback tested and documented
• Deprecation notices added where needed

Research

• All research questions answered
• Recommendations documented with rationale
• Proof of concept validated if applicable
• Decision matrix completed

State Preservation

Key Decisions

• Decision: [What was decided] Reasoning: [Why this choice] Impact: [How it affects other components]

Code Patterns

• Pattern: [Name/Description] Location: [Where to apply] Purpose: [Why chosen] Example: [Brief code structure]

Important Context

[Critical information for execution phase]

• [File locations and naming conventions]
• [Variable names and their purposes]
• [Key functions/methods to use or avoid]

Expected Challenges

• Challenge: [Potential issue during execution] Mitigation: [How to handle if encountered]

Notes

Assumptions

[Assumptions made during planning that execution should verify]

Out of Scope

[Explicitly what NOT to do during execution]

Future Considerations

[Items for potential follow-up tasks]

Template Instructions

1. Set Task Type in overview section
2. Use ONLY the matching Task-Specific Analysis section
3. Use ONLY the matching Task-Specific Completion checklist
4. Remove all other task-specific sections and these instructions
5. Adjust phase names and execution steps based on task complexity
6. Add/remove phases as needed (typically 3-5 phases work best)