302 lines
9.2 KiB
Markdown
302 lines
9.2 KiB
Markdown
# 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
|