Instruction file imported from tyrchen/simple-zanzibar (.cursor/rules/isolation_rules/Level4/phased-implementation.mdc). Copyright stays with the author.

description: Phased Implementation for Level 4 Complex System tasks globs: "/level4/", "/implementation/" alwaysApply: false

PHASED IMPLEMENTATION FOR LEVEL 4 TASKS

TL;DR: This document outlines a structured phased implementation approach for Level 4 (Complex System) tasks, ensuring controlled, incremental delivery of complex systems with appropriate verification at each phase.

🔍 PHASED IMPLEMENTATION OVERVIEW

Level 4 Complex System tasks require a controlled, incremental approach to implementation to manage complexity, reduce risk, and ensure quality. This document outlines a phased implementation methodology that divides complex system development into discrete, verifiable phases with clear entry and exit criteria.

flowchart TD
    classDef phase fill:#f9d77e,stroke:#d9b95c,color:#000
    classDef artifact fill:#f4b8c4,stroke:#d498a4,color:#000
    classDef verification fill:#c5e8b7,stroke:#a5c897,color:#000

    Start([Begin Implementation<br>Process]) --> Framework[Establish Implementation<br>Framework]
    Framework --> Plan[Create Phasing<br>Plan]
    Plan --> Foundation[Implement<br>Foundation Phase]
    Foundation --> VerifyF{Foundation<br>Verification}
    VerifyF -->|Pass| Core[Implement<br>Core Phase]
    VerifyF -->|Fail| ReviseF[Revise<br>Foundation]
    ReviseF --> VerifyF

    Core --> VerifyC{Core<br>Verification}
    VerifyC -->|Pass| Extension[Implement<br>Extension Phase]
    VerifyC -->|Fail| ReviseC[Revise<br>Core]
    ReviseC --> VerifyC

    Extension --> VerifyE{Extension<br>Verification}
    VerifyE -->|Pass| Integration[Implement<br>Integration Phase]
    VerifyE -->|Fail| ReviseE[Revise<br>Extension]
    ReviseE --> VerifyE

    Integration --> VerifyI{Integration<br>Verification}
    VerifyI -->|Pass| Finalization[Implement<br>Finalization Phase]
    VerifyI -->|Fail| ReviseI[Revise<br>Integration]
    ReviseI --> VerifyI

    Finalization --> VerifyFin{Finalization<br>Verification}
    VerifyFin -->|Pass| Complete([Implementation<br>Complete])
    VerifyFin -->|Fail| ReviseFin[Revise<br>Finalization]
    ReviseFin --> VerifyFin

    Framework -.-> IF((Implementation<br>Framework))
    Plan -.-> PP((Phasing<br>Plan))
    Foundation -.-> FP((Foundation<br>Phase))
    Core -.-> CP((Core<br>Phase))
    Extension -.-> EP((Extension<br>Phase))
    Integration -.-> IP((Integration<br>Phase))
    Finalization -.-> FiP((Finalization<br>Phase))

    class Start,Complete milestone
    class Framework,Plan,Foundation,Core,Extension,Integration,Finalization,ReviseF,ReviseC,ReviseE,ReviseI,ReviseFin step
    class VerifyF,VerifyC,VerifyE,VerifyI,VerifyFin verification
    class IF,PP,FP,CP,EP,IP,FiP artifact

📋 IMPLEMENTATION PHASING PRINCIPLES

1. Incremental Value Delivery: Each phase delivers tangible, verifiable value.
2. Progressive Complexity: Complexity increases gradually across phases.
3. Risk Mitigation: Early phases address high-risk elements to fail fast if needed.
4. Verification Gates: Each phase has explicit entry and exit criteria.
5. Business Alignment: Phases align with business priorities and user needs.
6. Technical Integrity: Each phase maintains architectural and technical integrity.
7. Continuous Integration: Work is continuously integrated and tested.
8. Knowledge Building: Each phase builds upon knowledge gained in previous phases.
9. Explicit Dependencies: Dependencies between phases are clearly documented.
10. Adaptability: The phasing plan can adapt to new information while maintaining structure.

📋 STANDARD IMPLEMENTATION PHASES

Level 4 Complex System tasks typically follow a five-phase implementation approach:

