ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity
BMAD-METHOD/bmad-core/tasks/build-context-analysis.md

19 KiB
Raw Blame History

Build Context Analysis

Task Overview

Perform comprehensive context analysis before attempting to fix build errors to prevent regressions and technical debt introduction. This consolidated framework combines systematic investigation with validation checklists to ensure informed fixes rather than blind error resolution.

Context

This analysis prevents developers from blindly "fixing" build errors without understanding why they exist and what functionality could be lost. It combines historical investigation, test contract analysis, dependency mapping, and risk assessment into a single comprehensive approach.

Execution Approach

CRITICAL BUILD CONTEXT VALIDATION - This analysis addresses systematic "quick fix" behavior that introduces regressions.

  1. Investigate the history - why did the build break?
  2. Understand the intended behavior through tests
  3. Map all dependencies and integration points
  4. Plan fixes that preserve existing functionality
  5. Create validation checkpoints to catch regressions

The goal is informed fixes, not blind error resolution.

Prerequisites

  • Build errors identified and categorized
  • Story requirements understood
  • Access to git history and previous implementations
  • Development environment configured for analysis

Phase 1: Historical Context Investigation

Git History Analysis

Understand the story behind each build error:

For each build error category:

  • Recent Changes Identified: Found commits that introduced build errors
  • Git Blame Analysis: Identify when interface/implementation diverged
  • Commit Message Review: Understand the intent behind interface changes
  • Previous Implementation Review: Study what the working code actually did
  • Interface Evolution Understood: Know why interfaces changed vs implementations
  • Previous Working State Documented: Have record of last working implementation
  • Change Intent Clarified: Understand purpose of interface modifications
  • Business Logic Preserved: Identified functionality that must be maintained
  • Change Justification: Understand why the interface was modified

Historical Analysis Commands

echo "=== BUILD CONTEXT HISTORICAL ANALYSIS ==="
echo "Analysis Date: $(date)"
echo "Analyst: [Developer Agent Name]"
echo ""

# Create analysis report
CONTEXT_REPORT="build-context-$(date +%Y%m%d-%H%M).md"
echo "# Build Context Analysis Report" > $CONTEXT_REPORT
echo "Date: $(date)" >> $CONTEXT_REPORT
echo "" >> $CONTEXT_REPORT

echo "=== GIT HISTORY INVESTIGATION ===" | tee -a $CONTEXT_REPORT

# Find recent commits that might have caused build errors
echo "## Recent Commits Analysis" >> $CONTEXT_REPORT
echo "Recent commits (last 10):" | tee -a $CONTEXT_REPORT
git log --oneline -10 | tee -a $CONTEXT_REPORT

echo "" >> $CONTEXT_REPORT
echo "## Interface Changes Detection" >> $CONTEXT_REPORT

# Look for interface/API changes in recent commits
echo "Interface changes in recent commits:" | tee -a $CONTEXT_REPORT
git log --oneline -20 --grep="interface\|API\|contract\|signature" | tee -a $CONTEXT_REPORT

# Find files with frequent recent changes
echo "" >> $CONTEXT_REPORT
echo "## Frequently Modified Files" >> $CONTEXT_REPORT
echo "Files with most changes in last 30 days:" | tee -a $CONTEXT_REPORT
git log --since="30 days ago" --name-only --pretty=format: | sort | uniq -c | sort -rn | head -20 | tee -a $CONTEXT_REPORT

# Analyze specific error-causing files
echo "" >> $CONTEXT_REPORT
echo "## Build Error File Analysis" >> $CONTEXT_REPORT
for file in $(find . -name "*.cs" -o -name "*.java" -o -name "*.ts" -o -name "*.js" -o -name "*.py" -o -name "*.rs" -o -name "*.go" | head -10); do
    if [ -f "$file" ]; then
        echo "### File: $file" >> $CONTEXT_REPORT
        echo "Last 5 commits affecting this file:" >> $CONTEXT_REPORT
        git log --oneline -5 -- "$file" >> $CONTEXT_REPORT
        echo "" >> $CONTEXT_REPORT
    fi
