Dependency Mapping Skill Skill

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

Left-to-right for linear - Use flowchart LR for sequential work
Top-to-bottom for complex - Use flowchart TB for many branches
Group by phase - Use subgraphs for project phases
Highlight critical path - Use thick arrows and colors
Keep titles short - Truncate to fit in diagram
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.

Agent Skills: Dependency Mapping Skill

Install this agent skill to your local

Skill Files