# /create-brownfield-story Task

When this command is used, execute the following task:

---
docOutputLocation: .vcsys/stories/legacy-story-[auto-increment].yaml
template: ".vcsys/templates/story-tmpl.yaml"
---

# Create Brownfield Story Task

Specialized task for creating stories that work with legacy systems, focusing on modernization, integration, and gradual improvement while preserving existing functionality.

## Purpose

This task creates stories specifically for legacy system improvements that:

- Work safely within outdated technology constraints
- Enable modernization without complete system rewrites
- Preserve critical business functionality during transitions
- Address technical debt systematically and incrementally
- Bridge legacy systems with modern approaches

## Legacy System Context

### Common Legacy Challenges

1. **Technical Debt** - Accumulated shortcuts and outdated approaches
2. **Outdated Technology** - Old frameworks, languages, or platforms
3. **Monolithic Architecture** - Tightly coupled systems hard to change
4. **Data Quality Issues** - Inconsistent or incomplete data
5. **Limited Documentation** - Missing or outdated system documentation
6. **Integration Complexity** - Difficult connections between systems
7. **Performance Issues** - Systems not optimized for current loads
8. **Security Vulnerabilities** - Outdated security practices

### Legacy Modernization Strategies

1. **Strangler Fig** - Gradually replace functionality
2. **Anti-Corruption Layer** - Isolate legacy system interactions
3. **Database-First Modernization** - Start with data layer improvements
4. **API Gateway** - Modern interface to legacy services
5. **Event-Driven Decoupling** - Use events to reduce direct coupling
6. **Incremental Refactoring** - Small, safe improvements over time

## Process

### Step 1: Legacy System Assessment

**System Characterization:**
- What is the age and technology stack of the legacy system?
- What is the current state of documentation?
- Who are the current maintainers and stakeholders?
- What are the known pain points and limitations?
- What business processes depend on this system?

**Technical Evaluation:**
- What technologies and frameworks are being used?
- What is the current architecture and design patterns?
- Are there existing APIs or integration points?
- What is the current data structure and quality?
- What are the performance characteristics?

**Risk Assessment:**
- What are the biggest risks to changing this system?
- What functionality is most critical to preserve?
- What could cause the most business disruption?
- Are there compliance or regulatory considerations?
- What is the disaster recovery/rollback situation?

### Step 2: Legacy Story Pattern Selection

Present numbered options based on legacy context:

1. **Data Modernization** - Improve data quality, structure, or access
2. **API Creation** - Add modern interfaces to legacy functionality  
3. **Security Hardening** - Address security vulnerabilities safely
4. **Performance Optimization** - Improve system performance incrementally
5. **Functionality Extraction** - Move specific functions to modern systems
6. **Integration Bridge** - Connect legacy systems to modern infrastructure
7. **User Interface Modernization** - Update UI while preserving backend
8. **Monitoring and Observability** - Add visibility into legacy system behavior
9. **Documentation Recovery** - Create missing documentation for legacy systems
10. **Gradual Architecture Evolution** - Small steps toward better architecture

### Step 3: Legacy-Specific Information Gathering

**Business Continuity Requirements:**
- What functionality absolutely cannot be interrupted?
- What are the acceptable maintenance windows?
- Who must approve changes to this system?
- What are the rollback requirements?

**Technical Constraints:**
- What technology limitations must we work within?
- Are there database or data format constraints?
- What are the performance requirements to maintain?
- Are there integration points that cannot be changed?

**Stakeholder Concerns:**
- Who are the business users affected by changes?
- What are their biggest concerns about system changes?
- What training or support might be needed?
- How will success be measured from their perspective?

### Step 4: Enhanced Legacy Story Structure

#### A. Legacy Story Header