done

Documentation Required

Document findings in the following format:

## Build Error Context Analysis

### Error Category: [UserRole Constructor Issues - 50 errors]

#### Git History Investigation:
- **Last Working Commit**: [commit hash]
- **Interface Change Commit**: [commit hash] 
- **Change Reason**: [why was interface modified]
- **Previous Functionality**: [what did the old implementation do]
- **Business Logic Lost**: [any functionality that would be lost]

#### Most Recent Interface Changes:
- UserRole interface changed in commit [hash] because [reason]
- SecurityEvent interface evolved in commit [hash] for [purpose]
- CachedUserSession modified in commit [hash] to support [feature]

#### Critical Business Logic to Preserve:
- [List functionality that must not be lost]
- [Dependencies that must be maintained]
- [Behavior patterns that must continue working]

Phase 2: Test Contract Analysis

Existing Test Investigation

Let existing tests define the correct behavior:

  • All Relevant Tests Located: Found every test touching broken components
  • Find All Tests: Locate every test that touches the broken components
  • Test Expectations Documented: Understand exactly what tests expect
  • Analyze Test Expectations: Understand what behavior tests expect
  • Interface Contracts Mapped: Know the API contracts tests enforce
  • Map API Contracts: Understand the interfaces tests expect to exist
  • Behavior Patterns Identified: Understand consistent usage patterns
  • Identify Usage Patterns: Find how components are actually used

Test Analysis Commands

echo "=== TEST CONTRACT ANALYSIS ===" | tee -a $CONTEXT_REPORT

# Find all test files
echo "## Test File Discovery" >> $CONTEXT_REPORT
echo "Locating test files..." | tee -a $CONTEXT_REPORT

# Different project types have different test patterns
if find . -name "*.Test.cs" -o -name "*Tests.cs" | head -1 | grep -q .; then
    # .NET tests
    TEST_FILES=$(find . -name "*.Test.cs" -o -name "*Tests.cs" -o -name "*Test*.cs")
    echo "Found .NET test files:" | tee -a $CONTEXT_REPORT
elif find . -name "*.test.js" -o -name "*.spec.js" | head -1 | grep -q .; then
    # JavaScript tests
    TEST_FILES=$(find . -name "*.test.js" -o -name "*.spec.js" -o -name "*.test.ts" -o -name "*.spec.ts")
    echo "Found JavaScript/TypeScript test files:" | tee -a $CONTEXT_REPORT
elif find . -name "*_test.py" -o -name "test_*.py" | head -1 | grep -q .; then
    # Python tests
    TEST_FILES=$(find . -name "*_test.py" -o -name "test_*.py")
    echo "Found Python test files:" | tee -a $CONTEXT_REPORT
elif find . -name "*_test.go" | head -1 | grep -q .; then
    # Go tests
    TEST_FILES=$(find . -name "*_test.go")
    echo "Found Go test files:" | tee -a $CONTEXT_REPORT
elif find . -name "*_test.rs" | head -1 | grep -q .; then
    # Rust tests
    TEST_FILES=$(find . -name "*_test.rs" -o -name "lib.rs" -path "*/tests/*")
    echo "Found Rust test files:" | tee -a $CONTEXT_REPORT
else
    # Generic search
    TEST_FILES=$(find . -name "*test*" -name "*.java" -o -name "*Test*")
    echo "Found test files (generic):" | tee -a $CONTEXT_REPORT
fi

echo "$TEST_FILES" | tee -a $CONTEXT_REPORT

# Analyze test expectations for key components
echo "" >> $CONTEXT_REPORT
echo "## Test Expectations Analysis" >> $CONTEXT_REPORT

