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/.patch/827/plan.md

9.2 KiB
Raw Blame History

PR #827 Investigation Plan

Created: 2025-10-28
PR: https://github.com/bmad-code-org/BMAD-METHOD/pull/827
Issue: Incomplete v5 to v6 reference updates

Objective

Validate and complete the v5 → v6 reference updates started in PR #827, ensuring all incorrect v5 references are changed to v6 while preserving intentional version markers.

Problem Statement

Current State:

  • PR #827 claims to change "all references to v5 to instead be v6"
  • PR only modifies 15 files (138 line changes)
  • Codebase search reveals 100+ v5 references remain
  • Contributor tested convert-legacy workflow and found v5 references in output

Root Cause:

  • Incomplete find/replace operation
  • Some files were missed in the original search
  • Possible scope limitation not communicated

Expected State:

  • All documentation v5 references → v6 (except intentional version markers)
  • Consistent versioning across bmad/ and src/ directories
  • CHANGELOG.md preserved for historical accuracy where appropriate

Investigation Strategy

Phase 1: Comprehensive Search & Categorization (1 hour)

Goal: Identify ALL v5 references and categorize them

Tasks:

  1. Download PR #827 patch file for offline analysis
  2. Apply patch to test branch to see exact changes
  3. Search entire codebase for \bv5\b pattern
  4. Categorize each v5 reference:
    • Type A: Intentional version markers (CHANGELOG.md [v5.0.0] - SKIPPED)
    • Type B: Documentation that should be v6 (conversion guides, footers)
    • Type C: Already fixed by PR (verify patch application)
    • Type D: Code/config requiring different handling
  5. Create comprehensive inventory spreadsheet

Success Criteria:

  • Complete list of all v5 references with file paths and line numbers
  • Each reference categorized by type
  • Clear distinction between "needs fixing" vs "keep as-is"

Phase 2: Pattern Analysis & Test Design (1 hour)

Goal: Understand patterns and design tests to validate changes

Tasks:

  1. Analyze common v5 reference patterns:
    • v4 to v5 (should be v4 to v6)
    • v5 compliant (should be v6 compliant)
    • v5 architecture (should be v6 architecture)
    • Part of the BMad Method v5 (should be v6)
    • v5.0.0 (context-dependent - CHANGELOG vs version history)
  2. Design grep-based tests to find each pattern
  3. Create validation script to verify no unintended v5 references remain
  4. Design test for bmad/ and src/ synchronization
  5. Document edge cases requiring manual review

Success Criteria:

  • Test script that can find all v5 references by pattern
  • Validation logic for intentional vs accidental v5 references
  • Clear test cases for post-fix validation

Phase 3: Fix Development (2 hours)

Goal: Create comprehensive fix covering all missed references

