# /brownfield-create-story Task

When this command is used, execute the following task:

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

# Brownfield Story Creation Task

Create user stories specifically for enhancing existing systems, with careful attention to integration, migration, and legacy constraints.

## Purpose

This task creates stories for brownfield (existing project) enhancements that:

- Work safely within existing system constraints
- Minimize disruption to current operations and users
- Account for legacy data and integration requirements
- Enable incremental and reversible improvements
- Address technical debt while delivering new value

## Brownfield Story Patterns

### Common Brownfield Story Types

1. **Enhancement Stories** - Adding features to existing functionality
2. **Integration Stories** - Connecting existing systems with new capabilities
3. **Migration Stories** - Moving from old approaches to new ones
4. **Refactoring Stories** - Improving existing code without changing behavior
5. **Data Stories** - Improving data quality, structure, or access
6. **Performance Stories** - Optimizing existing system performance
7. **Security Stories** - Enhancing existing system security
8. **UI Modernization Stories** - Updating existing user interfaces

## Process

### Step 1: Brownfield Context Assessment

**System Impact Analysis:**
- Which existing components will be affected?
- What are the current user workflows?
- Are there integration dependencies?
- What data will be impacted?

**Risk Assessment Questions:**
- What could break if this story is implemented poorly?
- How will we test this safely in the existing system?
- What is the rollback strategy if problems occur?
- Who are the stakeholders that must approve changes?

### Step 2: Story Type Selection

Present numbered options based on brownfield context:

1. **Safe Enhancement** - Add new functionality without changing existing behavior
2. **Careful Migration** - Move from old approach to new with safety measures
3. **Gradual Refactoring** - Improve code quality in small, safe increments  
4. **Integration Bridge** - Connect existing system to new capabilities
5. **Data Improvement** - Enhance data quality or access without disruption
6. **Performance Optimization** - Improve existing system performance
7. **Security Hardening** - Enhance security without breaking functionality
8. **UI Modernization** - Update interface while preserving user familiarity
9. **Technical Debt Reduction** - Address specific technical debt items

### Step 3: Brownfield Story Information Gathering

**Standard Story Elements:**
- User type and goal (may be internal users/developers)
- Business value (may be technical/operational value)  
- Acceptance criteria (with extra focus on "what must not break")

**Brownfield-Specific Elements:**

**Legacy Constraints:**
- What existing behavior must be preserved?
- What are the performance characteristics to maintain?
- Are there data format or API compatibility requirements?
- What are the rollback requirements?

**Integration Requirements:**
- Which systems must continue working during and after changes?
- What are the data consistency requirements?
- Are there timing or sequencing constraints?
- What are the testing requirements in integrated environment?

**Migration Considerations:**
- Is this a complete replacement or gradual transition?
- What user training or communication is needed?
- How will we handle users in transition state?
- What data migration or cleanup is required?

### Step 4: Enhanced Story Structure

#### A. Brownfield Story Header

```yaml
story-id: "BF-STORY-[YYYY-MM-DD]-[###]"
title: "[Story title emphasizing enhancement/improvement]"
type: "[Enhancement|Migration|Refactoring|Integration|Data|Performance|Security|UI|TechDebt]"
brownfield-type: "[Safe-Enhancement|Careful-Migration|Gradual-Refactoring|Integration-Bridge|etc]"
priority: "[High|Medium|Low]"
estimate: "[XS|S|M|L|XL]"
risk-level: "[Low|Medium|High]"
rollback-complexity: "[Simple|Moderate|Complex]"

legacy-context:
  affected-systems: ["system1", "system2"]
  backward-compatibility: "[Full|Partial|Breaking-Change]"
  migration-required: "[Yes|No|Partial]"
  user-impact: "[None|Minimal|Moderate|Significant]"
  
agents:
  owner: "scrum-master"
  editors: ["developer", "qa", "architect"]
  readonly: []
```

#### B. Enhanced User Story Statement

**Enhancement Story Format:**
```
As a [existing user type]
I want [new capability] added to [existing functionality]
So that [additional value] while preserving [existing value]
```