```yaml
story-id: "LEGACY-STORY-[YYYY-MM-DD]-[###]"
title: "[Story title focusing on specific improvement]"
legacy-pattern: "[Data-Modernization|API-Creation|Security-Hardening|Performance-Optimization|etc]"
modernization-strategy: "[Strangler-Fig|Anti-Corruption-Layer|API-Gateway|Incremental-Refactoring|etc]"
priority: "[Critical|High|Medium|Low]"
estimate: "[XS|S|M|L|XL]"
risk-level: "[Low|Medium|High|Critical]"
business-criticality: "[Low|Medium|High|Critical]"

legacy-context:
  system-age: "[Years since original development]"
  technology-stack: ["tech1", "tech2", "tech3"]
  documentation-state: "[Complete|Partial|Minimal|Missing]"
  maintainer-knowledge: "[Expert|Intermediate|Minimal|None]"
  business-dependency: "[Low|Medium|High|Critical]"
  change-frequency: "[Daily|Weekly|Monthly|Rarely|Never]"
  
constraints:
  cannot-change: ["[Constraint 1]", "[Constraint 2]"]
  must-preserve: ["[Requirement 1]", "[Requirement 2]"]
  technology-limits: ["[Limitation 1]", "[Limitation 2]"]
  data-constraints: ["[Data constraint 1]", "[Data constraint 2]"]
  
agents:
  owner: "scrum-master"
  editors: ["developer", "qa", "architect"]
  readonly: ["legacy-system-expert"]
```

#### B. Legacy-Focused User Story Statement

**Modernization Story Format:**
```
As a [user/maintainer] of the legacy [system name]
I need [specific improvement] to the [legacy component]
So that [modern benefit] while maintaining [legacy reliability/functionality]
```

**Integration Story Format:**
```
As a [modern system user]
I need the legacy [system name] to [integration capability]
So that [business value] without disrupting [existing legacy workflows]
```

**Technical Debt Story Format:**
```
As a [developer/maintainer]
I need to [improve/fix] [specific technical debt] in [legacy system]
So that [technical benefit] while preserving [existing functionality]
```

#### C. Legacy-Enhanced Acceptance Criteria

```yaml
acceptance-criteria:
  improvement-validation:
    - scenario: "Improvement works as intended"
      given: "Legacy system with new enhancement"
      when: "[User action or system trigger]"
      then: "[Improved behavior or capability]"
      
  legacy-preservation:
    - scenario: "Existing legacy functionality unchanged"
      given: "System after enhancement"
      when: "[Existing legacy workflow performed]"
      then: "Legacy functionality works exactly as before"
      
  data-integrity:
    - scenario: "Data remains consistent and accurate"
      given: "Data changes from enhancement"
      when: "Data validation performed"
      then: "All data integrity checks pass"
      
  performance-maintenance:
    - scenario: "System performance not degraded"
      given: "Enhanced legacy system under normal load"
      when: "Performance measurements taken"
      then: "Performance meets or exceeds previous benchmarks"
      
  rollback-capability:
    - scenario: "Changes can be safely reversed"
      given: "Enhancement deployed"
      when: "Rollback procedure executed"
      then: "System returns to previous state with no data loss"

legacy-specific-validation:
  compatibility-checks:
    - check: "[Specific compatibility requirement]"
      test-method: "[How to verify compatibility]"
      pass-criteria: "[What constitutes success]"
      
  business-continuity:
    - business-process: "[Critical business process]"
      validation-method: "[How to verify process still works]"
      success-criteria: "[What proves business continuity]"
      
  regulatory-compliance:
    - requirement: "[Compliance requirement]"
      validation-approach: "[How to verify compliance maintained]"
      documentation-needed: "[What documentation is required]"
```

#### D. Legacy Implementation Strategy

