227 lines
6.1 KiB
Markdown
227 lines
6.1 KiB
Markdown
---
|
|
title: Gap Analysis Migration Guide
|
|
description: Migration guide for existing BMAD users transitioning to automatic gap analysis in v6
|
|
---
|
|
|
|
# Gap Analysis Migration Guide
|
|
|
|
## Quick Start
|
|
|
|
**For existing BMAD users:** Gap analysis is now automatic. No changes required to your workflow!
|
|
|
|
## What Changed
|
|
|
|
### Before (BMAD v6.0.0-alpha.21 and earlier)
|
|
|
|
```
|
|
create-story → generates complete story with "verified" tasks
|
|
dev-story → blindly follows tasks as written
|
|
```
|
|
|
|
**Problem:** Tasks become stale in batch planning scenarios
|
|
|
|
### After (BMAD v6.0.0-alpha.22+)
|
|
|
|
```
|
|
create-story → generates requirements + DRAFT tasks
|
|
dev-story → validates tasks against codebase → implementation
|
|
```
|
|
|
|
**Solution:** Tasks always reflect current codebase state
|
|
|
|
## For Existing Stories
|
|
|
|
### Stories Already Created
|
|
|
|
**Option 1: No action needed**
|
|
- Gap analysis runs automatically when you use `dev-story`
|
|
- You'll be prompted to approve task updates
|
|
- Select [Y] to proceed with refinements
|
|
|
|
**Option 2: Regenerate stories** (optional)
|
|
- Delete existing story files
|
|
- Run `create-story` again
|
|
- New stories will have "DRAFT TASKS" notation
|
|
|
|
### Stories In Progress
|
|
|
|
**If you've already started development:**
|
|
- Gap analysis detects partial implementations
|
|
- Proposes tasks for remaining work only
|
|
- Use [e] Edit to manually adjust if needed
|
|
|
|
## New Workflow Steps
|
|
|
|
### When Planning (create-story)
|
|
|
|
**No changes to your workflow!** Just be aware:
|
|
- Tasks are now marked as "DRAFT"
|
|
- They'll be validated at dev-time
|
|
- This is expected behavior
|
|
|
|
### When Developing (dev-story)
|
|
|
|
**New Step 1.5 (automatic):**
|
|
|
|
1. Gap analysis runs
|
|
2. Shows findings (What Exists / What's Missing)
|
|
3. Proposes task updates
|
|
4. Waits for your approval
|
|
|
|
**Your options:**
|
|
- [Y] Yes - approve and proceed (recommended)
|
|
- [A] Auto-accept - apply + auto-accept future (automation)
|
|
- [n] No - keep draft tasks (not recommended)
|
|
- [e] Edit - manually adjust
|
|
- [s] Skip - halt development
|
|
- [r] Review - more details first
|
|
|
|
## Common Scenarios
|
|
|
|
### Scenario 1: Just-in-Time Planning
|
|
|
|
**Before:**
|
|
```bash
|
|
/create-story # Story 1.1
|
|
/dev-story # Implement immediately
|
|
```
|
|
|
|
**After:**
|
|
```bash
|
|
/create-story # Story 1.1 with DRAFT tasks
|
|
/dev-story # Gap analysis → minimal changes → implement
|
|
```
|
|
|
|
**Impact:** Minimal. Tasks stay mostly accurate.
|
|
|
|
### Scenario 2: Batch Planning (This is the game-changer!)
|
|
|
|
**Before:**
|
|
```bash
|
|
Day 1:
|
|
/create-story # Story 1.1 says "Create validation.ts"
|
|
/create-story # Story 1.2 says "Create validation.ts" (duplicate!)
|
|
|
|
Day 2:
|
|
/dev-story # Implements 1.1, creates validation.ts
|
|
/dev-story # Implements 1.2, creates validation.ts AGAIN ❌
|
|
```
|
|
|
|
**After:**
|
|
```bash
|
|
Day 1:
|
|
/create-story # Story 1.1 DRAFT: "Create validation.ts"
|
|
/create-story # Story 1.2 DRAFT: "Create validation.ts"
|
|
|
|
Day 2:
|
|
/dev-story # Gap analysis: nothing exists → creates validation.ts ✅
|
|
/dev-story # Gap analysis: validation.ts exists!
|
|
# Updated task: "Extend validation.ts" ✅
|
|
```
|
|
|
|
**Impact:** Massive! Prevents all duplicate implementations.
|
|
|
|
## For Custom Workflows
|
|
|
|
### If You've Customized create-story
|
|
|
|
**Changes you need to merge:**
|
|
1. Step labels changed (removed "EXHAUSTIVE ANALYSIS")
|
|
2. Focus shifted to requirements (not codebase scanning)
|
|
3. Tasks marked as "DRAFT" in story files
|
|
|
|
**Compatibility:** High. Changes are mostly textual.
|
|
|
|
### If You've Customized dev-story
|
|
|
|
**Changes you need to merge:**
|
|
1. New Step 1.5 (gap analysis) between Step 1 and 2
|
|
2. Step numbers shifted (old Step 2 is now Step 2, but Step 1.5 added)
|
|
3. Story file updates (Gap Analysis section, Change Log)
|
|
|
|
**Compatibility:** Medium. Review carefully if you have custom logic.
|
|
|
|
### If You've Customized Both
|
|
|
|
**Recommendation:**
|
|
1. Review changes in both workflows
|
|
2. Test with a sample story
|
|
3. Merge your customizations carefully
|
|
4. Validate with your use cases
|
|
|
|
## Rollback Instructions
|
|
|
|
If gap analysis causes issues, you can temporarily revert:
|
|
|
|
### Temporary Workaround (keep updated workflows)
|
|
|
|
When dev-story prompts for gap analysis approval:
|
|
- Select [n] No to keep original draft tasks
|
|
- Development proceeds without task refinement
|
|
|
|
### Full Rollback (revert to old workflows)
|
|
|
|
```bash
|
|
# In BMAD-METHOD repo
|
|
git checkout v6.0.0-alpha.21 -- src/modules/bmm/workflows/4-implementation/
|
|
|
|
# Reinstall in your project
|
|
cd ~/git/your-project
|
|
rm -rf _bmad
|
|
npx bmad-method@alpha install
|
|
```
|
|
|
|
**Note:** Report issues to help us improve gap analysis!
|
|
|
|
## Testing Checklist
|
|
|
|
Before fully adopting gap analysis, test these scenarios:
|
|
|
|
- [ ] **Just-in-time planning** - Create + develop story immediately
|
|
- [ ] **Batch planning** - Create 3-5 stories, develop sequentially
|
|
- [ ] **Auto-accept mode** - Use [A] option for automation
|
|
- [ ] **Edit mode** - Use [e] to manually adjust tasks
|
|
- [ ] **Existing codebase** - Develop story in project with existing code
|
|
- [ ] **Greenfield project** - Develop first story (nothing exists)
|
|
|
|
## FAQ
|
|
|
|
### Q: Do I need to regenerate existing stories?
|
|
|
|
**A:** No. Gap analysis works with any story format. It will validate tasks regardless of when the story was created.
|
|
|
|
### Q: Will this break my CI/CD pipeline?
|
|
|
|
**A:** Only if your pipeline auto-runs dev-story. Add [A] auto-accept flag or pre-approve in your automation.
|
|
|
|
### Q: Can I keep the old behavior?
|
|
|
|
**A:** Select [n] when prompted. But you'll lose the benefits of gap analysis.
|
|
|
|
### Q: What if gap analysis is wrong?
|
|
|
|
**A:** Use [e] Edit to manually correct, or [n] to keep original tasks. Also report the issue so we can improve detection.
|
|
|
|
## Getting Help
|
|
|
|
**Issues or questions?**
|
|
1. Join [Discord #general-dev](https://discord.gg/gk8jAdXWmj)
|
|
2. Open issue in [BMAD-METHOD repo](https://github.com/bmad-code-org/BMAD-METHOD)
|
|
3. Check [full gap analysis documentation](./gap-analysis.md)
|
|
|
|
## Feedback Welcome
|
|
|
|
This is a new feature in BMAD v6. We'd love your feedback!
|
|
|
|
**What we want to know:**
|
|
- Does gap analysis work correctly for your use case?
|
|
- Are the proposed task updates accurate?
|
|
- Any false positives/negatives in codebase scanning?
|
|
- Feature requests or improvements?
|
|
|
|
Share in Discord or open a GitHub issue.
|
|
|
|
---
|
|
|
|
**Gap Analysis: Keeping BMAD stories grounded in reality since v6.0.0-alpha.22**
|