flowchart LR
    classDef phase fill:#f9d77e,stroke:#d9b95c,color:#000

    P1[1. Foundation<br>Phase] --> P2[2. Core<br>Phase]
    P2 --> P3[3. Extension<br>Phase]
    P3 --> P4[4. Integration<br>Phase]
    P4 --> P5[5. Finalization<br>Phase]

    class P1,P2,P3,P4,P5 phase

Phase 1: Foundation Phase

The Foundation Phase establishes the basic architecture and infrastructure required for the system.

Key Activities:

• Set up development, testing, and deployment environments
• Establish core architectural components and patterns
• Implement database schema and basic data access
• Create skeleton application structure
• Implement authentication and authorization framework
• Establish logging, monitoring, and error handling
• Create basic CI/CD pipeline

Exit Criteria:

• Basic architectural framework is functional
• Environment setup is complete and documented
• Core infrastructure components are in place
• Basic CI/CD pipeline is operational
• Architecture review confirms alignment with design

Phase 2: Core Phase

The Core Phase implements the essential functionality that provides the minimum viable system.

Key Activities:

• Implement core business logic
• Develop primary user flows and interfaces
• Create essential system services
• Implement critical API endpoints
• Develop basic reporting capabilities
• Establish primary integration points
• Create automated tests for core functionality

Exit Criteria:

• Core business functionality is implemented
• Essential user flows are working
• Primary APIs are functional
• Core automated tests are passing
• Business stakeholders verify core functionality

Phase 3: Extension Phase

The Extension Phase adds additional features and capabilities to the core system.

Key Activities:

• Implement secondary business processes
• Add additional user interfaces and features
• Enhance existing functionality based on feedback
• Implement advanced features
• Extend integration capabilities
• Enhance error handling and edge cases
• Expand test coverage

Exit Criteria:

• All planned features are implemented
• Extended functionality is working correctly
• Secondary business processes are functional
• Enhanced features have been validated
• Test coverage meets defined thresholds

Phase 4: Integration Phase

The Integration Phase ensures all components work together properly and integrates with external systems.

Key Activities:

• Perform deep integration testing
• Implement all external system integrations
• Conduct end-to-end testing
• Perform performance and load testing
• Conduct security testing
• Implement any required data migrations
• Verify system behavior under various conditions

Exit Criteria:

• All integrations are working correctly
• End-to-end tests are passing
• Performance meets defined requirements
• Security tests show no critical vulnerabilities
• System handles error conditions gracefully

Phase 5: Finalization Phase

The Finalization Phase prepares the system for production release.

Key Activities:

• Optimize performance
• Conduct user acceptance testing
• Finalize documentation
• Conduct final security review
• Create production deployment plan
• Prepare support materials and training
• Conduct final system review

Exit Criteria:

• All acceptance criteria are met
• Documentation is complete
• User acceptance testing is successful
• Production deployment plan is approved
• Support and maintenance procedures are established

📋 PHASE PLANNING TEMPLATE

For each implementation phase, create a detailed plan using this template:

## [Phase Name] Implementation Plan

### Phase Overview
- **Purpose**: [Brief description of phase purpose]
- **Timeline**: [Start and end dates]
- **Dependencies**: [Dependencies on other phases or external factors]
- **Key Stakeholders**: [List of key stakeholders for this phase]

### Entry Criteria
- [ ] [Criterion 1]
- [ ] [Criterion 2]
- [ ] [Criterion 3]

### Implementation Components
- **Component 1**: [Description]
  - [ ] Task 1.1: [Description]
  - [ ] Task 1.2: [Description]

- **Component 2**: [Description]
  - [ ] Task 2.1: [Description]
  - [ ] Task 2.2: [Description]

### Technical Considerations
- [Key technical considerations for this phase]

### Risk Assessment
- **Risk 1**: [Description]
  - Impact: [High/Medium/Low]
  - Mitigation: [Strategy]

- **Risk 2**: [Description]
  - Impact: [High/Medium/Low]
  - Mitigation: [Strategy]

### Quality Assurance
- [QA approach for this phase]
- [Testing requirements]

### Exit Criteria
- [ ] [Criterion 1]
- [ ] [Criterion 2]
- [ ] [Criterion 3]

### Deliverables
- [List of deliverables for this phase]

📋 PHASE VERIFICATION

