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