**Migration Story Format:**
```
As a [user/system]
I need [old approach] to be replaced with [new approach]
So that [improvement] while maintaining [continuity/compatibility]
```

**Technical Story Format:**
```
As a [developer/system administrator]
I need [technical improvement] in [existing system]
So that [technical benefit] without disrupting [current operations]
```

#### C. Brownfield-Enhanced Acceptance Criteria

```yaml
acceptance-criteria:
  new-functionality:
    - scenario: "New capability works as intended"
      given: "Existing system state"
      when: "User performs new action"
      then: "New functionality works correctly"
      
  backward-compatibility:
    - scenario: "Existing functionality still works"
      given: "System with new changes"
      when: "User performs existing action"
      then: "Existing functionality unchanged"
      
  integration-safety:
    - scenario: "Integrated systems remain stable"
      given: "Changes deployed"
      when: "Integrated systems interact"
      then: "No degradation in integrated functionality"
      
  migration-safety:
    - scenario: "Migration preserves data integrity"
      given: "Data in old format"
      when: "Migration executes"
      then: "Data correctly converted with no loss"
      
  performance-requirements:
    - scenario: "Performance doesn't degrade"
      given: "System under normal load"
      when: "New functionality operates"
      then: "Response times remain within acceptable bounds"

rollback-criteria:
  rollback-triggers:
    - condition: "[Specific condition that requires rollback]"
      detection-method: "[How to detect this condition]"
      response-time: "[How quickly to respond]"
      
  rollback-validation:
    - check: "[What to verify after rollback]"
      method: "[How to verify]"
      success-criteria: "[When rollback is considered successful]"
```

#### D. Brownfield Implementation Guidance

```yaml
implementation-approach:
  strategy: "[Incremental|Feature-Toggle|Blue-Green|Canary|Shadow]"
  
  safety-measures:
    - measure: "[Safety measure]"
      purpose: "[Why this protects the system]"
      implementation: "[How to implement]"
      
  testing-strategy:
    existing-functionality-tests:
      - test-type: "[Regression test type]"
        scope: "[What existing functionality to test]"
        frequency: "[When to run these tests]"
        
    integration-tests:
      - integration: "[System integration]"
        test-approach: "[How to test integration]"
        success-criteria: "[When integration test passes]"
        
    performance-tests:
      - metric: "[Performance metric]"
        baseline: "[Current performance level]"
        threshold: "[Acceptable performance level]"
        test-method: "[How to measure]"

migration-plan:
  pre-migration:
    - step: "[Preparation step]"
      purpose: "[Why this step is needed]"
      validation: "[How to verify completion]"
      
  migration-execution:
    - step: "[Migration step]"
      order: "[When in sequence]"
      rollback-point: "[Can rollback be done after this step?]"
      validation: "[How to verify this step succeeded]"
      
  post-migration:
    - step: "[Post-migration step]"
      purpose: "[Why this step is needed]"
      success-criteria: "[When this step is complete]"

risk-mitigation:
  identified-risks:
    - risk: "[Specific risk]"
      probability: "[High|Medium|Low]"
      impact: "[High|Medium|Low]"
      mitigation: "[How to reduce risk]"
      detection: "[How to detect if risk occurs]"
      response: "[What to do if risk occurs]"
```

#### E. Stakeholder Communication Plan

```yaml
communication-plan:
  stakeholder-notifications:
    - stakeholder: "[Stakeholder type]"
      timing: "[When to notify]"
      method: "[How to communicate]"
      content: "[What to communicate]"
      
  user-impact-communication:
    - impact-type: "[Type of impact on users]"
      communication-timing: "[When to inform users]"
      communication-method: "[How to reach users]"
      messaging: "[Key messages for users]"
      support-plan: "[How to support users through change]"
      
  technical-team-coordination:
    - team: "[Technical team]"
      coordination-needs: "[What coordination is needed]"
      timing: "[When coordination is needed]"
      deliverables: "[What they need to provide]"
```

### Step 5: Story Validation for Brownfield Context

Apply enhanced validation checklist:

