Skip to main content
This runbook helps you detect and break circular dependency cycles in your issues.

​
Symptoms

  • “circular dependency detected” errors
  • bd blocked shows unexpected results
  • Issues that should be ready appear blocked

​
Diagnosis

# Check for blocked issues
bd blocked

# View dependencies for a specific issue
bd show <issue-id>

# List all dependencies
bd dep tree

​
Solution

Step 1: Identify the cycle 
bd blocked --verbose
Step 2: Map the dependency chain 
bd show <issue-a>
bd show <issue-b>
# Follow the chain until you return to <issue-a>
Step 3: Determine which dependency to remove Consider: Which dependency is least critical to the workflow? Step 4: Remove the problematic dependency 
bd dep remove <dependent-issue> <blocking-issue>
Step 5: Verify the cycle is broken 
bd blocked
bd ready

​
Prevention

  • Think “X needs Y” not “X before Y” when adding dependencies
  • Use bd blocked after adding dependencies to check for cycles
  • Keep dependency chains shallow when possible