> ## 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.

# Advanced Workflows

> Deep dive into graph analytics, stacks, parallel tracks, and worktree-based development

This guide explains how tk's graph analytics, stacks, parallel tracks, and worktrees work together to enable sophisticated development workflows. Understanding these concepts helps you structure work for maximum parallelization and efficient merge queues.

***

## The Dependency Graph

At its core, tk maintains a **directed acyclic graph (DAG)** of your issues. Each issue can depend on zero or more other issues, and these relationships form the graph structure.

```mermaid theme={null}
flowchart TB
    AUTH["tk-auth<br/>(Root)"]
    API["tk-api"]
    UI["tk-ui"]
    DEPLOY["tk-deploy<br/>(Leaf)"]

    AUTH --> API
    AUTH --> UI
    API --> DEPLOY
    UI --> DEPLOY

    style AUTH fill:#d62922,stroke:#a92215,stroke-width:2px,color:#fff
    style API fill:#cce5ff,stroke:#004085,stroke-width:2px,color:#1a1a2e
    style UI fill:#cce5ff,stroke:#004085,stroke-width:2px,color:#1a1a2e
    style DEPLOY fill:#d4edda,stroke:#28a745,stroke-width:2px,color:#1a1a2e
```

<Caption>A directed acyclic graph (DAG) — edges point from blockers to blocked issues</Caption>

This graph enables:

* **Topological sorting** — Determine execution order
* **Cycle detection** — Prevent impossible dependencies
* **Impact analysis** — Know what work unblocks what
* **Parallelization** — Find independent work streams

***

## Two Types of Structure: Stacks vs Tracks

tk recognizes two fundamental patterns in your dependency graph:

### Stacks (Linear Chains)

A **stack** is a linear sequence where each issue depends on exactly one predecessor:

```mermaid theme={null}
flowchart LR
    BASE["tk-base"]
    API["tk-api"]
    UI["tk-ui"]
    DEPLOY["tk-deploy"]

    BASE --> API --> UI --> DEPLOY

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

Characteristics:

* **Sequential execution** — Must be worked in order
* **Coordinated review** — Can be reviewed as a unit
* **Merge optimization** — Validate tip, fast-forward merge all
* **Graphite-style** — Mirrors stacked PR workflows

Use stacks for:

* Incremental feature development
* Layered refactoring (foundation → API → UI)
* Changes that must be merged in order

### Parallel Tracks

A **track** is a group of issues that share a common root but can be worked independently:

```mermaid theme={null}
flowchart TB
    AUTH["tk-auth<br/>(Shared Root)"]
    API["tk-api"]
    UI["tk-ui"]
    MOBILE["tk-mobile"]

    AUTH --> API
    AUTH --> UI
    AUTH --> MOBILE

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

<Caption>Three parallel tracks (API, UI, Mobile) that can be worked simultaneously after completing the shared root</Caption>

Characteristics:

* **Parallel execution** — Can be worked simultaneously
* **Independent review** — Each track reviewed separately
* **Merge flexibility** — Merge in any order after root completes

Use tracks for:

* Feature branches that share infrastructure
* Platform-specific implementations
* Independent components of a larger system

***

## Graph Analytics Deep Dive

tk uses several graph algorithms to help prioritize work:

### PageRank Priority

