dependency-mapping

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:

flowchart LR
    I1[#1 Setup (init)]

CORRECT:

flowchart LR
    I1[#1 Setup - init]

Issue Node Naming Convention

Use consistent naming for issue nodes:

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:

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:

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:

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:

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:

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.