for test_file in $TEST_FILES; do
    if [ -f "$test_file" ] && [ $(wc -l < "$test_file") -gt 0 ]; then
        echo "### Test File: $test_file" >> $CONTEXT_REPORT
        
        # Look for constructor calls, method calls, and assertions
        echo "Constructor usage patterns:" >> $CONTEXT_REPORT
        grep -n "new.*(" "$test_file" | head -5 >> $CONTEXT_REPORT 2>/dev/null || echo "No constructor patterns found" >> $CONTEXT_REPORT
        
        echo "Method call patterns:" >> $CONTEXT_REPORT  
        grep -n "\\..*(" "$test_file" | head -5 >> $CONTEXT_REPORT 2>/dev/null || echo "No method call patterns found" >> $CONTEXT_REPORT
        
        echo "Assertion patterns:" >> $CONTEXT_REPORT
        grep -n "Assert\|expect\|should\|assert" "$test_file" | head -5 >> $CONTEXT_REPORT 2>/dev/null || echo "No assertion patterns found" >> $CONTEXT_REPORT
        
        echo "" >> $CONTEXT_REPORT
    fi
done

Test Contract Documentation

Document test findings:

## Test Contract Analysis

### Test Files Located:
- [List of all relevant test files]

### API Contracts Expected by Tests:
- UserRole expects constructor with [parameters]
- SecurityEvent expects methods [list methods]
- CachedUserSession expects behavior [describe behavior]

### Consistent Usage Patterns:
- [Pattern 1: How components are typically instantiated]
- [Pattern 2: Common method call sequences]
- [Pattern 3: Expected return types and values]

### Test Expectations to Preserve:
- [Critical test behaviors that must continue working]

Phase 3: Dependency Integration Analysis

Integration Point Mapping

Map all components that depend on broken interfaces:

  • Dependent Components Identified: Found all code that uses broken interfaces
  • Integration Points Mapped: Know how components connect and communicate
  • Data Flow Understood: Traced how data moves through dependent systems
  • Call Chain Analysis: Understand sequence of operations
  • Impact Assessment Completed: Know scope of potential regression

Dependency Analysis Commands

echo "=== DEPENDENCY INTEGRATION ANALYSIS ===" | tee -a $CONTEXT_REPORT

# Find dependencies and usage patterns
echo "## Dependency Mapping" >> $CONTEXT_REPORT

# Search for class/interface usage across the codebase
if find . -name "*.cs" | head -1 | grep -q .; then
    # .NET analysis
    echo "Analyzing .NET dependencies..." | tee -a $CONTEXT_REPORT
    
    # Find interface implementations
    echo "### Interface Implementations:" >> $CONTEXT_REPORT
    grep -r "class.*:.*I[A-Z]" . --include="*.cs" | head -10 >> $CONTEXT_REPORT
    
    # Find constructor usage
    echo "### Constructor Usage Patterns:" >> $CONTEXT_REPORT
    grep -r "new [A-Z][a-zA-Z]*(" . --include="*.cs" | head -15 >> $CONTEXT_REPORT
    
elif find . -name "*.ts" -o -name "*.js" | head -1 | grep -q .; then
    # TypeScript/JavaScript analysis
    echo "Analyzing TypeScript/JavaScript dependencies..." | tee -a $CONTEXT_REPORT
    
    # Find imports
    echo "### Import Dependencies:" >> $CONTEXT_REPORT
    grep -r "import.*from\|require(" . --include="*.ts" --include="*.js" | head -15 >> $CONTEXT_REPORT
    
    # Find class usage
    echo "### Class Usage Patterns:" >> $CONTEXT_REPORT
    grep -r "new [A-Z]" . --include="*.ts" --include="*.js" | head -15 >> $CONTEXT_REPORT
    
elif find . -name "*.java" | head -1 | grep -q .; then
    # Java analysis
    echo "Analyzing Java dependencies..." | tee -a $CONTEXT_REPORT
    
    # Find imports
    echo "### Import Dependencies:" >> $CONTEXT_REPORT
    grep -r "import.*;" . --include="*.java" | head -15 >> $CONTEXT_REPORT
    
    # Find constructor usage
    echo "### Constructor Usage:" >> $CONTEXT_REPORT
    grep -r "new [A-Z][a-zA-Z]*(" . --include="*.java" | head -15 >> $CONTEXT_REPORT
fi

