> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ticket-rs.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Dependencies

> Structure and manage issue dependencies for effective project planning

**Dependencies** define the relationships between issues in your project. When issue B depends on issue A, B is blocked until A is completed. tk uses these relationships to power graph analytics, prioritization, and execution planning.

***

## Defining Dependencies

### Using the CLI

```bash theme={null}
# Create an issue with dependencies
tk create "Build API endpoints" -d tk-abc123 -d tk-def456

# Add dependency to existing issue
tk dep add tk-ghi789 --depends-on tk-abc123

# Remove a dependency
tk dep remove tk-ghi789 --depends-on tk-abc123
```

### In Issue Files

Dependencies are listed in the YAML frontmatter:

```markdown theme={null}
---
status: open
deps: [tk-abc123, tk-def456]
type: feature
priority: 1
---
# Build API endpoints

This issue depends on the database schema (tk-abc123)
and authentication setup (tk-def456).
```

<Info>
  Dependencies reference issue IDs. The ID is the filename without the `.md` extension.
</Info>

***

## Dependency Types

### Direct vs Transitive

* **Direct dependencies**: Issues explicitly listed in `deps`
* **Transitive dependencies**: Issues blocked through a chain

```mermaid theme={null}
flowchart RL
    API["tk-api"]
    AUTH["tk-auth<br/>(Direct)"]
    DB["tk-db<br/>(Transitive)"]

    API -->|"depends on"| AUTH
    AUTH -->|"depends on"| DB

    style API fill:#cce5ff,stroke:#004085,stroke-width:2px,color:#1a1a2e
    style AUTH fill:#d62922,stroke:#a92215,stroke-width:2px,color:#fff
    style DB fill:#f8d7da,stroke:#dc3545,stroke-width:2px,color:#1a1a2e
```

<Caption>tk-api has a direct dependency on tk-auth, and a transitive dependency on tk-db</Caption>

### Blockers vs Blocked

* **Blockers**: Issues that must complete first (`deps`)
* **Blocked by this**: Issues waiting for this to complete

```mermaid theme={null}
flowchart LR
    AUTH["tk-auth<br/>(blocker)"]
    CONFIG["tk-config<br/>(blocker)"]
    API["tk-api<br/><strong>Current</strong>"]
    UI["tk-ui"]
    MOBILE["tk-mobile"]
    TESTS["tk-tests"]

    AUTH --> API
    CONFIG --> API
    API --> UI
    API --> MOBILE
    API --> TESTS

    style API fill:#d62922,stroke:#a92215,stroke-width:3px,color:#fff
    style AUTH fill:#fff3cd,stroke:#856404,stroke-width:2px,color:#1a1a2e
    style CONFIG fill:#fff3cd,stroke:#856404,stroke-width:2px,color:#1a1a2e
    style UI fill:#cce5ff,stroke:#004085,stroke-width:2px,color:#1a1a2e
    style MOBILE fill:#cce5ff,stroke:#004085,stroke-width:2px,color:#1a1a2e
    style TESTS fill:#cce5ff,stroke:#004085,stroke-width:2px,color:#1a1a2e
```

<Caption>tk-api is blocked by 2 issues (yellow) and blocks 3 issues (blue)</Caption>

```bash theme={null}
# See what blocks an issue
tk show tk-api

# See full dependency tree
tk dep tree tk-api
```

***

## Visualizing Dependencies

### Dependency Tree

```bash theme={null}
tk dep tree tk-api
```

**Sample output:**

```
tk-api: Build API endpoints [P1] (open)
    ├── tk-auth: Authentication setup [P1] (open)
    │   └── tk-db: Database schema [P0] (in_progress)
    └── tk-config: Config system [P2] (closed) ✓
```

<Tip>
  Closed dependencies show a checkmark. Only open dependencies block progress.
</Tip>

### Graph Analytics

```bash theme={null}
# See how dependencies affect priority
tk priority

# Find bottlenecks in dependency graph
tk insights
```

***

## Dependency Best Practices