Each phase requires formal verification before proceeding to the next phase.

flowchart TD
    classDef activity fill:#f9d77e,stroke:#d9b95c,color:#000
    classDef artifact fill:#f4b8c4,stroke:#d498a4,color:#000
    classDef decision fill:#c5e8b7,stroke:#a5c897,color:#000

    Start([Begin Phase<br>Verification]) --> CodeReview[Conduct Code<br>Review]
    CodeReview --> TestExecution[Execute Automated<br>Tests]
    TestExecution --> QAVerification[Perform QA<br>Verification]
    QAVerification --> ArchReview[Conduct Architecture<br>Review]
    ArchReview --> StakeholderReview[Conduct Stakeholder<br>Review]
    StakeholderReview --> Checklist[Complete Verification<br>Checklist]
    Checklist --> ExitCriteria{All Exit<br>Criteria Met?}
    ExitCriteria -->|Yes| Approval[Obtain Phase<br>Approval]
    ExitCriteria -->|No| Issues[Document<br>Issues]
    Issues --> Remediation[Implement<br>Remediation]
    Remediation --> Retest[Verify<br>Fixes]
    Retest --> ExitCriteria
    Approval --> Complete([Verification<br>Complete])

    CodeReview -.-> CodeReport((Code Review<br>Report))
    TestExecution -.-> TestReport((Test<br>Report))
    QAVerification -.-> QAReport((QA<br>Report))
    ArchReview -.-> ArchReport((Architecture<br>Report))
    StakeholderReview -.-> StakeReport((Stakeholder<br>Report))
    Checklist -.-> CheckDoc((Verification<br>Checklist))

    class Start,Complete milestone
    class CodeReview,TestExecution,QAVerification,ArchReview,StakeholderReview,Checklist,Approval,Issues,Remediation,Retest activity
    class ExitCriteria decision
    class CodeReport,TestReport,QAReport,ArchReport,StakeReport,CheckDoc artifact

Phase Verification Checklist Template

## Phase Verification Checklist

### Implementation Completeness
- [ ] All planned components implemented
- [ ] All tasks marked as complete
- [ ] No outstanding TODOs in code
- [ ] All documentation updated

### Code Quality
- [ ] Code review completed
- [ ] No critical issues found in static analysis
- [ ] Code meets established standards
- [ ] Technical debt documented

### Testing
- [ ] Unit tests completed and passing
- [ ] Integration tests completed and passing
- [ ] End-to-end tests completed and passing
- [ ] Performance testing completed (if applicable)
- [ ] Security testing completed (if applicable)
- [ ] Test coverage meets requirements

### Architecture
- [ ] Implementation follows architectural design
- [ ] No architectural violations introduced
- [ ] Technical patterns correctly implemented
- [ ] Non-functional requirements met

### Stakeholder Verification
- [ ] Business requirements met
- [ ] Stakeholder demo completed
- [ ] Feedback incorporated
- [ ] Acceptance criteria verified

### Risk Assessment
- [ ] All identified risks addressed
- [ ] No new risks introduced
- [ ] Contingency plans in place for known issues

### Exit Criteria
- [ ] All exit criteria met
- [ ] Any exceptions documented and approved
- [ ] Phase signoff obtained from required parties

📋 HANDLING PHASE DEPENDENCIES

flowchart TD
    classDef solid fill:#f9d77e,stroke:#d9b95c,color:#000
    classDef partial fill:#a8d5ff,stroke:#88b5e0,color:#000

    F[Foundation<br>Phase] --> C[Core<br>Phase]
    F --> E[Extension<br>Phase]
    F --> I[Integration<br>Phase]
    F --> FN[Finalization<br>Phase]

    C --> E
    C --> I
    C --> FN

    E --> I
    E --> FN

    I --> FN

    class F,C solid
    class E,I,FN partial

Dependency Management Strategies

1. Vertical Slicing: Implement complete features across all phases for priority functionality.
2. Stubbing and Mocking: Create temporary implementations to allow progress on dependent components.
3. Interface Contracts: Define clear interfaces between components to allow parallel development.
4. Feature Toggles: Implement features but keep them disabled until dependencies are ready.
5. Incremental Integration: Gradually integrate components as they become available.

Dependency Documentation Format

## Implementation Dependencies

