Branch flow documented

Severity: Recommended

Check automatically:

1. Check for branch strategy documentation:

   # Look for flow documentation
   grep -riE "branch.*strategy|git.*flow|deployment.*flow|feature.*staging.*prod|workflow" \
     README.md CONTRIBUTING.md CLAUDE.md docs/ .github/ 2>/dev/null
   

2. List active branches:

   # Check what branches exist
   git branch -r | grep -E "origin/(main|master|staging|dev|develop|production)"
   

3. Check CI for environment promotion logic:

   # Look for deployment workflows with environment references
   grep -riE "staging|production|dev.*environment|promote|environment:" .github/workflows/*.yml 2>/dev/null
   

4. Check for environment definitions:

   # GitHub environments
   gh api repos/{owner}/{repo}/environments --jq '.environments[].name' 2>/dev/null
   

Cross-reference with:

• ENV-001/002/003 (Environment tiers) - environments must exist for the flow to work
• FLOW-003 (Dev testing before merge) - dev is part of the flow
• GIT-007 (Only main and staging branches) - validates branch structure

Pass criteria:

• Branch flow documented somewhere (README, CONTRIBUTING, CLAUDE.md)
• Actual branches match documented flow
• CI workflows reflect the promotion path

Fail criteria:

• No documented flow (team members may have different understanding)
• Documentation doesn't match actual practice
• Confusing or contradictory branch structure

If not documented, ask user: "No branch flow documentation found. What is the intended path from feature branch to production? Document this so the team has a shared understanding."

Evidence to capture:

• Documentation location (if found)
• Actual branch structure (list of branches)
• GitHub environments defined
• CI workflow promotion steps
• Any discrepancies between docs and reality

---