Tasks:

  1. Create fix script or manual change list:

    • Option A: Automated sed/PowerShell script for bulk replacement
    • Option B: Manual git patch file with all changes
    • Option C: File-by-file replacement with verification

  2. Handle each category:

    • Type A (Keep): Document why these remain (CHANGELOG version marker)
    • Type B (Fix): Apply v5 → v6 replacement
    • Type C (Verify): Confirm PR already handles these
    • Type D (Manual): Case-by-case assessment

  3. Address specific files:

    • CHANGELOG.md: Keep [v5.0.0] - SKIPPED but fix accidental v5 in line 19
    • convert-legacy/*: Comprehensive v5 → v6 in all documentation
    • Module footers: Update all "Part of BMad Method v5" → "v6"
    • Version history: Change v5.0.0 → v6.0.0 where appropriate

  4. Maintain bmad/ and src/ synchronization:

    • Ensure both directories receive identical updates
    • Verify no drift between the two

Success Criteria:

  • All Type B references converted to v6
  • Type A references documented and preserved
  • bmad/ and src/ remain synchronized
  • Changes ready for testing

Phase 4: Test Execution (1 hour)

Goal: Validate fix completeness and correctness

Tasks:

  1. Run automated tests:

    • Execute grep search for remaining \bv5\b references
    • Verify only intentional v5 references remain
    • Check bmad/ and src/ synchronization
    • Validate no broken references introduced

  2. Manual validation:

    • Review CHANGELOG.md for historical accuracy
    • Check convert-legacy workflow documentation
    • Verify module footers updated
    • Confirm version history entries

  3. Regression testing:

    • Run npm run format:check to verify no style issues
    • Run npm run lint to check for any broken references
    • Run npm test if applicable
    • Verify no unintended changes to code files

  4. Documentation review:

    • Ensure all v6 references make contextual sense
    • Verify no v4 → v5 → v6 inconsistencies
    • Check that "skipping v5" narrative is consistent

Success Criteria:

  • Zero unintended v5 references found
  • All intentional v5 references documented
  • All tests pass
  • No regressions introduced

Phase 5: PR Review & Recommendation (30 minutes)

Goal: Formulate clear recommendation for PR #827

Tasks:

  1. Assess PR completeness:

    • Compare PR changes vs. our comprehensive fix
    • Identify what PR got right
    • Document what PR missed

  2. Formulate recommendation:

    • Option A: Request changes - list all missed references
    • Option B: Approve with follow-up - suggest companion PR
    • Option C: Offer to expand - propose taking over completion

  3. Draft PR review comment:

    • Thank contributor for finding the issue
    • Acknowledge the work done (15 files is significant)
    • Explain the gap (100+ references, only 15 files addressed)
    • Provide complete list of remaining v5 references
    • Offer specific fix recommendations or patch file
    • Address testing documentation concern raised by contributor

  4. Prepare artifacts:

    • Complete v5 reference inventory
    • Patch file with all needed changes (if offering to complete)
    • Test validation script
    • Updated PR summary

Success Criteria:

  • Clear, constructive PR review comment
  • Specific list of all missed references
  • Actionable recommendations for contributor
  • Option to complete the work if contributor prefers

Phase 6: Application & Cleanup (30 minutes)

Goal: Apply fix and clean up workspace

Tasks:

  1. If applying fix ourselves:

    • Commit all changes to patch-827 branch
    • Run final validation tests
    • Push to fork or create patch file
    • Post as PR comment or new PR

  2. If requesting contributor changes:

    • Post review comment with complete list
    • Offer to assist or take over if needed
    • Monitor for contributor response

  3. Workspace cleanup:

    • Document all findings in .patch/827/
    • Archive test scripts and validation results
    • Revert to v6-alpha branch
    • Preserve all investigation artifacts

Success Criteria:

  • Fix applied (ourselves or by contributor)
  • All artifacts preserved in .patch/827/
  • Workspace clean and on v6-alpha
  • PR #827 has clear path forward

Resource Estimates

Phase Description Estimated Time
1 Comprehensive Search & Categorization 1 hour
2 Pattern Analysis & Test Design 1 hour
3 Fix Development 2 hours
4 Test Execution 1 hour
5 PR Review & Recommendation 30 minutes
6 Application & Cleanup 30 minutes
Total 6 hours

Risk Assessment

Low Risk

  • Text-only changes in documentation files
  • No code logic affected
  • Easily reversible changes
  • Clear pattern matching

Medium Risk

  • Large number of files to modify (potentially 50+ files)
  • bmad/ and src/ synchronization complexity
  • Contributor may have scope limitation we're not aware of

Mitigation Strategies

  • Comprehensive testing before application
  • Preserve original PR scope in review (don't just take over)
  • Offer collaboration rather than replacement
  • Document every change for transparency

Success Metrics

  1. Completeness: 100% of unintentional v5 references converted to v6
  2. Accuracy: 100% of intentional v5 references preserved (CHANGELOG markers)
  3. Consistency: bmad/ and src/ remain synchronized
  4. Quality: All tests pass, no regressions
  5. Collaboration: Contributor feels supported, not undermined

Deliverables

  1. Complete v5 reference inventory (.patch/827/v5-references-inventory.md)
  2. Test validation script (.patch/827/validate-v5-fix.ps1 or similar)
  3. Comprehensive fix patch (.patch/827/complete-v5-to-v6.patch)
  4. PR review comment (.patch/827/PR-827-review-comment.md)
  5. Final investigation report (.patch/827/final-summary.md)

Next Steps

  1. Begin Phase 1: Download patch and run comprehensive search
  2. Create v5 reference inventory with categorization
  3. Proceed through phases systematically
  4. Make decision on PR recommendation at Phase 5

Status: PLAN CREATED - Ready to begin Phase 1