@cloudkinetix/bmad-enhanced

# Parallel Development Troubleshooting Decision Tree ## Quick Diagnosis Guide Use this decision tree to quickly diagnose and resolve common parallel development issues. ## Start Here ``` What type of issue are you experiencing? │ ├─ 🔴 Execution Issues (Can't start/run parallel work) ├─ 🟡 Conflict Issues (Work items interfering) ├─ 🔵 Performance Issues (Slow or resource problems) ├─ 🟢 Integration Issues (Can't merge completed work) └─ ⚫ Quality Issues (Tests failing, standards not met) ``` --- ## 🔴 Execution Issues ### Cannot Create Worktree ``` Error: "fatal: could not create worktree" │ ├─ Check: Git version >= 2.7? │ ├─ NO → Update Git: brew upgrade git │ └─ YES → Continue │ ├─ Check: Disk space available? │ ├─ NO → Free space or change worktree location │ └─ YES → Continue │ ├─ Check: Directory permissions? │ ├─ NO → Fix: chmod 755 ../worktrees │ └─ YES → Continue │ └─ Check: Worktree already exists? ├─ YES → Remove: git worktree remove <path> └─ NO → Check: git worktree list ``` ### Stories Not Found ``` Error: "No stories found in docs/stories/" │ ├─ Check: Correct directory? │ ├─ NO → Navigate to project root │ └─ YES → Continue │ ├─ Check: Stories have .md extension? │ ├─ NO → Rename files to .md │ └─ YES → Continue │ └─ Check: Stories follow BMAD format? ├─ NO → Fix story format └─ YES → Check file permissions ``` ### Validation Failures ``` Error: "Story validation failed" │ ├─ Critical Issues? │ ├─ YES → Must fix before proceeding │ └─ NO → Continue │ ├─ Warning Issues? │ ├─ YES → Can override with justification │ └─ NO → Continue │ └─ Check validation rules: └─ config/validation-rules.yaml ``` --- ## 🟡 Conflict Issues ### File Conflicts Detected ``` Warning: "File conflicts between work items" │ ├─ Same file modified? │ ├─ YES → Continue to resolution │ └─ NO → Check for indirect conflicts │ ├─ Can changes be isolated? │ ├─ YES → Refactor to separate files │ └─ NO → Continue │ ├─ Is sequential execution acceptable? │ ├─ YES → Use waves to sequence work │ └─ NO → Continue │ └─ Resolution options: ├─ Mediator pattern (complex conflicts) ├─ Feature flags (runtime isolation) └─ Microservice split (architectural) ``` ### Hidden Dependencies Found ``` Warning: "Semantic dependencies detected" │ ├─ Business logic coupling? │ ├─ YES → Document and sequence work │ └─ NO → Continue │ ├─ Data model dependencies? │ ├─ YES → Create migration strategy │ └─ NO → Continue │ └─ API contract changes? ├─ YES → Version APIs properly └─ NO → Review analysis accuracy ``` --- ## 🔵 Performance Issues ### Slow Execution ``` Issue: "Parallel execution slower than expected" │ ├─ Check: CPU cores available? │ ├─ < 4 → Reduce parallelism │ └─ >= 4 → Continue │ ├─ Check: Memory usage? │ ├─ > 80% → Close other applications │ └─ < 80% → Continue │ ├─ Check: Disk I/O? │ ├─ SSD → Continue │ └─ HDD → Consider SSD or reduce parallelism │ └─ Check: Test suite performance? ├─ Slow tests → Optimize or parallelize tests └─ Fast tests → Check build process ``` ### Resource Exhaustion ``` Error: "Cannot allocate resources" │ ├─ Too many worktrees? │ ├─ YES → Limit to CPU cores - 1 │ └─ NO → Continue │ ├─ Large repository? │ ├─ YES → Use shallow clones │ └─ NO → Continue │ └─ Background processes? ├─ YES → Stop unnecessary services └─ NO → Increase system resources ``` --- ## 🟢 Integration Issues ### Cannot Merge Worktree ``` Error: "Merge conflicts during integration" │ ├─ Simple conflicts? │ ├─ YES → Use git mergetool │ └─ NO → Continue │ ├─ Logical conflicts? │ ├─ YES → Joint team resolution │ └─ NO → Continue │ ├─ Test failures after merge? │ ├─ YES → Fix tests before continuing │ └─ NO → Continue │ └─ Options: ├─ Rebase instead of merge ├─ Squash commits for clarity └─ Cherry-pick specific changes ``` ### Integration Tests Failing ``` Error: "Integration tests fail after merge" │ ├─ Unit tests passing? │ ├─ NO → Fix unit tests first │ └─ YES → Continue │ ├─ Environment issues? │ ├─ YES → Verify test environment │ └─ NO → Continue │ ├─ Race conditions? │ ├─ YES → Add synchronization │ └─ NO → Continue │ └─ Data dependencies? ├─ YES → Reset test data └─ NO → Debug integration points ``` --- ## ⚫ Quality Issues ### Coverage Dropping ``` Warning: "Code coverage below threshold" │ ├─ New code untested? │ ├─ YES → Add missing tests │ └─ NO → Continue │ ├─ Tests disabled? │ ├─ YES → Re-enable or fix tests │ └─ NO → Continue │ └─ Coverage tool issues? ├─ YES → Verify configuration └─ NO → Review coverage report ``` ### Standards Violations ``` Error: "Linting/formatting errors" │ ├─ Auto-fixable? │ ├─ YES → Run auto-fix command │ └─ NO → Manual fixes needed │ ├─ Rule conflicts? │ ├─ YES → Align team on rules │ └─ NO → Fix violations │ └─ New rules added? ├─ YES → Update all worktrees └─ NO → Check rule configuration ``` --- ## Emergency Procedures ### 🚨 Complete Rollback ```bash # Stop all work and reset git worktree list | grep -v main | awk '{print $1}' | xargs -I {} git worktree remove --force {} git branch -D $(git branch | grep parallel/) rm -rf .bmad-workspace/ck-parallel-dev/runs/* ``` ### 🔧 Partial Recovery ```bash # Recover specific worktree cd ../worktrees/<name> git stash save "Emergency backup" git checkout main git worktree remove ../worktrees/<name> # Recreate and apply stash ``` ### 📞 Escalation Path 1. Team Lead - Process issues 2. Architect - Technical conflicts 3. Product Owner - Requirement conflicts 4. DevOps - Infrastructure issues --- ## Prevention Checklist After resolving any issue: - [ ] Document root cause - [ ] Update troubleshooting guide - [ ] Add automated check if possible - [ ] Share learning with team - [ ] Update process if needed Remember: Every issue is an opportunity to improve the parallel development process!