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/src/modules/bmm/workflows/4-implementation/create-story-with-gap-analysis/README.md

5.0 KiB
Raw Blame History

Create Story With Gap Analysis

Custom Workflow by Jonah Schulte Created: December 24, 2025 Purpose: Generate stories with SYSTEMATIC codebase gap analysis (not inference-based)

Problem This Solves

Standard /create-story workflow:

  • ❌ Reads previous stories and git commits (passive)
  • ❌ Infers what probably exists (guessing)
  • ❌ Gap analysis quality varies by agent thoroughness
  • ❌ Checkboxes may not reflect reality

This custom workflow:

  • ✅ Actively scans codebase with Glob/Read tools
  • ✅ Verifies file existence (not inference)
  • ✅ Reads key files to check implementation depth (mocked vs real)
  • ✅ Generates TRUTHFUL gap analysis
  • ✅ Checkboxes are FACTS verified by file system

Usage

/create-story-with-gap-analysis

# Or via Skill tool:
Skill: "create-story-with-gap-analysis"
Args: "1.9" (epic.story number)

Workflow will:

  1. Load existing story + epic context
  2. SCAN codebase systematically (Glob for files, Read to verify implementation)
  3. Generate gap analysis with verified ✅/❌/⚠️ status
  4. Update story file with truthful checkboxes
  5. Save to docs/sprint-artifacts/

What It Scans

For each story, the workflow:

  1. Identifies target directories (from story title/requirements)

    • Example: "admin-user-service" → apps/backend/admin-user-service/

  2. Globs for all files

    • {target}/src/**/*.ts - Find all TypeScript files
    • {target}/src/**/*.spec.ts - Find all tests

  3. Checks specific required files

    • Based on ACs, check if files exist
    • Example: src/auth/controllers/bridgeid-auth.controller.ts → ❌ MISSING

  4. Reads key files to verify depth

    • Check if mocked: Search for "MOCK" string
    • Check if incomplete: Search for "TODO"
    • Verify real implementation exists

  5. Checks package.json

    • Verify required dependencies are installed
    • Identify missing packages

  6. Counts tests

    • How many test files exist
    • Coverage for each component

Output Format

Generates story with:

  1. ✅ Standard BMAD 5 sections (Story, AC, Tasks, Dev Notes, Dev Agent Record)

  2. ✅ Enhanced Dev Notes with verified gap analysis subsections:

    • Gap Analysis: Current State vs Requirements
    • Library/Framework Requirements (from package.json)
    • File Structure Requirements (from Glob results)
    • Testing Requirements (from test file count)
    • Architecture Compliance
    • Previous Story Intelligence

  3. ✅ Truthful checkboxes based on verified file existence

Difference from Standard /create-story

Feature /create-story /create-story-with-gap-analysis
Reads previous story ✅ ✅
Reads git commits ✅ ✅
Loads epic context ✅ ✅
Scans codebase with Glob ❌ ✅ SYSTEMATIC
Verifies files exist ❌ ✅ VERIFIED
Reads files to check depth ❌ ✅ MOCKED vs REAL
Checks package.json ❌ ✅ DEPENDENCIES
Counts test coverage ❌ ✅ COVERAGE
Gap analysis quality Variable (agent-dependent) Systematic (tool-verified)
Checkbox accuracy Inference-based File-existence-based

When to Use

This workflow (planning-time gap analysis):

  • Use when regenerating/auditing stories
  • Use when you want verified checkboxes upfront
  • Best for stories that will be implemented immediately
  • Manual verification at planning time

Standard /create-story + /dev-story (dev-time gap analysis):

  • Recommended for most workflows
  • Stories start as DRAFT, validated when dev begins
  • Prevents staleness in batch planning
  • Automatic verification at development time

Use standard /create-story when:

  • Greenfield project (nothing exists yet)
  • Backlog stories (won't be implemented for months)
  • Epic planning phase (just sketching ideas)

Tip: Both approaches are complementary. You can use this workflow to regenerate stories, then use /dev-story which will re-validate at dev-time.

Examples

Regenerating Story 1.9:

/create-story-with-gap-analysis

Choice: 1.9

# Workflow will:
# 1. Load existing 1-9-admin-user-service-bridgeid-rbac.md
# 2. Identify target: apps/backend/admin-user-service/
# 3. Glob: apps/backend/admin-user-service/src/**/*.ts (finds 47 files)
# 4. Check: src/auth/controllers/bridgeid-auth.controller.ts → ❌ MISSING
# 5. Read: src/bridgeid/services/bridgeid-client.service.ts → ⚠️ MOCKED
# 6. Read: package.json → axios ❌ NOT INSTALLED
# 7. Generate gap analysis with verified status
# 8. Write story with truthful checkboxes

Result: Story with verified gap analysis showing:

  • ✅ 7 components IMPLEMENTED (verified file existence)
  • ❌ 6 components MISSING (verified file not found)
  • ⚠️ 1 component PARTIAL (file exists but contains "MOCK")

Installation

This workflow is auto-discovered when BMAD is installed.

To use:

/bmad:bmm:workflows:create-story-with-gap-analysis

Last Updated: December 27, 2025 Status: Integrated into BMAD-METHOD