6.1 KiB

Raw Blame History

title	description
Gap Analysis Migration Guide	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):

Gap analysis runs
Shows findings (What Exists / What's Missing)
Proposes task updates
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:

/create-story  # Story 1.1
/dev-story     # Implement immediately

After:

/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:

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:

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:

Step labels changed (removed "EXHAUSTIVE ANALYSIS")
Focus shifted to requirements (not codebase scanning)
Tasks marked as "DRAFT" in story files

Compatibility: High. Changes are mostly textual.

If You've Customized dev-story

Changes you need to merge:

New Step 1.5 (gap analysis) between Step 1 and 2
Step numbers shifted (old Step 2 is now Step 2, but Step 1.5 added)
Story file updates (Gap Analysis section, Change Log)

Compatibility: Medium. Review carefully if you have custom logic.

If You've Customized Both

Recommendation:

Review changes in both workflows
Test with a sample story
Merge your customizations carefully
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)

# 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?

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

6.1 KiB Raw Blame History