# TODO List for PR #827 Investigation **PR:** #827 - Fix: Update references to 'v5' to be 'v6' **Created:** 2025-10-28 **Type:** Incomplete documentation update - requires expansion --- ## Phase 1: Comprehensive Search & Categorization ### 1.1 Gather PR Context - [x] **1.1.1** Download PR #827 details from GitHub API - [x] **1.1.2** Create PR-827-Summary.md with basic info - [x] **1.1.3** Save PR conversation (currently empty) - [x] **1.1.4** Download PR patch file (.patch) for offline analysis - [x] **1.1.5** Review PR description and contributor's testing notes ### 1.2 Apply and Analyze PR Changes - [x] **1.2.1** Create test branch from v6-alpha (pr-827-test) - [x] **1.2.2** Apply PR #827 patch to test branch (FAILED - outdated) - [x] **1.2.3** Review exact files modified by the patch (658 files discovered) - [x] **1.2.4** Document what the PR successfully changes (patch-analysis.md created) - [x] **1.2.5** Identify scope of PR's changes vs claims (COMPLETE - comprehensive but outdated) ### 1.3 Comprehensive Codebase Search - [x] **1.3.1** Search entire codebase for `\bv5\b` pattern (443 matches in 44 files) - [x] **1.3.2** Export grep results to structured format (CSV created) - [x] **1.3.3** Group results by file type (.md=432, .js=9, .yaml=2) - [x] **1.3.4** Group results by directory (documented in inventory) - [x] **1.3.5** Count total v5 references per file (443 total) ### 1.4 Categorize Each v5 Reference - [x] **1.4.1** Create v5-references-inventory.md template - [x] **1.4.2** Review each v5 reference and categorize: - [x] Type A: Intentional version markers (CHANGELOG - keep as-is) - [x] Type B: Documentation needing v6 update (~432 refs) - [x] Type C: Already fixed by PR #827 (N/A - PR outdated) - [x] Type D: Code/config requiring special handling (11 refs: 9 JS + 2 YAML) - [x] **1.4.3** Document reasoning for each categorization (in inventory) - [x] **1.4.4** Flag any ambiguous cases for manual review (Type D flagged) ### 1.5 Analyze bmad/ vs src/ Duplication - [x] **1.5.1** Identify which files exist in both bmad/ and src/ - [x] **1.5.2** Verify if v5 references are identical in duplicates - [x] **1.5.3** Determine if duplication is intentional (appears to be mirrors) - [x] **1.5.4** Document synchronization requirements (both need updates) **Phase 1 Completion Criteria:** - [x] Complete inventory of all v5 references with categories - [x] Clear understanding of PR scope vs total scope (PR: 658 files Oct 2025, Current: 44 files) - [x] Documentation of bmad/src relationship (mirrors - both need fixing) --- ## Phase 2: Pattern Analysis & Test Design ### 2.1 Extract Common Patterns - [ ] **2.1.1** List all unique v5 reference patterns found - [ ] **2.1.2** Group by context (conversion, compliance, versioning, footers) - [ ] **2.1.3** Identify regex patterns for each type - [ ] **2.1.4** Document edge cases (v5.0.0 vs v5 compliant) ### 2.2 Design Detection Tests - [ ] **2.2.1** Create grep test for "v4 to v5" pattern - [ ] **2.2.2** Create grep test for "v5 compliant" pattern - [ ] **2.2.3** Create grep test for "v5 architecture/conventions/patterns" - [ ] **2.2.4** Create grep test for footer "Part of BMad Method v5" - [ ] **2.2.5** Create grep test for version "v5.0.0" - [ ] **2.2.6** Create grep test for "v5-specific" references ### 2.3 Design Validation Tests - [ ] **2.3.1** Write script to find all remaining v5 references - [ ] **2.3.2** Write script to verify bmad/ and src/ synchronization - [ ] **2.3.3** Write script to check for broken references after replacement - [ ] **2.3.4** Design test for CHANGELOG.md historical accuracy - [ ] **2.3.5** Create checklist for manual validation ### 2.4 Create Test Scripts - [ ] **2.4.1** Create validate-v5-references.ps1 (PowerShell) - [ ] **2.4.2** Add function: Find-V5References - [ ] **2.4.3** Add function: Test-CategoryA-Preserved (intentional markers) - [ ] **2.4.4** Add function: Test-CategoryB-Fixed (documentation) - [ ] **2.4.5** Add function: Test-BmadSrcSync - [ ] **2.4.6** Add comprehensive test output formatting ### 2.5 Document Edge Cases - [ ] **2.5.1** Document CHANGELOG.md "[v5.0.0] - SKIPPED" (keep) - [ ] **2.5.2** Document any code comments referencing v5 historically - [ ] **2.5.3** Document version history entries (context-dependent) - [ ] **2.5.4** Flag any external references or URLs with v5 **Phase 2 Completion Criteria:** - [ ] Test script created and functional - [ ] All patterns documented with regex - [ ] Edge cases clearly identified --- ## Phase 3: Fix Development ### 3.1 Create Fix Strategy - [ ] **3.1.1** Decide on fix method (automated script vs manual vs patch) - [ ] **3.1.2** Create fix execution plan with file-by-file approach - [ ] **3.1.3** Identify files requiring manual review - [ ] **3.1.4** Plan bmad/ and src/ synchronization approach ### 3.2 Handle Category A (Keep As-Is) - [ ] **3.2.1** Document CHANGELOG.md "[v5.0.0] - SKIPPED" preservation - [ ] **3.2.2** Verify no accidental changes to intentional markers - [ ] **3.2.3** Create whitelist of approved v5 references ### 3.3 Fix Category B (Documentation Updates) - [ ] **3.3.1** Fix all "v4 to v5" → "v4 to v6" in convert-legacy - [ ] **3.3.2** Fix all "v5 compliant" → "v6 compliant" - [ ] **3.3.3** Fix all "v5 architecture" → "v6 architecture" - [ ] **3.3.4** Fix all "v5 conventions" → "v6 conventions" - [ ] **3.3.5** Fix all "v5 patterns" → "v6 patterns" - [ ] **3.3.6** Fix all "v5 structure" → "v6 structure" - [ ] **3.3.7** Fix all footers "Part of BMad Method v5" → "v6" - [ ] **3.3.8** Fix version history "v5.0.0" → "v6.0.0" (where appropriate) ### 3.4 Fix Specific Files - [ ] **3.4.1** CHANGELOG.md line 19: Fix "from v5 to modules in v5" - [ ] **3.4.2** bmad/bmb/workflows/convert-legacy/README.md (all v5 refs) - [ ] **3.4.3** bmad/bmb/workflows/convert-legacy/checklist.md (all v5 refs) - [ ] **3.4.4** bmad/bmb/workflows/convert-legacy/instructions.md (all v5 refs) - [ ] **3.4.5** bmad/bmb/workflows/convert-legacy/workflow.yaml - [ ] **3.4.6** src/ mirrors of above files (maintain sync) - [ ] **3.4.7** All module README footers still showing v5 - [ ] **3.4.8** Any other files identified in inventory ### 3.5 Create Fix Artifacts - [ ] **3.5.1** Generate complete-v5-to-v6.patch file - [ ] **3.5.2** Create before/after diff summary - [ ] **3.5.3** Document all changes made - [ ] **3.5.4** Verify bmad/ and src/ receive identical changes **Phase 3 Completion Criteria:** - [ ] All Category B references fixed - [ ] Category A references preserved - [ ] Patch file created - [ ] bmad/ and src/ synchronized --- ## Phase 4: Test Execution ### 4.1 Run Automated Tests - [ ] **4.1.1** Execute validate-v5-references.ps1 script - [ ] **4.1.2** Verify only whitelisted v5 references remain - [ ] **4.1.3** Check bmad/ and src/ synchronization - [ ] **4.1.4** Grep for any new v5 references accidentally introduced - [ ] **4.1.5** Verify no broken internal links (v5 → v6 paths) ### 4.2 Run Repository Tests - [ ] **4.2.1** Run `npm run format:check` for style compliance - [ ] **4.2.2** Run `npm run lint` for any issues - [ ] **4.2.3** Run `npm test` if applicable - [ ] **4.2.4** Run `npm run validate:schemas` for YAML validation ### 4.3 Manual Validation - [ ] **4.3.1** Review CHANGELOG.md - verify historical accuracy maintained - [ ] **4.3.2** Review convert-legacy workflow docs - check all v5 → v6 - [ ] **4.3.3** Review module footers - verify all updated to v6 - [ ] **4.3.4** Check version history entries - ensure consistency - [ ] **4.3.5** Spot check 5-10 files for contextual accuracy ### 4.4 Regression Testing - [ ] **4.4.1** Verify no code files accidentally modified - [ ] **4.4.2** Check no config files broken - [ ] **4.4.3** Ensure no agent YAML files affected - [ ] **4.4.4** Confirm documentation formatting preserved ### 4.5 Document Test Results - [ ] **4.5.1** Create test-results.md with pass/fail for each test - [ ] **4.5.2** Document any remaining v5 references with justification - [ ] **4.5.3** List any edge cases requiring manual review - [ ] **4.5.4** Summarize regression test results **Phase 4 Completion Criteria:** - [ ] All automated tests pass - [ ] All manual validation complete - [ ] Zero unintended v5 references - [ ] No regressions introduced --- ## Phase 5: PR Review & Recommendation ### 5.1 Assess PR Completeness - [ ] **5.1.1** Compare PR #827 changes vs our comprehensive fix - [ ] **5.1.2** List what PR got right (15 files successfully updated) - [ ] **5.1.3** List what PR missed (remaining v5 references) - [ ] **5.1.4** Calculate coverage: PR changes / total needed changes - [ ] **5.1.5** Assess if PR scope was intentionally limited ### 5.2 Formulate Recommendation - [ ] **5.2.1** Decide on recommendation type: - [ ] Option A: REQUEST CHANGES with complete list - [ ] Option B: APPROVE with follow-up companion PR - [ ] Option C: COMMENT with offer to complete - [ ] **5.2.2** Draft rationale for chosen recommendation - [ ] **5.2.3** Prepare list of specific changes needed - [ ] **5.2.4** Consider contributor's time/expertise ### 5.3 Draft PR Review Comment - [ ] **5.3.1** Thank contributor for finding and addressing v5 issue - [ ] **5.3.2** Acknowledge work done (15 files is significant effort) - [ ] **5.3.3** Explain gap diplomatically (100+ refs, 15 files addressed) - [ ] **5.3.4** Provide complete inventory of remaining v5 references - [ ] **5.3.5** Offer specific fix recommendations or patch file - [ ] **5.3.6** Address contributor's testing documentation concern - [ ] **5.3.7** Offer to help complete if contributor prefers ### 5.4 Prepare Supporting Artifacts - [ ] **5.4.1** Attach v5-references-inventory.md - [ ] **5.4.2** Attach complete-v5-to-v6.patch (if offering) - [ ] **5.4.3** Attach validate-v5-references.ps1 script - [ ] **5.4.4** Create PR-827-review-comment.md ### 5.5 Address Testing Documentation Issue - [ ] **5.5.1** Investigate contributor's claim about missing pre-release script - [ ] **5.5.2** Check CONTRIBUTING.md for outdated testing instructions - [ ] **5.5.3** Verify current testing process in package.json - [ ] **5.5.4** Consider separate issue for documentation update **Phase 5 Completion Criteria:** - [ ] Clear recommendation formulated - [ ] Constructive review comment drafted - [ ] All supporting artifacts prepared - [ ] Testing documentation issue addressed --- ## Phase 6: Application & Cleanup ### 6.1 Apply Fix (If Doing It Ourselves) - [ ] **6.1.1** Commit all changes to patch-827 branch - [ ] **6.1.2** Write comprehensive commit message - [ ] **6.1.3** Run final validation tests - [ ] **6.1.4** Create patch file for PR comment - [ ] **6.1.5** Decide: push to fork vs attach to comment ### 6.2 Post Review (If Requesting Contributor Changes) - [ ] **6.2.1** Post review comment to PR #827 - [ ] **6.2.2** Attach inventory and patch file - [ ] **6.2.3** Set review status (REQUEST CHANGES, COMMENT, or APPROVE) - [ ] **6.2.4** Monitor for contributor response ### 6.3 Archive Investigation Artifacts - [ ] **6.3.1** Save all created files to `.patch/827/` - [ ] **6.3.2** Save test scripts and validation results - [ ] **6.3.3** Create final-summary.md with complete investigation - [ ] **6.3.4** Document lessons learned ### 6.4 Workspace Cleanup - [ ] **6.4.1** Delete pr-827-test branch (if created) - [ ] **6.4.2** Checkout v6-alpha branch - [ ] **6.4.3** Verify .patch/827/ preserved - [ ] **6.4.4** Run git status to ensure clean workspace ### 6.5 Follow-up Actions - [ ] **6.5.1** Create issue for CONTRIBUTING.md testing docs update (if needed) - [ ] **6.5.2** Monitor PR #827 for contributor response - [ ] **6.5.3** Offer additional help if contributor has questions - [ ] **6.5.4** Re-review when changes applied **Phase 6 Completion Criteria:** - [ ] Fix applied or review posted - [ ] All artifacts archived - [ ] Workspace clean - [ ] Follow-up plan established --- ## Quick Reference **Current Status:** Phase 1 partially complete - [x] PR details gathered - [x] Initial codebase search complete (100+ v5 refs found) - [ ] Patch not yet downloaded/applied - [ ] Inventory not yet categorized **Next Immediate Tasks:** 1. Download and apply PR #827 patch 2. Create complete v5 reference inventory 3. Categorize each reference (A/B/C/D) **Key Files to Create:** - [ ] `.patch/827/v5-references-inventory.md` - [ ] `.patch/827/validate-v5-references.ps1` - [ ] `.patch/827/complete-v5-to-v6.patch` - [ ] `.patch/827/PR-827-review-comment.md` - [ ] `.patch/827/test-results.md` - [ ] `.patch/827/final-summary.md` **Decision Points:** - [ ] Phase 2: Automated vs manual fix approach - [ ] Phase 5: REQUEST CHANGES vs APPROVE vs COMMENT - [ ] Phase 6: Complete ourselves vs guide contributor --- ## Notes - **Contributor Insight:** @davedittrich tested convert-legacy workflow and found v5 refs in output - good testing approach - **Testing Gap:** Contributor couldn't validate using CONTRIBUTING.md instructions (pre-release script missing) - separate issue? - **PR Intent:** Contributor used Claude Code for find/replace - may not have caught all instances - **Scope Clarity:** PR description says "all references" but only changed 15 files - need to clarify if scope was intentional --- **Status:** TODO LIST CREATED - Ready to begin Phase 1.4 (Categorization)