---
name: dependency-mapping
description: "Use when asked to map issue dependencies, show what blocks what, or find the critical path through project work - reads GitHub issues for blocked-by/depends-on signals and generates Mermaid flowcharts of blocking chains"
---

# Dependency Mapping Skill

Generate Mermaid flowcharts that visualize GitHub issue dependencies, blocking relationships, and critical paths through the project.

## When to Use

Activate this skill when:
- User asks "show me the dependencies", "map the issue dependencies"
- User wants to see which issues block others
- During sprint planning to identify critical path
- After issue decomposition to visualize relationships

## CRITICAL: Mermaid Syntax Rules

### NEVER use parentheses in node labels

Parentheses break GitHub rendering.

**WRONG:**
```mermaid
flowchart LR
    I1[#1 Setup (init)]
```

**CORRECT:**
```mermaid
flowchart LR
    I1[#1 Setup - init]
```

### Issue Node Naming Convention

Use consistent naming for issue nodes:

```mermaid
flowchart LR
    I201[#201 Setup auth module]
    I202[#202 Implement login]
    I203[#203 Add password reset]
```

Format: `I<number>[#<number> <short title>]`

## Dependency Graph Patterns

### Linear Dependencies

Issues that must be done in sequence:

```mermaid
flowchart LR
    I1[#1 Setup project] --> I2[#2 Create database]
    I2 --> I3[#3 Add API endpoints]
    I3 --> I4[#4 Integration tests]
```

### Parallel Work

Issues that can be done simultaneously:

```mermaid
flowchart TB
    I1[#1 Setup project]
    I1 --> I2[#2 Frontend setup]
    I1 --> I3[#3 Backend setup]
    I2 --> I4[#4 Integration]
    I3 --> I4
```

### Complex Dependencies

Multiple blocking relationships:

```mermaid
flowchart TB
    subgraph Foundation
        I1[#1 Project setup]
        I2[#2 Database schema]
    end

    subgraph Features
        I3[#3 User auth]
        I4[#4 User profile]
        I5[#5 Settings page]
    end

    subgraph Integration
        I6[#6 End-to-end tests]
    end

    I1 --> I2
    I1 --> I3
    I2 --> I3
    I3 --> I4
    I3 --> I5
    I4 --> I6
    I5 --> I6
```

### Critical Path Highlighting

Emphasize the longest dependency chain:

```mermaid
flowchart LR
    I1[#1 Setup]
    I2[#2 Database]
    I3[#3 Auth]
    I4[#4 API]
    I5[#5 Tests]

    I1 ==> I2
    I2 ==> I3
    I3 ==> I4
    I4 ==> I5

    I1 --> I6[#6 Docs]

    style I1 fill:#f96
    style I2 fill:#f96
    style I3 fill:#f96
    style I4 fill:#f96
    style I5 fill:#f96
```

## Dependency Analysis Process

### Step 1: Gather Issues

**Prerequisite**: Requires the `gh` CLI (e.g. `gh issue list --state open --json number,title,labels,body`) or an equivalent GitHub MCP server.

Gather all open issues:
- Note issue numbers and titles
- Check for "blocked by" or "depends on" in labels
- Look for dependency keywords in descriptions

### Step 2: Parse Dependencies

Look for dependency indicators:
- **Labels**: `blocked`, `waiting`, `depends-on`
- **Body text**: "Blocked by #X", "Depends on #X", "After #X"
- **Comments**: Discussion about ordering

### Step 3: Build Dependency Map

Create a map of relationships:
```
#201 → blocks → #202, #203
#202 → blocks → #204
#203 → blocks → #204
```

### Step 4: Identify Critical Path

Find the longest chain of dependencies - this is the critical path that determines minimum project duration.

### Step 5: Generate Diagram

Create the Mermaid flowchart with:
- All issues as nodes
- Arrows showing "blocks" direction
- Subgraphs for phases or areas
- Styling for critical path

## Dependency Detection Keywords

Look for these patterns in issue bodies:

| Pattern | Meaning |
|---------|---------|
| "Blocked by #X" | This issue depends on #X |
| "Depends on #X" | This issue depends on #X |
| "After #X" | Do this after #X |
| "Blocks #X" | This issue must complete before #X |
| "Required for #X" | This issue must complete before #X |
| "Prerequisite: #X" | This issue depends on #X |

## Arrow Types

| Arrow | Use For |
|-------|---------|
| `-->` | Standard dependency |
| `==>` | Critical path |
| `-.->` | Soft dependency or optional |
| `--text-->` | Labeled relationship |

## Best Practices

1. **Left-to-right for linear** - Use `flowchart LR` for sequential work
2. **Top-to-bottom for complex** - Use `flowchart TB` for many branches
3. **Group by phase** - Use subgraphs for project phases
4. **Highlight critical path** - Use thick arrows and colors
5. **Keep titles short** - Truncate to fit in diagram
6. **Link to issues** - Include issue numbers for reference

## Example Output

For a set of issues about building an API:

```mermaid
flowchart TB
    subgraph Setup
        I1[#101 Initialize project]
        I2[#102 Configure database]
    end

    subgraph Core API
        I3[#103 User endpoints]
        I4[#104 Auth endpoints]
        I5[#105 Data endpoints]
    end

    subgraph Testing
        I6[#106 Unit tests]
        I7[#107 Integration tests]
    end

    I1 --> I2
    I2 --> I3
    I2 --> I4
    I2 --> I5
    I3 --> I6
    I4 --> I6
    I5 --> I6
    I6 --> I7

    %% Critical path
    linkStyle 0,1,3,5,7 stroke:#f00,stroke-width:2px
```

## After Generating Graph

- Offer to save the graph to a markdown file the user names
- Identify the critical path length
- Flag any circular dependencies as errors
- Suggest `timeline-planning` skill (if available) for Gantt chart
- Recommend addressing blockers first

## Common Mistakes

- **Parentheses in node labels** - breaks GitHub's Mermaid rendering. NEVER use parentheses in labels; use dashes instead (see the CRITICAL syntax rules above).
- **Unflagged circular dependencies** - if #A blocks #B and #B blocks #A, the diagram may still render but the plan is impossible. Always call out cycles as errors.
- **Inconsistent node IDs** - deviating from the `I<number>[#<number> <short title>]` convention silently creates duplicate nodes for the same issue.