```yaml
implementation-approach:
  modernization-pattern: "[Specific pattern being used]"
  
  phased-approach:
    - phase: "Phase 1 - [Phase name]"
      objectives: ["[Objective 1]", "[Objective 2]"]
      legacy-changes: ["[What legacy changes in this phase]"]
      rollback-point: "[Can rollback be done after this phase?]"
      validation-criteria: ["[How to validate this phase]"]
      
  safety-measures:
    - measure: "[Safety measure name]"
      purpose: "[What this protects against]"
      implementation: "[How to implement this measure]"
      monitoring: "[How to monitor effectiveness]"
      
  testing-strategy:
    legacy-regression-tests:
      - test-category: "[Type of regression test]"
        scope: "[What legacy functionality to test]"
        automation-level: "[Manual|Semi-automated|Fully-automated]"
        frequency: "[How often to run]"
        
    integration-tests:
      - integration-point: "[System integration]"
        test-approach: "[How to test this integration]"
        legacy-system-impact: "[How testing affects legacy system]"
        
    data-validation-tests:
      - data-category: "[Type of data]"
        validation-method: "[How to validate data]"
        consistency-checks: ["[Consistency check 1]", "[Consistency check 2]"]
        
    performance-benchmarks:
      - metric: "[Performance metric]"
        legacy-baseline: "[Current legacy system performance]"
        acceptable-threshold: "[Minimum acceptable performance]"
        measurement-method: "[How to measure]"

legacy-specific-considerations:
  documentation-recovery:
    - missing-documentation: "[What documentation is missing]"
      discovery-method: "[How to discover/recreate documentation]"
      stakeholder-interviews: "[Who to interview for knowledge]"
      
  knowledge-transfer:
    - knowledge-area: "[Area of legacy system knowledge]"
      current-experts: "[Who currently has this knowledge]"
      transfer-method: "[How to transfer/document knowledge]"
      
  technology-constraints:
    - constraint: "[Technology constraint]"
      workaround: "[How to work within this constraint]"
      future-mitigation: "[Long-term plan to address constraint]"
```

#### E. Legacy Risk Management

```yaml
risk-management:
  high-probability-risks:
    - risk: "[Likely risk in legacy context]"
      probability: "[High|Medium|Low]"
      impact: "[Critical|High|Medium|Low]"
      early-detection: "[How to detect this risk early]"
      mitigation: "[How to reduce or eliminate risk]"
      contingency: "[What to do if risk occurs]"
      
  legacy-specific-risks:
    - risk: "Documentation is incomplete or incorrect"
      detection: "[How to identify documentation problems]"
      mitigation: "[How to address documentation gaps]"
      
    - risk: "Legacy system behavior is not fully understood"
      detection: "[How to identify unknown behaviors]"
      mitigation: "[How to safely discover and document behaviors]"
      
    - risk: "Changes break undocumented dependencies"
      detection: "[How to identify hidden dependencies]"
      mitigation: "[How to safely manage unknown dependencies]"
      
    - risk: "Rollback is not possible due to data changes"
      detection: "[How to identify irreversible changes]"
      mitigation: "[How to ensure rollback capability]"

rollback-strategy:
  rollback-scenarios:
    - scenario: "[What would trigger rollback]"
      detection-method: "[How to detect this scenario]"
      rollback-procedure: "[Step-by-step rollback process]"
      data-recovery: "[How to recover data if needed]"
      business-communication: "[How to communicate rollback to business]"
      
  rollback-testing:
    - test: "[Rollback test description]"
      environment: "[Where to test rollback]"
      success-criteria: "[How to verify successful rollback]"
      
  rollback-limitations:
    - limitation: "[What cannot be rolled back]"
      reason: "[Why rollback is not possible]"
      mitigation: "[How to handle non-rollbackable changes]"
```

#### F. Stakeholder Management for Legacy Context

```yaml
stakeholder-management:
  legacy-system-experts:
    - expert: "[Name/role of legacy expert]"
      knowledge-areas: ["[Knowledge area 1]", "[Knowledge area 2]"]
      involvement-level: "[How much involvement needed]"
      knowledge-transfer-plan: "[How to capture their knowledge]"
      
  business-stakeholders:
    - stakeholder: "[Business stakeholder role]"
      concerns: ["[Primary concern about legacy changes]"]
      success-criteria: "[What success means to them]"
      communication-needs: "[How they want to be kept informed]"
      approval-authority: "[What they need to approve]"
      
  end-users:
    - user-group: "[Type of legacy system users]"
      current-workflows: "[How they currently use the system]"
      change-tolerance: "[High|Medium|Low tolerance for change]"
      training-needs: "[What training might be needed]"
      support-requirements: "[What support during transition]"

communication-strategy:
  change-communication:
    - audience: "[Communication audience]"
      timing: "[When to communicate]"
      message: "[Key messages]"
      method: "[How to communicate]"
      feedback-mechanism: "[How to collect feedback]"
      
  risk-communication:
    - risk-level: "[High|Medium|Low]"
      stakeholders: "[Who needs to know about this risk]"
      message-content: "[What to communicate about risk]"
      escalation-criteria: "[When to escalate risk communication]"
```