### Foundation Phase Dependencies
- **External Dependencies**:
  - Development environment setup
  - Access to source control
  - Access to CI/CD pipeline

### Core Phase Dependencies
- **Foundation Phase Dependencies**:
  - Authentication framework
  - Database schema
  - Logging infrastructure
  - Basic application skeleton

- **External Dependencies**:
  - API specifications from external systems
  - Test data

### Extension Phase Dependencies
- **Core Phase Dependencies**:
  - Core business logic
  - Primary user interface
  - Essential services

- **External Dependencies**:
  - [List external dependencies]

### Integration Phase Dependencies
- **Core Phase Dependencies**:
  - [List core dependencies]

- **Extension Phase Dependencies**:
  - [List extension dependencies]

- **External Dependencies**:
  - Access to integration test environments
  - Test credentials for external systems

### Finalization Phase Dependencies
- **All previous phases must be complete**
- **External Dependencies**:
  - User acceptance testing environment
  - Production deployment approval

📋 PHASE TRANSITION PROCESS

flowchart TD
    classDef step fill:#f9d77e,stroke:#d9b95c,color:#000
    classDef artifact fill:#f4b8c4,stroke:#d498a4,color:#000
    classDef verification fill:#c5e8b7,stroke:#a5c897,color:#000

    Start([Begin Phase<br>Transition]) --> Verification[Verify Current<br>Phase Complete]
    Verification --> Checkpoint{Phase<br>Verified?}
    Checkpoint -->|No| Remediation[Remediate<br>Issues]
    Remediation --> Verification
    Checkpoint -->|Yes| Documentation[Update<br>Documentation]
    Documentation --> Reflection[Conduct Phase<br>Reflection]
    Reflection --> NextPlan[Finalize Next<br>Phase Plan]
    NextPlan --> Approvals[Obtain<br>Approvals]
    Approvals --> Kickoff[Conduct Next<br>Phase Kickoff]
    Kickoff --> End([Begin Next<br>Phase])

    Verification -.-> VerifDoc((Verification<br>Checklist))
    Documentation -.-> Docs((Updated<br>Documentation))
    Reflection -.-> ReflectDoc((Reflection<br>Document))
    NextPlan -.-> PlanDoc((Phase<br>Plan))

    class Start,End milestone
    class Verification,Remediation,Documentation,Reflection,NextPlan,Approvals,Kickoff step
    class Checkpoint verification
    class VerifDoc,Docs,ReflectDoc,PlanDoc artifact

Phase Transition Checklist

## Phase Transition Checklist

### Current Phase Closure
- [ ] All exit criteria met and documented
- [ ] All verification steps completed
- [ ] All issues resolved or documented
- [ ] Phase retrospective completed

### Documentation Updates
- [ ] Technical documentation updated
- [ ] User documentation updated
- [ ] Architecture documentation updated
- [ ] Test documentation updated

### Knowledge Transfer
- [ ] Lessons learned documented
- [ ] Knowledge shared with team
- [ ] Training conducted if needed

### Next Phase Preparation
- [ ] Next phase plan reviewed and updated
- [ ] Resources aligned
- [ ] Dependencies verified
- [ ] Entry criteria confirmed

### Approvals
- [ ] Technical lead approval
- [ ] Business stakeholder approval
- [ ] Project management approval

📋 IMPLEMENTATION TRACKING IN TASKS.MD

Update tasks.md to track phased implementation progress:

## [SYSTEM-ID]: System Name

### Implementation Phases
#### 1. Foundation Phase
- **Status**: [Not Started/In Progress/Complete]
- **Progress**: [0-100%]
- **Start Date**: [Date]
- **Target Completion**: [Date]
- **Actual Completion**: [Date]

**Key Components**:
- [ ] Component 1: [Status] - [Progress %]
- [ ] Component 2: [Status] - [Progress %]

**Verification Status**:
- [ ] Code Review: [Status]
- [ ] Testing: [Status]
- [ ] Architecture Review: [Status]
- [ ] Stakeholder Approval: [Status]

**Issues/Blockers**:
- [List of issues if any]

#### 2. Core Phase
...

#### 3. Extension Phase
...

#### 4. Integration Phase
...

#### 5. Finalization Phase
...

📋 MEMORY BANK INTEGRATION

