BMAD-METHOD/bmad/bmm/docs/troubleshooting.md

# BMM Troubleshooting Guide

Common issues and solutions for the BMad Method Module.

---

## Quick Diagnosis

**Use this flowchart to find your issue:**

```mermaid
flowchart TD
    START{What's the problem?}

    START -->|Can't get started| SETUP[Setup & Installation Issues]
    START -->|Wrong level detected| LEVEL[Level Detection Problems]
    START -->|Workflow not working| WORKFLOW[Workflow Issues]
    START -->|Agent lacks context| CONTEXT[Context & Documentation Issues]
    START -->|Implementation problems| IMPL[Implementation Issues]
    START -->|Files/paths wrong| FILES[File & Path Issues]

    style START fill:#ffb,stroke:#333,stroke-width:2px
    style SETUP fill:#bfb,stroke:#333,stroke-width:2px
    style LEVEL fill:#bbf,stroke:#333,stroke-width:2px
    style WORKFLOW fill:#fbf,stroke:#333,stroke-width:2px
    style CONTEXT fill:#f9f,stroke:#333,stroke-width:2px
```

---

## Table of Contents

- [Setup & Installation Issues](#setup--installation-issues)
- [Level Detection Problems](#level-detection-problems)
- [Workflow Issues](#workflow-issues)
- [Context & Documentation Issues](#context--documentation-issues)
- [Implementation Issues](#implementation-issues)
- [File & Path Issues](#file--path-issues)
- [Agent Behavior Issues](#agent-behavior-issues)
- [Integration Issues (Brownfield)](#integration-issues-brownfield)

---

## Setup & Installation Issues

### Problem: BMM not found after installation

**Symptoms:**

- `bmad` command not recognized
- Agent files not accessible
- Workflows don't load

**Solution:**

```bash
# Check if BMM is installed
ls bmad/

# If not present, run installer
npx bmad-method@alpha install

# For fresh install
npx bmad-method@alpha install --skip-version-prompt
```

### Problem: Agents don't have menu

**Symptoms:**

- Load agent file but no menu appears
- Agent doesn't respond to commands

**Solution:**

1. Ensure you're loading the correct agent file path: `bmad/bmm/agents/[agent-name].md`
2. Wait a few seconds for agent to initialize
3. Try asking "show menu" or "help"
4. Check IDE supports Markdown rendering with context
5. For Claude Code: Ensure agent file is open in chat context

### Problem: Workflows not found

**Symptoms:**

- Agent says workflow doesn't exist
- Menu shows workflow but won't run

**Solution:**

1. Check workflow exists: `ls bmad/bmm/workflows/`
2. Verify agent has access to workflow (check agent's workflow list)
3. Try using menu number instead of workflow name
4. Restart chat with agent in fresh session

---

## Level Detection Problems

### Problem: workflow-init suggests wrong level

**Symptoms:**

- Detects Level 3 but you only need Level 1
- Suggests Level 1 but project is actually Level 2
- Can't figure out appropriate level

**Solution:**

1. **Override the suggestion** - workflow-init always asks for confirmation, just say "no" and choose correct level
2. **Be specific in description** - Use level keywords when describing:
   - "fix bug" → Level 0
   - "add small feature" → Level 1
   - "build dashboard" → Level 2
3. **Manual override** - You can always switch levels later if needed

**Example:**

```
workflow-init: "Level 3 project?"
You: "No, this is just adding OAuth login - Level 1"
workflow-init: "Got it, creating Level 1 workflow"
```

### Problem: Project level unclear

**Symptoms:**

- Between Level 1 and Level 2
- Not sure if architecture needed
- Story count uncertain

**Solution:**
**When in doubt, start smaller:**

- Choose Level 1 instead of Level 2
- You can always run `create-prd` later if needed
- Level 1 is faster, less overhead
- Easy to upgrade, hard to downgrade

**Decision criteria:**

- Single epic with related stories? → Level 1
- Multiple independent epics? → Level 2
- Need product-level planning? → Level 2
- Just need technical plan? → Level 1

### Problem: Old planning docs influencing level detection

**Symptoms:**

- Old Level 3 PRD in folder
- Working on new Level 0 bug fix
- workflow-init suggests Level 3

**Solution:**
workflow-init asks: "Is this work in progress or previous effort?"

- Answer: "Previous effort"
- Then describe your NEW work clearly
- System will detect level based on NEW work, not old artifacts

---

## Workflow Issues

### Problem: Workflow fails or hangs

**Symptoms:**

- Workflow starts but doesn't complete
- Agent stops responding mid-workflow
- Progress stalls

**Solution:**

1. **Check context limits** - Start fresh chat for complex workflows
2. **Verify prerequisites**:
   - Phase 2 needs Phase 1 complete (if used)
   - Phase 3 needs Phase 2 complete
   - Phase 4 needs Phase 3 complete (if Level 3-4)
3. **Restart workflow** - Load agent in new chat and restart
4. **Check status file** - Verify `bmm-workflow-status.md` or `sprint-status.yaml` is present and valid

### Problem: Agent says "workflow not found"

**Symptoms:**

- Request workflow by name
- Agent doesn't recognize it
- Menu doesn't show workflow

**Solution:**

1. Check spelling/format - Use exact workflow name or menu shortcut (*prd not *PRD)
2. Verify agent has workflow:
   - PM agent: prd, tech-spec
   - Architect agent: create-architecture, validate-architecture
   - SM agent: sprint-planning, create-story, story-context
3. Try menu number instead of name
4. Check you're using correct agent for workflow

### Problem: Sprint-planning workflow fails

**Symptoms:**

- Can't create sprint-status.yaml
- Epics not extracted from files
- Status file empty or incorrect

**Solution:**

1. **Verify epic files exist**:
   - Level 1: tech-spec with epic
   - Level 2-4: epics.md or sharded epic files
2. **Check file format**:
   - Epic files should be valid Markdown
   - Epic headers should be clear (## Epic Name)
3. **Run in Phase 4 only** - Ensure Phase 2/3 complete first
4. **Check file paths** - Epic files should be in correct output folder

### Problem: story-context generates empty or wrong context

**Symptoms:**

- Context file created but has no useful content
- Context doesn't reference existing code
- Missing technical guidance

**Solution:**

1. **Run epic-tech-context first** - story-context builds on epic context
2. **Check story file exists** - Verify story was created by create-story
3. **For brownfield**:
   - Ensure document-project was run
   - Verify docs/index.md exists with codebase context
4. **Try regenerating** - Sometimes needs fresh attempt with more specific story details

---

## Context & Documentation Issues

### Problem: AI agents lack codebase understanding (Brownfield)

**Symptoms:**

- Suggestions don't align with existing patterns
- Ignores available components
- Proposes approaches that conflict with architecture
- Doesn't reference existing code

**Solution:**

1. **Run document-project** - Critical for brownfield projects
   ```
   Load Analyst agent → run document-project
   Choose scan level: Deep (recommended for PRD prep)
   ```
2. **Verify docs/index.md exists** - This is master entry point for AI agents
3. **Check documentation completeness**:
   - Review generated docs/index.md
   - Ensure key systems are documented
4. **Run deep-dive on specific areas** if needed

### Problem: Have documentation but agents can't find it

**Symptoms:**

- README.md, ARCHITECTURE.md exist
- AI agents still ask questions answered in docs
- No docs/index.md file

**Solution:**
**Option 1: Quick fix (2-5min)**
Run `index-docs` task:

- Located at `bmad/core/tasks/index-docs.xml`
- Scans existing docs and generates index.md
- Lightweight, just creates navigation

**Option 2: Comprehensive (10-30min)**
Run document-project workflow:

- Discovers existing docs in Step 2
- Generates NEW AI-friendly documentation from codebase
- Creates index.md linking to BOTH existing and new docs

**Why this matters:** AI agents need structured entry point (index.md) to navigate docs efficiently.

### Problem: document-project takes too long

**Symptoms:**

- Exhaustive scan running for hours
- Impatient to start planning

**Solution:**
**Choose appropriate scan level:**

- **Quick (2-5min)** - Pattern analysis, no source reading - Good for initial overview
- **Deep (10-30min)** - Reads critical paths - **Recommended for most brownfield projects**
- **Exhaustive (30-120min)** - Reads all files - Only for migration planning or complete understanding

For most brownfield projects, **Deep scan is sufficient**.

---

## Implementation Issues

### Problem: Existing tests breaking (Brownfield)

**Symptoms:**

- Regression test failures
- Previously working functionality broken
- Integration tests failing

**Solution:**

1. **Review changes against existing patterns**:
   - Check if new code follows existing conventions
   - Verify API contracts unchanged (unless intentionally versioned)
2. **Run test-review workflow** (TEA agent):
   - Analyzes test coverage
   - Identifies regression risks
   - Suggests fixes
3. **Add regression testing to DoD**:
   - All existing tests must pass
   - Add integration tests for new code
4. **Consider feature flags** for gradual rollout

### Problem: Story takes much longer than estimated

**Symptoms:**

- Story estimated 4 hours, took 12 hours
- Acceptance criteria harder than expected
- Hidden complexity discovered

**Solution:**
**This is normal!** Estimates are estimates. To handle:

1. **Continue until DoD met** - Don't compromise quality
2. **Document learnings in retrospective**:
   - What caused the overrun?
   - What should we watch for next time?
3. **Consider splitting story** if it's truly two stories
4. **Adjust future estimates** based on this data

**Don't stress about estimate accuracy** - use them for learning, not judgment.

### Problem: Integration points unclear

**Symptoms:**

- Not sure how to connect new code to existing
- Unsure which files to modify
- Multiple possible integration approaches

**Solution:**

1. **For brownfield**:
   - Ensure document-project captured existing architecture
   - Review architecture docs before implementing
2. **Check story-context** - Should document integration points
3. **In tech-spec/architecture** - Explicitly document:
   - Which existing modules to modify
   - What APIs/services to integrate with
   - Data flow between new and existing code
4. **Run integration-planning workflow** (Level 3-4):
   - Architect agent creates integration strategy

### Problem: Inconsistent patterns being introduced

**Symptoms:**

- New code style doesn't match existing
- Different architectural approach
- Not following team conventions

**Solution:**

1. **Check convention detection** (Quick Spec Flow):
   - Should detect existing patterns
   - Asks for confirmation before proceeding
2. **Review documentation** - Ensure document-project captured patterns
3. **Use story-context** - Injects pattern guidance per story
4. **Add to code-review checklist**:
   - Pattern adherence
   - Convention consistency
   - Style matching
5. **Run retrospective** to identify pattern deviations early

---

## File & Path Issues

### Problem: Output files in wrong location

**Symptoms:**

- PRD created in wrong folder
- Story files not where expected
- Documentation scattered

**Solution:**
Check `bmad/bmm/config.yaml` for configured paths:

```yaml
output_folder: '{project-root}/docs'
dev_story_location: '{project-root}/docs/stories'
```

Default locations:

- Planning docs (PRD, epics, architecture): `{output_folder}/`
- Stories: `{dev_story_location}/`
- Status files: `{output_folder}/bmm-workflow-status.md`, `{output_folder}/sprint-status.yaml`

To change locations, edit config.yaml then re-run workflows.

### Problem: Can't find status file

**Symptoms:**

- workflow-status says no status file
- Can't track progress
- Lost place in workflow

**Solution:**

1. **Check default location**: `docs/bmm-workflow-status.md`
2. **If missing, reinitialize**:
   ```
   Load Analyst agent → run workflow-init
   ```
3. **For Phase 4**: Look for `sprint-status.yaml` in same folder as PRD
4. **Search for it**:
   ```bash
   find . -name "bmm-workflow-status.md"
   find . -name "sprint-status.yaml"
   ```

### Problem: Sprint-status.yaml not updating

**Symptoms:**

- Workflows complete but status unchanged
- Stories stuck in old status
- Epic status not progressing

**Solution:**

1. **Manual update required** - Most status changes are manual:
   ```yaml
   stories:
     - id: epic-1-story-1
       status: done # Change this manually
   ```
2. **Some workflows auto-update**:
   - sprint-planning creates file
   - epic-tech-context changes epic to "contexted"
   - create-story changes story to "drafted"
   - story-context changes to "ready-for-dev"
   - dev-story may auto-update (check workflow)
3. **Re-run sprint-planning** to resync if needed

---

## Agent Behavior Issues

### Problem: Agent provides vague or generic responses

**Symptoms:**

- "Use appropriate framework"
- "Follow best practices"
- Generic advice without specifics

**Solution:**

1. **Provide more context** - Be specific in your description:
   - "Add OAuth using passport.js to Express server"
   - Not: "Add authentication"
2. **For brownfield**:
   - Ensure document-project was run
   - Agent needs codebase context for specific advice
3. **Reference existing docs**:
   - "Based on the existing auth system in UserService..."
4. **Start fresh chat** - Context overload can cause generic responses

### Problem: Agent hallucinating or making up information

**Symptoms:**

- References files that don't exist
- Suggests APIs that aren't in your stack
- Creates imaginary requirements

**Solution:**

1. **Use fresh chat** - Context overflow main cause of hallucinations
2. **Provide concrete constraints**:
   - "We use Express 4.18.2, not Next.js"
   - "Our database is PostgreSQL, not MongoDB"
3. **For brownfield**:
   - Document-project provides factual grounding
   - Agent sees actual code, not assumptions
4. **Correct immediately**:
   - "No, we don't have UserService, we have AuthenticationModule"

### Problem: Agent won't follow instructions

**Symptoms:**

- Ignores specific requests
- Does something different than asked
- Doesn't respect constraints

**Solution:**

1. **Be more explicit** - Agents respond to clear, specific instructions:
   - "Use EXACTLY these three steps..."
   - "Do NOT include database migrations in this story"
2. **Check agent capabilities** - Agent might not have access to requested workflow
3. **Try different phrasing** - Rephrase request to be more direct
4. **Use menu system** - Numbers are clearer than text commands

---

## Integration Issues (Brownfield)

### Problem: New code conflicts with existing architecture

**Symptoms:**

- Integration approach doesn't fit existing structure
- Would require major refactoring
- Conflicts with established patterns

**Solution:**

1. **Check if document-project was run** - Agents need architecture context
2. **Review existing architecture docs**:
   - Read docs/architecture.md (from document-project)
   - Understand current system design
3. **For Level 3-4**:
   - Run validate-architecture workflow before planning
   - Use integration-planning workflow
4. **Explicitly document integration strategy** in architecture:
   - How new components fit existing structure
   - What modifications needed to existing code
   - Migration path if changing patterns

### Problem: Breaking changes to existing APIs

**Symptoms:**

- Changing API breaks consumers
- Downstream services affected
- Need backward compatibility

**Solution:**

1. **Identify all API consumers** (document-project should show this)
2. **Plan versioning strategy**:
   - API v1 (existing) + v2 (new)
   - Deprecation timeline
3. **Use feature flags** for gradual rollout
4. **Document migration guide** for API consumers
5. **Add to testing strategy**:
   - Existing consumers still work (v1)
   - New functionality works (v2)

### Problem: Data migration required

**Symptoms:**

- Schema changes needed
- Existing data needs transformation
- Risk of data loss

**Solution:**

1. **Create explicit migration strategy** in architecture:
   - Forward migration (old → new schema)
   - Rollback plan (new → old schema)
   - Data validation approach
2. **Test migrations thoroughly**:
   - On copy of production data
   - Measure performance impact
3. **Plan rollout**:
   - Staging environment first
   - Gradual production rollout
   - Monitoring for issues
4. **Document in tech-spec/architecture**:
   - Migration scripts
   - Rollback procedures
   - Expected downtime

---

## Still Stuck?

### Getting More Help

If your issue isn't covered here:

1. **Check other documentation**:
   - [FAQ](./faq.md) - Common questions
   - [Glossary](./glossary.md) - Terminology
   - [Quick Start](./quick-start.md) - Basic usage
   - [Brownfield Guide](./brownfield-guide.md) - Existing codebases
   - [Scale Adaptive System](./scale-adaptive-system.md) - Understanding levels

2. **Community support**:
   - [Discord](https://discord.gg/gk8jAdXWmj) - #general-dev, #bugs-issues
   - Active community, fast responses
   - Share your specific situation

3. **Report bugs**:
   - [GitHub Issues](https://github.com/bmad-code-org/BMAD-METHOD/issues)
   - Include version, steps to reproduce, expected vs actual behavior

4. **Video tutorials**:
   - [YouTube Channel](https://www.youtube.com/@BMadCode)
   - Visual walkthroughs of common workflows

---

## Common Error Messages

### "No workflow status file found"

**Cause:** Haven't run workflow-init yet
**Fix:** Load Analyst agent → run workflow-init

### "Epic file not found"

**Cause:** PRD/epics not created, or wrong path
**Fix:** Verify PRD/epics exist in output folder, check config.yaml paths

### "Story not in sprint-status.yaml"

**Cause:** Sprint-planning not run, or story file not created
**Fix:** Run sprint-planning workflow, verify story files exist

### "Documentation insufficient for brownfield"

**Cause:** No docs/index.md or document-project not run
**Fix:** Run document-project workflow with Deep scan

### "Level detection failed"

**Cause:** Ambiguous project description
**Fix:** Be more specific, use level keywords (fix, feature, platform, etc.)

### "Context generation failed"

**Cause:** Missing prerequisites (epic context, story file, or docs)
**Fix:** Verify epic-tech-context run, story file exists, docs present

---

## Prevention Tips

**Avoid common issues before they happen:**

1. ✅ **Always run document-project for brownfield** - Saves hours of context issues later
2. ✅ **Use fresh chats for complex workflows** - Prevents hallucinations and context overflow
3. ✅ **Verify files exist before running workflows** - Check PRD, epics, stories are present
4. ✅ **Read agent menu before requesting workflows** - Confirm agent has the workflow
5. ✅ **Start with smaller level if unsure** - Easy to upgrade (Level 1 → 2), hard to downgrade
6. ✅ **Keep status files updated** - Manual updates when needed, don't let them drift
7. ✅ **Run retrospectives after epics** - Catch issues early, improve next epic
8. ✅ **Follow phase sequence** - Don't skip required phases (Phase 2 before 3, 3 before 4)

---

**Issue not listed?** Please [report it](https://github.com/bmad-code-org/BMAD-METHOD/issues) so we can add it to this guide!