### Step 5: Legacy Story Validation

Apply comprehensive legacy-focused validation:

1. **Legacy Preservation Validation**
   - All existing functionality explicitly tested and preserved
   - Business continuity requirements met
   - Regulatory compliance maintained
   - Critical data integrity assured

2. **Risk Management Validation**
   - All legacy-specific risks identified and planned for
   - Rollback strategy tested and verified
   - Early warning systems for problems implemented
   - Contingency plans for high-probability issues

3. **Knowledge and Documentation Validation**
   - Missing knowledge identified and acquisition planned
   - Documentation gaps filled or explicitly acknowledged
   - Expert knowledge captured and transferred
   - Assumptions validated with legacy system experts

4. **Technical Safety Validation**
   - Technology constraints respected and worked within
   - Integration points preserved and tested
   - Performance baselines established and monitored
   - Data migration/changes validated extensively

## Advanced Legacy Patterns

### Anti-Corruption Layer Pattern

For protecting modern code from legacy system complexities:

```yaml
anti-corruption-layer:
  purpose: "[What the layer protects against]"
  interface-design: "[How modern code interfaces with layer]"
  legacy-isolation: "[How layer isolates legacy complexities]"
  data-translation: "[How data is translated between layers]"
  error-handling: "[How layer handles legacy system errors]"
```

### Event-Driven Decoupling Pattern

For reducing direct coupling between legacy and modern systems:

```yaml
event-driven-decoupling:
  event-types: ["[Event type 1]", "[Event type 2]"]
  legacy-event-generation: "[How legacy system generates events]"
  modern-event-consumption: "[How modern systems consume events]"
  failure-handling: "[How to handle event processing failures]"
  ordering-guarantees: "[What event ordering is guaranteed]"
```

## Quality Gates for Legacy Stories

Before legacy story completion:

- [ ] Legacy system impact analysis completed with expert input
- [ ] All critical functionality preservation verified
- [ ] Knowledge gaps identified and addressed
- [ ] Documentation recovery plan implemented
- [ ] Technology constraints respected in solution design
- [ ] Comprehensive rollback strategy defined and tested
- [ ] Business continuity plan validated with stakeholders
- [ ] Risk assessment includes legacy-specific risks
- [ ] Performance benchmarks established and monitored
- [ ] Regulatory compliance verified and maintained

## Success Metrics for Legacy Modernization

### Technical Success Metrics

- **Functionality Preservation**: 100% of critical legacy functionality maintained
- **Performance Maintenance**: Legacy system performance maintained or improved
- **Data Integrity**: Zero data loss or corruption during changes
- **System Stability**: No increase in system downtime or errors
- **Integration Stability**: All existing integrations continue working

### Business Success Metrics

- **Business Continuity**: No disruption to critical business processes
- **User Satisfaction**: User acceptance of changes (survey/feedback)
- **Cost Impact**: Changes stay within budget parameters
- **Timeline**: Changes delivered within agreed timeframes
- **Risk Realization**: Number and severity of risks that actually occurred

### Modernization Progress Metrics

- **Technical Debt Reduction**: Measurable improvement in code quality metrics
- **Maintainability**: Reduced time for common maintenance tasks
- **Flexibility**: Increased ability to make future changes
- **Documentation**: Improved documentation coverage and accuracy
- **Knowledge Transfer**: Reduced dependency on legacy system experts

## Integration with Modernization Strategy

**Portfolio-Level Planning:**
- Coordinate with other modernization efforts
- Manage dependencies between legacy improvement stories
- Balance modernization with maintenance and new development
- Plan resource allocation across legacy and modern systems

**Architecture Evolution:**
- Ensure story changes align with target architecture
- Plan transition steps toward modernized architecture
- Maintain architectural consistency across changes
- Document architectural decisions and their legacy implications

**Risk Management:**
- Aggregate risk across multiple legacy changes
- Plan contingencies for multiple simultaneous changes
- Coordinate rollback procedures across related changes
- Monitor cumulative impact on legacy system stability