# Analyze call chains and data flow
echo "" >> $CONTEXT_REPORT
echo "## Call Chain Analysis" >> $CONTEXT_REPORT
echo "Method call patterns in source files:" >> $CONTEXT_REPORT

# Find method chaining and call patterns
grep -r "\\..*\\." . --include="*.cs" --include="*.java" --include="*.ts" --include="*.js" | head -20 >> $CONTEXT_REPORT 2>/dev/null || echo "No method chains found" >> $CONTEXT_REPORT

Integration Documentation

## Integration Analysis

### Dependent Components:
- [Component 1]: Uses [interfaces/classes] in [specific ways]
- [Component 2]: Depends on [functionality] for [purpose]
- [Component 3]: Integrates with [services] through [methods]

### Data Flow Paths:
- [Path 1]: Data flows from [source] through [intermediates] to [destination]
- [Path 2]: Information passes between [components] via [mechanisms]

### Critical Integration Points:
- [Integration 1]: [Component A] ↔ [Component B] via [interface]
- [Integration 2]: [System X] ↔ [System Y] through [API calls]

### Impact Assessment:
- **High Risk**: [Components that could break completely]
- **Medium Risk**: [Components that might have reduced functionality]  
- **Low Risk**: [Components with minimal coupling]

Phase 4: Risk Assessment and Planning

Comprehensive Risk Analysis

Assess the risk of different fix approaches:

  • Fix Approaches Evaluated: Considered multiple ways to resolve build errors
  • Regression Risk Assessed: Understand likelihood of breaking existing functionality
  • Testing Strategy Planned: Know how to validate fixes don't introduce regressions
  • Rollback Plan Prepared: Have strategy if fixes introduce new problems
  • Impact Scope Bounded: Understand maximum possible scope of changes

Risk Assessment Framework

echo "=== RISK ASSESSMENT ===" | tee -a $CONTEXT_REPORT

echo "## Fix Strategy Risk Analysis" >> $CONTEXT_REPORT

# Analyze different fix approaches
echo "### Possible Fix Approaches:" >> $CONTEXT_REPORT
echo "1. **Interface Restoration**: Restore previous interface signatures" >> $CONTEXT_REPORT
echo "   - Risk: May conflict with new functionality requirements" >> $CONTEXT_REPORT
echo "   - Impact: Low regression risk, high business requirement risk" >> $CONTEXT_REPORT
echo "" >> $CONTEXT_REPORT

echo "2. **Implementation Adaptation**: Update implementations to match new interfaces" >> $CONTEXT_REPORT
echo "   - Risk: May break existing functionality if not careful" >> $CONTEXT_REPORT
echo "   - Impact: Medium regression risk, low requirement risk" >> $CONTEXT_REPORT
echo "" >> $CONTEXT_REPORT

echo "3. **Hybrid Approach**: Combine interface restoration with selective implementation updates" >> $CONTEXT_REPORT
echo "   - Risk: Complex changes with multiple failure points" >> $CONTEXT_REPORT
echo "   - Impact: Variable risk depending on execution" >> $CONTEXT_REPORT
echo "" >> $CONTEXT_REPORT

# Document critical risk factors
echo "### Critical Risk Factors:" >> $CONTEXT_REPORT
echo "- **Test Coverage**: $(find . -name "*test*" -o -name "*Test*" | wc -l) test files found" >> $CONTEXT_REPORT
echo "- **Integration Complexity**: Multiple components interact through changed interfaces" >> $CONTEXT_REPORT
echo "- **Business Logic Preservation**: Core functionality must remain intact" >> $CONTEXT_REPORT
echo "- **Timeline Pressure**: Need to balance speed with quality" >> $CONTEXT_REPORT

Risk Documentation

## Risk Assessment Summary

### Fix Strategy Recommendations:
- **Recommended Approach**: [Chosen strategy with justification]
- **Alternative Approaches**: [Other options considered and why rejected]