1. **Safety Validation**
   - Rollback strategy is clearly defined and tested
   - Backward compatibility requirements addressed
   - Integration safety measures identified
   - Risk assessment completed with mitigation plans

2. **Implementation Validation**
   - Implementation approach minimizes system disruption
   - Testing strategy covers existing functionality
   - Migration plan (if applicable) is detailed and safe
   - Performance impact assessed and monitored

3. **Stakeholder Validation**
   - All affected stakeholders identified
   - Communication plan addresses user concerns
   - Approval processes for changes defined
   - Support plans for users during transition

4. **Technical Validation**
   - Technical approach works within existing constraints
   - Dependencies on other systems understood
   - Data integrity and consistency maintained
   - Monitoring and alerting updated for new functionality

## Advanced Brownfield Patterns

### Feature Toggle Pattern

For new functionality that needs to be gradually enabled:

```yaml
feature-toggle-approach:
  toggle-strategy: "[User-based|Percentage|Geographic|Time-based]"
  rollout-phases:
    - phase: "[Phase name]"
      toggle-state: "[On/Off/Partial]" 
      user-criteria: "[Which users affected]"
      success-metrics: "[How to measure success]"
      rollback-trigger: "[What triggers rollback]"
```

### Strangler Fig Pattern

For gradually replacing legacy functionality:

```yaml
strangler-fig-approach:
  replacement-strategy: "[How new replaces old]"
  coexistence-period: "[How long old and new coexist]"
  migration-phases:
    - phase: "[Migration phase]"
      scope: "[What gets migrated]"
      user-impact: "[Impact on users]"
      validation: "[How to verify success]"
  legacy-retirement: "[When and how to retire old system]"
```

### Database Evolution Pattern

For stories involving database changes:

```yaml
database-evolution:
  schema-changes:
    - change: "[Schema change description]"
      backward-compatibility: "[Yes|No|Transitional]"
      migration-script: "[Migration approach]"
      rollback-script: "[Rollback approach]"
      data-validation: "[How to verify data integrity]"
      
  data-migration:
    approach: "[Batch|Streaming|Hybrid]"
    validation-strategy: "[How to verify migration]"
    performance-impact: "[Expected impact on system]"
    rollback-data-strategy: "[How to rollback data changes]"
```

## Quality Gates for Brownfield Stories

Before brownfield story completion:

- [ ] Legacy system impact analysis completed
- [ ] Backward compatibility requirements defined
- [ ] Integration testing strategy documented
- [ ] Rollback plan defined and validated
- [ ] Risk assessment completed with mitigation plans
- [ ] Stakeholder communication plan created
- [ ] Performance impact assessed and monitored
- [ ] Data integrity and migration plan (if applicable) defined
- [ ] Feature toggle or gradual rollout plan (if applicable)
- [ ] Support and training plan for users created

## Integration with Development Process

**Pre-Development:**
- Architecture review for complex brownfield changes
- Database review for schema/data changes
- Security review for changes affecting authentication/authorization
- Performance baseline establishment

**During Development:**
- Continuous integration testing with existing functionality
- Regular integration testing with dependent systems
- Performance monitoring throughout development
- Stakeholder communication at key milestones

**Post-Development:**
- Production monitoring for performance and stability
- User feedback collection and response
- Success metrics tracking and reporting
- Lessons learned documentation for future brownfield stories

## Success Patterns for Brownfield Stories

### Incremental Value Delivery

Structure stories to deliver value incrementally:
- Each story provides user-visible value
- Stories can be developed and deployed independently
- Rollback affects only the current story, not previous ones
- Users experience gradual improvement rather than disruption

### Risk-Aware Implementation

Plan implementation with risk management:
- High-risk changes get extra validation and testing
- Rollback procedures tested before deployment
- Monitoring and alerting updated before deployment
- Stakeholder approval for high-impact changes

### User-Centered Transition

Focus on user experience during transitions:
- Minimize learning curve for new functionality
- Provide clear communication about changes
- Offer training and support during transition
- Collect and respond to user feedback quickly