Troubleshooting FAQ documented

Severity: Optional

Common issues and gotchas should be documented so new developers don't hit the same problems repeatedly.

Check automatically:

# Look for troubleshooting or FAQ docs
find . -maxdepth 4 -type f \( -name "*troubleshoot*" -o -name "*faq*" -o -name "*problem*" -o -name "*issue*" -o -name "*debug*" \) -name "*.md" 2>/dev/null | grep -v node_modules

# Search for troubleshooting content
grep -riE "troubleshoot|common (issue|problem|error)|faq|known issue|if you see|fix for" docs/ README.md --include="*.md" 2>/dev/null | head -10

# Check README for troubleshooting section
grep -iE "^#+ *(troubleshoot|faq|common issue|known issue|problem)" README.md 2>/dev/null

Ask user:

• "Are common setup issues documented somewhere?"
• "What trips up new devs most often?" (port conflicts, env issues, version mismatches)
• "Is there a place to add new gotchas when discovered?"

Common troubleshooting topics:

• Port conflicts (something already running on 3000)
• Node/Python version mismatches
• Missing environment variables
• Docker issues (disk space, network, permissions)
• Database connection failures
• Dependency installation failures
• Platform-specific issues (Mac vs Linux)

Pass criteria:

• Troubleshooting section or FAQ exists
• Covers common issues (port conflicts, dependency issues, env problems)
• Actively maintained (new issues added when discovered)

Fail criteria:

• No troubleshooting docs
• Doc exists but stale (references old issues, misses current ones)
• New devs hit same issues repeatedly without documentation

Cross-reference with:

• DEV-001 (onboarding doc should link to troubleshooting)
• GIT-001/003 (setup failures should feed into FAQ)

Evidence to capture:

• Location of troubleshooting docs
• Number of issues documented
• Last updated date
• Whether actively maintained

---