flowchart TD
    classDef memfile fill:#f4b8c4,stroke:#d498a4,color:#000
    classDef process fill:#f9d77e,stroke:#d9b95c,color:#000

    Implementation[Phased<br>Implementation] --> PB[projectbrief.md]
    Implementation --> PC[productContext.md]
    Implementation --> AC[activeContext.md]
    Implementation --> SP[systemPatterns.md]
    Implementation --> TC[techContext.md]
    Implementation --> P[progress.md]

    PB & PC & AC & SP & TC & P --> MBI[Memory Bank<br>Integration]
    MBI --> Implementation

    class PB,PC,AC,SP,TC,P memfile
    class Implementation,MBI process

Memory Bank Updates

Update the following Memory Bank files during phased implementation:

1. projectbrief.md

   • Update implementation approach
   • Document phase-specific objectives
   • Link to phase plans

2. activeContext.md

   • Update with current implementation phase
   • Document active implementation tasks
   • Highlight current focus areas

3. systemPatterns.md

   • Document implementation patterns used
   • Update with architectural decisions made during implementation
   • Record any pattern adaptations

4. techContext.md

   • Update with implementation technologies
   • Document technical constraints encountered
   • Record technical decisions made

5. progress.md

   • Update implementation progress by phase
   • Document completed components
   • Track overall implementation status

📋 IMPLEMENTATION VERIFICATION CHECKLIST

✓ IMPLEMENTATION VERIFICATION CHECKLIST

Planning
- Implementation framework established? [YES/NO]
- Phasing plan created? [YES/NO]
- Phase dependencies documented? [YES/NO]
- Entry/exit criteria defined for all phases? [YES/NO]
- Risk assessment performed? [YES/NO]

Foundation Phase
- Environment setup complete? [YES/NO]
- Core architecture implemented? [YES/NO]
- Basic infrastructure in place? [YES/NO]
- CI/CD pipeline operational? [YES/NO]
- Foundation verification completed? [YES/NO]

Core Phase
- Core business logic implemented? [YES/NO]
- Primary user flows working? [YES/NO]
- Essential services operational? [YES/NO]
- Core APIs implemented? [YES/NO]
- Core verification completed? [YES/NO]

Extension Phase
- Secondary features implemented? [YES/NO]
- Enhanced functionality working? [YES/NO]
- Additional user interfaces complete? [YES/NO]
- Extended test coverage in place? [YES/NO]
- Extension verification completed? [YES/NO]

Integration Phase
- All components integrated? [YES/NO]
- External integrations working? [YES/NO]
- End-to-end testing completed? [YES/NO]
- Performance testing executed? [YES/NO]
- Integration verification completed? [YES/NO]

Finalization Phase
- All optimizations complete? [YES/NO]
- User acceptance testing passed? [YES/NO]
- Documentation finalized? [YES/NO]
- Production deployment plan ready? [YES/NO]
- Final system review completed? [YES/NO]

Memory Bank Integration
- All Memory Bank files updated? [YES/NO]
- Implementation status reflected? [YES/NO]
- Technical decisions documented? [YES/NO]
- Progress tracking current? [YES/NO]

📋 MINIMAL MODE IMPLEMENTATION FORMAT

For situations requiring a more compact implementation approach:

## [SYSTEM-ID]: Phased Implementation

### Phase Status Summary
- **Foundation**: [Status] - [Progress %]
- **Core**: [Status] - [Progress %]
- **Extension**: [Status] - [Progress %]
- **Integration**: [Status] - [Progress %]
- **Finalization**: [Status] - [Progress %]

### Current Phase: [Phase Name]
- **Key Components**: [List of key components being implemented]
- **Blockers**: [List of blockers if any]
- **Next Steps**: [List of immediate next steps]

### Verification Status
- [List of verification steps and their status]

### Memory Bank Updates
- [List of Memory Bank files that need updating]

🚨 IMPLEMENTATION VERIFICATION PRINCIPLE

┌─────────────────────────────────────────────────────┐
│ NO PHASE IS CONSIDERED COMPLETE until all            │
│ verification steps have been passed and documented.  │
│ Phases MUST NOT be rushed to meet deadlines at the   │
│ expense of quality or architectural integrity.       │
└─────────────────────────────────────────────────────┘