# Dependency Mapping > 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 - Skill: `britt/dependency-mapping` (Agent Skill) - Install (CLI): `npx skillmds@latest add britt/dependency-mapping` - Raw SKILL.md: https://api.skillmd.com/api/skills/britt/dependency-mapping/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: britt (https://skillmd.com/u/britt) - Updated: 2026-09-10 - Page: https://skillmd.com/skills/britt/dependency-mapping --- # 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[# ]` ## 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[# ]` convention silently creates duplicate nodes for the same issue.