### Risk Mitigation Strategies:
- **Test Validation**: [How to verify fixes don't break existing functionality]
- **Incremental Implementation**: [Steps to implement changes safely]
- **Rollback Procedures**: [How to undo changes if problems arise]

### Validation Checkpoints:
- [ ] All existing tests continue to pass
- [ ] New functionality requirements met
- [ ] Performance remains acceptable
- [ ] Integration points verified working
- [ ] No new security vulnerabilities introduced

Phase 5: Validation and Documentation

Implementation Planning

Plan the fix implementation with validation:

  • Change Sequence Planned: Know the order to make changes to minimize breakage
  • Validation Points Identified: Have checkpoints to verify each step
  • Test Execution Strategy: Plan how to validate fixes at each stage
  • Documentation Updates Required: Know what documentation needs updating
  • Team Communication Plan: Ensure stakeholders understand changes and risks

Final Context Report

Generate comprehensive context report:

echo "=== CONTEXT ANALYSIS SUMMARY ===" | tee -a $CONTEXT_REPORT

echo "## Executive Summary" >> $CONTEXT_REPORT
echo "**Analysis Completion Date**: $(date)" >> $CONTEXT_REPORT
echo "**Build Errors Analyzed**: [Number and categories]" >> $CONTEXT_REPORT
echo "**Components Affected**: [List of impacted components]" >> $CONTEXT_REPORT
echo "**Risk Level**: [High/Medium/Low with justification]" >> $CONTEXT_REPORT
echo "**Recommended Approach**: [Chosen fix strategy]" >> $CONTEXT_REPORT
echo "" >> $CONTEXT_REPORT

echo "## Key Findings:" >> $CONTEXT_REPORT
echo "- **Root Cause**: [Why build errors occurred]" >> $CONTEXT_REPORT
echo "- **Business Impact**: [Functionality at risk]" >> $CONTEXT_REPORT
echo "- **Technical Debt**: [Issues to address]" >> $CONTEXT_REPORT
echo "- **Integration Risks**: [Components that could break]" >> $CONTEXT_REPORT
echo "" >> $CONTEXT_REPORT

echo "## Next Steps:" >> $CONTEXT_REPORT
echo "1. **Implement fixes** following recommended approach" >> $CONTEXT_REPORT
echo "2. **Execute validation checkpoints** at each stage" >> $CONTEXT_REPORT
echo "3. **Run comprehensive test suite** before completion" >> $CONTEXT_REPORT
echo "4. **Update documentation** to reflect changes" >> $CONTEXT_REPORT
echo "5. **Communicate changes** to relevant stakeholders" >> $CONTEXT_REPORT

echo "" >> $CONTEXT_REPORT
echo "**Context Analysis Complete**" >> $CONTEXT_REPORT
echo "Report saved to: $CONTEXT_REPORT" | tee -a $CONTEXT_REPORT

Completion Criteria

Analysis Complete When:

  • Historical Investigation Complete: Understanding of how/why build broke
  • Test Contracts Understood: Clear picture of expected behavior
  • Dependencies Mapped: Full scope of integration impacts known
  • Risk Assessment Complete: Understand risks of different fix approaches
  • Implementation Plan Ready: Clear strategy for making changes safely
  • Validation Strategy Defined: Know how to verify fixes work correctly

Outputs Delivered:

  • Context Analysis Report: Comprehensive analysis document
  • Fix Implementation Plan: Step-by-step approach to resolving errors
  • Risk Mitigation Strategy: Plans to prevent and handle regressions
  • Validation Checklist: Tests and checkpoints for verification
  • Documentation Updates: Changes needed for accuracy

Summary

This comprehensive build context analysis ensures that developers understand the full scope and implications before attempting to fix build errors. It combines historical investigation, test analysis, dependency mapping, and risk assessment into a systematic approach that prevents regressions and preserves existing functionality.

Key Benefits:

  • Prevents blind fixes that introduce regressions
  • Preserves business logic by understanding existing functionality
  • Reduces technical debt through informed decision-making
  • Improves fix quality by considering all implications
  • Enables safe implementation through comprehensive planning

Integration Points:

  • Provides foundation for informed build error resolution
  • Feeds into implementation planning and validation strategies
  • Supports risk-based decision making for fix approaches
  • Documents context for future maintenance and development