> ## Documentation Index
> Fetch the complete documentation index at: https://beads.gascity.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Circular Dependencies

> Detect and break dependency cycles

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

```bash theme={null}
# 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

```bash theme={null}
bd blocked --verbose
```

**Step 2:** Map the dependency chain

```bash theme={null}
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

```bash theme={null}
bd dep remove <dependent-issue> <blocking-issue>
```

**Step 5:** Verify the cycle is broken

```bash theme={null}
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