[PageRank](http://ilpubs.stanford.edu:8090/422/1/1999-66.pdf) scores issues by their position in the dependency graph. Issues that block more downstream work get higher scores.

```bash theme={null}
tk priority
```

**How it works:**

1. Each issue starts with equal "importance"
2. Importance flows through dependency edges
3. Issues that block many others accumulate importance
4. Scores normalize to 0-100 range

**Interpretation:**

| Score | Meaning                                   |
| ----- | ----------------------------------------- |
| 80+   | Critical blocker, blocks significant work |
| 50-79 | Important, blocks multiple issues         |
| 20-49 | Moderate impact                           |
| \< 20 | Leaf node or low-dependency issue         |

### Betweenness Centrality

Measures how often an issue appears on the shortest path between other issues. High betweenness indicates a **bottleneck**.

```bash theme={null}
tk insights
```

**Why it matters:**

An issue with high betweenness:

* Sits at a critical junction in your workflow
* Delays here cascade to multiple work streams
* May need to be split or prioritized

### Critical Path

The longest chain of dependencies determines your **minimum timeline**. No amount of parallelization can shorten the critical path.

```bash theme={null}
tk insights --critical-path
```

**Using critical path:**

1. Identify issues on the critical path
2. These are your highest-leverage optimization targets
3. Breaking dependencies on critical path shortens timeline
4. Monitor critical path length as a project health metric

***

## Execution Planning

The `tk plan` command generates an execution plan using topological sort:

```bash theme={null}
tk plan
```

**Sample output:**

```
Execution Plan:

Batch 1 (start immediately):
  • tk-auth     - Authentication setup
  • tk-config   - Configuration system

Batch 2 (after Batch 1):
  • tk-api      - API endpoints (waits: tk-auth)
  • tk-ui       - UI components (waits: tk-config)

Batch 3 (after Batch 2):
  • tk-deploy   - Deployment (waits: tk-api, tk-ui)
```

**Batches represent:**

* **Maximum parallelism** — All issues in a batch can be worked simultaneously
* **Dependency ordering** — Each batch depends only on previous batches
* **Resource allocation** — Match batch sizes to team capacity

***

## Stacks + Worktrees: Graphite-Style Workflows

tk's worktree support enables Graphite-style stacked development:

### The Pattern

1. **Detect stacks** in your issue graph
2. **Create worktrees** for each issue in the stack
3. **Work bottom-up** from stack root to tip
4. **Validate at tip** — run tests on the final state
5. **Merge all** — fast-forward the entire stack

### Setup

```bash theme={null}
# Configure worktree location (sibling directory)
tk config set workflow.worktree_base "../wt"

# View detected stacks
tk stacks
```

### Working a Stack

```bash theme={null}
# See your stacks
tk stacks

# Output:
# ○ stack-1 [3 issues] tk-base → tk-api → tk-ui
#   Chain: tk-base → tk-api → tk-ui

# Start from root
tk claim tk-base
tk worktree create tk-base

# Work in the worktree
cd ../wt/tk-base
# ... make changes, commit ...

# Move up the stack
tk resolve tk-base
tk claim tk-api
# The worktree inherits from tk-base's branch
```

### Stack-Aware Hooks

tk's hook system supports stack workflows with special variables:

```bash theme={null}
# .tickets/hooks/on-claim.sh
#!/bin/bash

# Stack-aware worktree creation
if [ -n "{{ stack_id }}" ]; then
    echo "Working on {{ id }} ({{ stack_position }}/{{ stack_depth }} in {{ stack_id }})"

    # Create worktree based on previous stack issue if not root
    if [ "{{ stack_position }}" -gt 1 ]; then
        git worktree add ../wt/{{ id | short }} {{ previous_in_stack }}
    else
        git worktree add ../wt/{{ id | short }} main
    fi
fi
```

***

## Combining Concepts: A Real Workflow

Here's how all these concepts work together in a real project:

### 1. Structure Your Work

```bash theme={null}
# Create foundation (no deps - track root)
tk create "Auth system" -t feature -p 1
# Created: tk-auth

# Create parallel tracks (independent work)
tk create "REST API" -t feature -d tk-auth
tk create "GraphQL API" -t feature -d tk-auth
tk create "Mobile SDK" -t feature -d tk-auth

# Create a stack (sequential work)
tk create "User model" -t task -d tk-auth
tk create "User API" -t task -d tk-user-model
tk create "User UI" -t task -d tk-user-api
```

### 2. Analyze the Graph

```bash theme={null}
# See the structure
tk plan

# Batch 1: tk-auth (root)
# Batch 2: tk-rest, tk-graphql, tk-mobile, tk-user-model
# Batch 3: tk-user-api
# Batch 4: tk-user-ui

# See stacks
tk stacks

# stack-1: tk-user-model → tk-user-api → tk-user-ui

# Check priorities
tk priority

# tk-auth: 85 (blocks everything)
# tk-user-model: 45 (stack root, blocks 2)
# Others: 20-30
```

### 3. Execute Strategically

```bash theme={null}
# Start with highest-impact work
tk triage

# Recommendation: tk-auth (blocks 6 issues)
tk claim tk-auth

# After completing auth, multiple tracks open up
tk resolve tk-auth

# Now unblocked: tk-rest, tk-graphql, tk-mobile, tk-user-model
# Assign to team members or work in parallel

# Work the stack bottom-up
tk claim tk-user-model
# ... complete ...
tk resolve tk-user-model
tk claim tk-user-api
# ... and so on
```

### 4. Monitor Health

```bash theme={null}
# Regular health checks
tk triage

# Watch for:
# - High stack count → lots of sequential work
# - Long critical path → timeline risk
# - High bottleneck count → restructure needed
# - Cycles detected → immediate fix required
```

***

## Best Practices

<AccordionGroup>
  <Accordion title="Minimize critical path length">
    The critical path determines minimum timeline. To shorten it:

    * Break large issues into parallel sub-tasks
    * Remove unnecessary dependencies
    * Identify and optimize bottleneck issues
  </Accordion>

  <Accordion title="Use stacks for incremental features">
    Stacks excel when:

    * Changes must be reviewed/merged in order
    * Each layer builds on the previous
    * You want to validate the final state once

    Avoid stacks when:

    * Work can genuinely be done in parallel
    * You have multiple reviewers
    * Speed is more important than ordering
  </Accordion>

  <Accordion title="Balance stack depth">
    Deep stacks (5+ issues) have trade-offs:

    * **Pro:** Clear progression, easy to follow
    * **Con:** Sequential bottleneck, long merge times

    Consider splitting deep stacks into parallel tracks where possible.
  </Accordion>

  <Accordion title="Use triage daily">
    `tk triage` combines all analytics into actionable recommendations:

    * Start sessions with `tk triage`
    * Focus on blockers to clear first
    * Quick wins maintain momentum
    * Monitor health trends over time
  </Accordion>

  <Accordion title="Structure for your team size">
    * **Solo:** Deeper stacks are fine, you control the sequence
    * **Small team (2-4):** Mix stacks and parallel tracks
    * **Large team (5+):** Maximize parallel tracks, minimize shared stacks
  </Accordion>
</AccordionGroup>

***

## Command Reference

| Command                   | Purpose                    |
| ------------------------- | -------------------------- |
| `tk plan`                 | Parallel execution batches |
| `tk stacks`               | Detect linear chains       |
| `tk priority`             | PageRank-based priorities  |
| `tk insights`             | Betweenness, critical path |
| `tk triage`               | Unified recommendations    |
| `tk dep tree <id>`        | Visualize dependencies     |
| `tk worktree create <id>` | Create issue worktree      |

***

## Next Steps

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

  <Card title="Dependencies" icon="diagram-project" href="/concepts/dependencies">
    Managing issue dependencies.
  </Card>

  <Card title="Graph Analytics" icon="chart-network" href="/concepts/graph-analytics">
    PageRank, critical path, and metrics.
  </Card>

  <Card title="CLI Reference" icon="terminal" href="/cli-reference/commands">
    Full command documentation.
  </Card>
</CardGroup>