<AccordionGroup>
  <Accordion title="Keep dependencies minimal">
    Only add dependencies that are truly blocking. Over-specifying dependencies reduces parallelization opportunities.
  </Accordion>

  <Accordion title="Avoid circular dependencies">
    tk detects cycles but can't resolve them. If A depends on B and B depends on A, neither can be completed.

    ```bash theme={null}
    # Check for cycles
    tk dep cycles
    ```
  </Accordion>

  <Accordion title="Use epics for grouping, not blocking">
    Don't make subtasks depend on the epic. Use `parent` field instead:

    ```markdown theme={null}
    # Good: parent relationship
    parent: tk-epic123

    # Avoid: dependency on parent
    deps: [tk-epic123]
    ```
  </Accordion>

  <Accordion title="Break large dependencies">
    If issue A depends on 10 things from issue B, B might be too large. Consider splitting B into smaller pieces.
  </Accordion>
</AccordionGroup>

***

## Working with Blocked Issues

### Finding Ready Work

Issues with no open blockers are "ready":

```bash theme={null}
# List all ready issues
tk ready

# Filter by priority
tk ready --priority 0
```

### Unblocking Work

When you complete an issue, dependents become unblocked:

```bash theme={null}
# Complete and see what's unblocked
tk resolve tk-db
# Output: tk-auth is now ready!
```

### Handling Blocked Issues

```bash theme={null}
# See blocked issues
tk list --status blocked

# See what's blocking a specific issue
tk show tk-api
```

***

## Linear Chains (Stacks)

When issues form a linear chain of dependencies, tk recognizes them as **stacks**:

```mermaid theme={null}
flowchart LR
    BASE["tk-base<br/>(Root)"]
    API["tk-api<br/>(Middle)"]
    UI["tk-ui<br/>(Tip)"]

    BASE --> API --> UI

    style BASE fill:#d4edda,stroke:#28a745,stroke-width:2px,color:#1a1a2e
    style API fill:#fff3cd,stroke:#856404,stroke-width:2px,color:#1a1a2e
    style UI fill:#cce5ff,stroke:#004085,stroke-width:2px,color:#1a1a2e
```

Stacks are useful for:

* Incremental feature development
* Coordinated code reviews
* Merge queue ordering

<Card title="Learn about Stacks" icon="layer-group" href="/concepts/stacks">
  See how tk detects and works with linear dependency chains.
</Card>

***

## Graph Analytics on Dependencies

tk analyzes your dependency graph to provide intelligent recommendations:

| Analysis          | What it shows                              |
| ----------------- | ------------------------------------------ |
| **PageRank**      | Issues blocking the most downstream work   |
| **Critical Path** | Longest chain determining minimum timeline |
| **Betweenness**   | Bottleneck issues appearing in many paths  |

```bash theme={null}
# Get all analytics
tk insights

# AI-powered recommendations
tk triage
```

<Card title="Graph Analytics" icon="chart-network" href="/concepts/graph-analytics">
  Deep dive into how tk uses graph algorithms for prioritization.
</Card>

***

## Common Patterns

### Feature Development

```bash theme={null}
# Create dependent feature issues
tk create "Database schema for users" -t feature -p 1
# Created: tk-user-db

tk create "User API endpoints" -t feature -p 1 -d tk-user-db
# Created: tk-user-api

tk create "User profile UI" -t feature -p 1 -d tk-user-api
# Created: tk-user-ui
```

### Bug Fix with Test

```bash theme={null}
# Bug depends on having a test first
tk create "Add test for edge case" -t task -p 1
# Created: tk-test

tk create "Fix edge case bug" -t bug -p 0 -d tk-test
# Created: tk-bug
```

### Epic Breakdown

```bash theme={null}
# Create epic
tk create "Authentication system" -t epic -p 1
# Created: tk-auth-epic

# Create subtasks with parent (not deps)
tk create "OAuth provider setup" -t task --parent tk-auth-epic
tk create "Session management" -t task --parent tk-auth-epic
tk create "Login UI" -t task --parent tk-auth-epic
```

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Circular dependency detected">
    Use `tk dep cycles` to find the cycle, then remove one dependency to break it.
  </Accordion>

  <Accordion title="Too many blocked issues">
    Run `tk triage` to find high-impact blockers. Clear these first to unblock the most work.
  </Accordion>

  <Accordion title="Dependency not recognized">
    Ensure the dependency ID matches exactly. IDs are case-sensitive and include the `tk-` prefix.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Stacks" icon="layer-group" href="/concepts/stacks">
    Learn about linear dependency chains.
  </Card>

  <Card title="Graph Analytics" icon="chart-network" href="/concepts/graph-analytics">
    Understand priority scoring and bottleneck detection.
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/cli-reference/commands">
    Full command reference for dependency management.
  </Card>

  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Get started with tk in 60 seconds.
  </Card>
</CardGroup>