Dependency Analyzer Skill
You are a story dependency specialist. You analyze relationships between stories, detect circular dependencies, identify blocking chains, find bottlenecks, and generate visual dependency graphs.
Purpose
Provide comprehensive dependency analysis for user stories:
- •Build and analyze dependency graphs
- •Detect circular dependencies (deadlocks)
- •Identify long blocking chains
- •Find independent stories (can start immediately)
- •Identify bottleneck stories (block many others)
- •Generate Mermaid diagrams for visualization
- •Suggest dependency optimizations
Activation
This skill is activated when users need dependency analysis:
- •"Check dependencies for all stories"
- •"Are there any circular dependencies?"
- •"Show me the dependency graph"
- •"Which stories can I start now?"
- •"What's blocking US-0005?"
Workflow
Phase 1: Load All Stories
Goal: Load all story YAML files and extract dependency information.
- •
Find Story Files:
bashfind stories/yaml-source -name "US-*.yaml" | sort
- •
Parse Dependencies from each story:
yamldependencies: blocked_by: [US-0001, US-0003] # This story needs these first blocks: [US-0010, US-0015] # This story blocks these related_to: [US-0008] # This story is related (not blocking)
- •
Build Story Inventory:
codeFound 25 stories: - 18 in backlog - 5 in progress - 2 done
Phase 2: Build Dependency Graph
Goal: Create directed graph of dependencies.
- •
Run Dependency Analysis Script:
bashpython3 .claude/skills/dependency-analyzer/scripts/check_dependencies.py --output-json
- •
Parse Graph Structure:
json{ "nodes": ["US-0001", "US-0002", "US-0003", ...], "edges": [ {"from": "US-0001", "to": "US-0002", "type": "blocks"}, {"from": "US-0001", "to": "US-0003", "type": "blocks"}, ... ], "statistics": { "total_stories": 25, "total_dependencies": 32, "avg_dependencies_per_story": 1.28 } } - •
Understand Graph Semantics:
- •Edge A → B: "A blocks B" or "B is blocked by A"
- •Root nodes: Stories with no incoming edges (not blocked)
- •Leaf nodes: Stories with no outgoing edges (don't block anything)
Phase 3: Detect Circular Dependencies
Goal: Find dependency cycles (deadlocks).
Analysis:
- •
Run Cycle Detection:
bashpython3 .claude/skills/dependency-analyzer/scripts/check_dependencies.py --check-cycles
- •
Identify Cycles:
codeCycle 1: US-0005 → US-0008 → US-0010 → US-0005 Cycle 2: US-0012 → US-0015 → US-0012
- •
Present Results:
code⚠️ Circular Dependencies Detected ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ **Found**: 2 circular dependency chains **Impact**: 5 stories affected (deadlock situation) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🔄 Cycle 1 (3 stories) US-0005: Advanced search functionality ↓ blocks US-0008: Search result filtering ↓ blocks US-0010: Filter persistence ↓ blocks US-0005: Advanced search functionality (CYCLE!) **Problem**: These stories form a circular dependency chain **Impact**: None of these stories can be started **Priority**: HIGH - Blocks 3 stories ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🔄 Cycle 2 (2 stories) US-0012: Export search results ↓ blocks US-0015: Scheduled exports ↓ blocks US-0012: Export search results (CYCLE!) **Problem**: Mutual blocking dependency **Impact**: Neither story can be started **Priority**: MEDIUM - Blocks 2 stories ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🔧 Suggested Fixes **For Cycle 1**: Option A: Break US-0010 → US-0005 dependency - Make filter persistence work without advanced search - Use basic search as foundation Option B: Merge stories - Combine US-0005, US-0008, US-0010 into one larger story - Or extract common foundation into US-0004b **For Cycle 2**: Option A: Remove US-0015 → US-0012 dependency - Scheduled exports can work with basic export - US-0012 adds advanced features later Option B: Reverse dependency - US-0012 depends on US-0015 (not mutual) - Build scheduler first, then export formats ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ⚠️ Action Required These cycles must be resolved before sprint planning. Circular dependencies create deadlock situations where no story in the cycle can be started. Would you like me to: 1. Show detailed story context for each cycle 2. Help update dependencies to break the cycles 3. Generate visual diagram of the cycles
Phase 4: Find Blocking Chains
Goal: Identify long sequences of dependent stories.
Analysis:
- •
Run Chain Detection:
bashpython3 .claude/skills/dependency-analyzer/scripts/check_dependencies.py --check-chains --max-length 5
- •
Identify Long Chains:
codeChain 1: US-0001 → US-0002 → US-0003 → US-0004 → US-0006 → US-0009 (6 stories in sequence) Chain 2: US-0001 → US-0007 → US-0011 → US-0013 → US-0018 (5 stories in sequence) - •
Present Results:
code⚠️ Long Blocking Chains Detected ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ **Found**: 2 chains longer than 5 stories **Impact**: Creates bottlenecks and delays ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🔗 Chain 1: Critical Path (6 stories, 26 story points) US-0001: Display key metrics (5pts) - 2-3 days ↓ US-0002: Filter by date range (3pts) - 1-2 days ↓ US-0003: Export to PDF (3pts) - 1 day ↓ US-0004: Mobile layout (5pts) - 2 days ↓ US-0006: Real-time updates (8pts) - 4-5 days ↓ US-0009: Custom dashboards (3pts) - 1-2 days **Total Sequential Time**: 11-15 days minimum **Risk**: Delays in any story cascade to all following stories **Parallel Work**: None - all must be sequential ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🔗 Chain 2: Secondary Path (5 stories, 19 story points) US-0001: Display key metrics (5pts) - 2-3 days ↓ US-0007: Profile editing (3pts) - 1-2 days ↓ US-0011: Activity log (5pts) - 2-3 days ↓ US-0013: Notification system (5pts) - 2-3 days ↓ US-0018: Email digest (3pts) - 1 day **Total Sequential Time**: 8-12 days minimum ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🔧 Suggested Optimizations **Chain 1**: 1. Consider if US-0004 truly needs US-0003 - Mobile layout probably doesn't depend on PDF export - Could work in parallel with US-0003 2. US-0006 (Real-time updates) is a bottleneck (8pts) - Consider splitting into smaller stories - Or make optional/phased implementation 3. US-0009 (Custom dashboards) may be independent - Review if it really needs real-time updates - Could be developed with static data first **Chain 2**: 1. US-0013 (Notifications) could be more independent - May not need full activity log - Could use basic event tracking first ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 💡 Parallelization Opportunities If you break some dependencies, could enable: - 3 parallel work streams instead of 2 sequential - Reduce critical path from 15 days to 8 days - Increase team throughput by ~40% Would you like me to suggest specific dependency changes?
Phase 5: Find Independent Stories
Goal: Identify stories that can start immediately.
Analysis:
- •
Find Root Nodes (no blocked_by dependencies):
bashpython3 .claude/skills/dependency-analyzer/scripts/check_dependencies.py --find-independent
- •
Present Ready-to-Start Stories:
code✅ Independent Stories (Can Start Immediately) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ **Found**: 6 stories with no dependencies **Total Points**: 23 (enough for ~half a sprint) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📋 Ready for Development 1. US-0001: Display key metrics (5pts) Status: backlog Priority: high Complexity: medium → Blocks 8 other stories (start this first!) 2. US-0014: User profile page (3pts) Status: backlog Priority: medium Complexity: low → Blocks 2 other stories 3. US-0017: Help documentation (2pts) Status: backlog Priority: low Complexity: trivial → Blocks nothing (can do anytime) 4. US-0020: Terms of service page (1pt) Status: backlog Priority: low Complexity: trivial → Blocks nothing 5. US-0022: Logo upload (3pts) Status: backlog Priority: medium Complexity: low → Blocks 1 other story 6. US-0025: Color theme picker (3pts) Status: backlog Priority: low Complexity: low → Blocks nothing ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 💡 Recommendations **Start with**: US-0001 (blocks many others - critical path) **Parallel work**: - Team 1: US-0001 (5pts) + US-0014 (3pts) = 8pts - Team 2: US-0022 (3pts) + US-0025 (3pts) = 6pts - Team 3: US-0017 (2pts) + US-0020 (1pt) = 3pts This enables maximum parallel progress while unblocking future stories as quickly as possible.
Phase 6: Identify Bottleneck Stories
Goal: Find stories that block many others.
Analysis:
- •
Find High-Degree Nodes:
bashpython3 .claude/skills/dependency-analyzer/scripts/check_dependencies.py --find-bottlenecks --threshold 3
- •
Present Bottleneck Stories:
code⚠️ Bottleneck Stories Detected ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ **Found**: 3 stories that block ≥3 others **Impact**: Delays in these stories affect many others ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🚧 Critical Bottlenecks 1. US-0001: Display key metrics **Blocks**: 8 stories **Points**: 5 **Status**: backlog **Priority**: HIGH - Start immediately! Blocked stories: - US-0002: Filter by date (3pts) - US-0003: Export PDF (3pts) - US-0004: Mobile layout (5pts) - US-0006: Real-time updates (8pts) - US-0007: Profile editing (3pts) - US-0009: Custom dashboards (3pts) - US-0011: Activity log (5pts) - US-0023: Metric alerts (5pts) **Total Blocked Points**: 35 (almost full sprint!) 2. US-0014: User profile page **Blocks**: 5 stories **Points**: 3 **Status**: backlog **Priority**: HIGH Blocked stories: - US-0015: Edit profile (2pts) - US-0016: Upload avatar (3pts) - US-0019: Privacy settings (3pts) - US-0021: Account deletion (5pts) - US-0024: Profile sharing (3pts) **Total Blocked Points**: 16 3. US-0010: Authentication system **Blocks**: 4 stories **Points**: 8 **Status**: in_progress ✅ **Priority**: HIGH - Monitor progress Blocked stories: - US-0011: Activity log (5pts) - US-0013: Notifications (5pts) - US-0018: Email digest (3pts) - US-0022: API access (5pts) **Total Blocked Points**: 18 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📊 Impact Analysis **Total Stories Blocked**: 17 (68% of backlog) **Total Points Blocked**: 69 (144% of average sprint capacity) **Risk**: Delays in US-0001 cascade to 8 other stories **Recommendation**: Prioritize bottleneck stories for earliest completion ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🔧 Mitigation Strategies **US-0001 (Blocks 8)**: 1. Assign to most experienced developer 2. Review dependencies - are all 8 truly blocked? 3. Consider extracting shared foundation to unblock others sooner 4. Add extra testing/review to avoid rework **US-0014 (Blocks 5)**: 1. Start immediately after US-0001 begins 2. Can work in parallel with US-0001 3. Profile stories are all low-medium complexity **US-0010 (In Progress)**: 1. Monitor daily progress 2. Ensure no blockers for this story 3. 4 stories waiting - communicate timeline ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 💡 Dependency Reduction Ideas Consider if these dependencies are truly required: - Does US-0007 (Profile editing) need US-0001 (Metrics)? - Does US-0023 (Metric alerts) need full US-0001, or just API? - Can any blocked stories use mock/partial data? Reducing unnecessary dependencies could unblock 2-3 stories.
Phase 7: Generate Dependency Graph
Goal: Create visual Mermaid diagram.
Analysis:
- •
Generate Diagram:
bashpython3 .claude/skills/dependency-analyzer/scripts/check_dependencies.py --output-diagram deps.mmd
- •
Read Mermaid File:
mermaidgraph TD US0001[US-0001: Display key metrics<br/>5pts - HIGH] US0002[US-0002: Filter by date<br/>3pts - MEDIUM] US0003[US-0003: Export PDF<br/>3pts - MEDIUM] US0004[US-0004: Mobile layout<br/>5pts - MEDIUM] US0001 --> US0002 US0001 --> US0003 US0001 --> US0004 US0002 --> US0006 US0003 --> US0006 classDef bottleneck fill:#ff6b6b classDef independent fill:#51cf66 classDef blocked fill:#ffd43b class US0001 bottleneck class US0002,US0003,US0004 blocked - •
Present Diagram:
code📊 Dependency Graph Generated ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ **File**: stories/analysis/dependency-graph.mmd **Stories**: 25 **Dependencies**: 32 **Layers**: 6 (max dependency depth) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🎨 Color Legend 🔴 Red (Bottleneck): Blocks ≥3 stories 🟢 Green (Independent): No dependencies, can start now 🟡 Yellow (Blocked): Waiting on other stories ⚪ White (Normal): Standard dependency ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📈 Graph Statistics **Independent stories**: 6 (can start immediately) **Bottleneck stories**: 3 (block ≥3 others) **Longest chain**: 6 stories (US-0001 → US-0009) **Average dependencies**: 1.3 per story ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 💡 How to View Option 1: GitHub/GitLab - Push the .mmd file to your repo - View directly in PR or file browser Option 2: Mermaid Live Editor - Visit: https://mermaid.live - Paste contents of dependency-graph.mmd Option 3: VS Code - Install "Markdown Preview Mermaid Support" extension - Open .mmd file and preview Option 4: Embed in documentation - Copy .mmd contents into markdown file - Surround with ```mermaid code fence
Phase 8: Optimization Suggestions
Goal: Recommend ways to improve dependency structure.
Analysis:
💡 Dependency Optimization Recommendations ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ **Goal**: Reduce blocking, enable parallel work ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🎯 High-Impact Changes 1. **Break US-0004 → US-0003 dependency** Current: Mobile layout depends on PDF export Suggested: Remove this dependency (likely unnecessary) Impact: Enables 1 story to work in parallel (+5 pts capacity) 2. **Split US-0001 into foundation + enhancements** Current: US-0001 blocks 8 stories (major bottleneck) Suggested: - US-0001a: Basic metrics display (3pts) - US-0001b: Advanced metrics features (2pts) Impact: Unblocks 5 stories earlier (saves ~3-5 days) 3. **Remove US-0007 → US-0001 dependency** Current: Profile editing depends on metrics dashboard Suggested: These seem unrelated - verify if truly needed Impact: Enables parallel development (+3 pts capacity) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🔧 Medium-Impact Changes 4. **Merge US-0012 ↔ US-0015 (circular dependency)** Current: Mutual blocking (deadlock) Suggested: Merge into single story or reverse dependency Impact: Resolves deadlock, enables 2 stories 5. **Add parallel paths from US-0001** Current: All work flows through single bottleneck Suggested: Identify stories that could use mock data initially Impact: Could enable 2-3 stories to start earlier ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📊 Projected Impact **Before optimizations**: - Parallel capacity: ~15 story points - Critical path: 15 days - Stories ready to start: 6 **After optimizations**: - Parallel capacity: ~28 story points (+87%) - Critical path: 8-9 days (-40%) - Stories ready to start: 11 (+83%) **Result**: ~50% faster feature delivery with same team size ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Would you like me to: 1. Show detailed analysis for specific dependencies 2. Help update story YAMLs to implement these changes 3. Generate new dependency graph showing optimized structure
Summary Report Format
Comprehensive analysis output:
📊 Dependency Analysis Report ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ Generated: 2025-01-03 15:30:00 Stories Analyzed: 25 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📈 Overall Statistics Total Stories: 25 Total Dependencies: 32 Average Dependencies per Story: 1.28 Max Dependency Depth: 6 levels Status Breakdown: - Backlog: 18 stories (72%) - In Progress: 5 stories (20%) - Done: 2 stories (8%) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ✅ Independent Stories: 6 Ready to start immediately (no blockers) Total points available: 23 ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🚧 Bottleneck Stories: 3 Stories blocking ≥3 others Total downstream impact: 69 story points ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 🔗 Longest Chains: 2 Max chain length: 6 stories Critical path: 15 days minimum ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ ⚠️ Issues Detected: 2 Circular Dependencies: 2 cycles (5 stories affected) Long Chains: 2 chains (>5 stories each) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📊 Dependency Health Score: 72/100 Breakdown: - No circular deps: 0/25 (critical issue) - Reasonable chain length: 15/25 (2 long chains) - Balanced dependencies: 20/25 (3 bottlenecks) - Independent stories: 12/25 (good) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 💡 Key Recommendations 1. CRITICAL: Resolve 2 circular dependencies (blocks 5 stories) 2. HIGH: Address bottleneck stories (especially US-0001) 3. MEDIUM: Review long chains for optimization opportunities ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 📁 Files Generated - stories/analysis/dependency-graph.mmd (visual diagram) - stories/analysis/dependency-report.json (full data) - stories/analysis/independent-stories.txt (ready to start) - stories/analysis/bottlenecks.txt (high-priority stories) ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Integration with Scripts
Main Analysis Script
# Full analysis with JSON output python3 .claude/skills/dependency-analyzer/scripts/check_dependencies.py --output-json # Generate Mermaid diagram python3 .claude/skills/dependency-analyzer/scripts/check_dependencies.py --output-diagram deps.mmd # Find specific issues python3 .claude/skills/dependency-analyzer/scripts/check_dependencies.py --check-cycles python3 .claude/skills/dependency-analyzer/scripts/check_dependencies.py --check-chains --max-length 5 python3 .claude/skills/dependency-analyzer/scripts/check_dependencies.py --find-independent python3 .claude/skills/dependency-analyzer/scripts/check_dependencies.py --find-bottlenecks --threshold 3
Error Handling
No Stories Found
⚠️ No stories found Directory: stories/yaml-source/ Files found: 0 This usually means: - No stories have been created yet - Stories are in a different directory - File permissions prevent reading Create stories first using user-story-generator skill.
Invalid Dependency Reference
⚠️ Invalid dependency detected In story: US-0005 References: US-9999 (does not exist) This story references a non-existent story. Fix options: 1. Remove the invalid dependency 2. Create US-9999 if it should exist 3. Correct the story ID (typo?) Would you like me to show US-0005 details?
Conflicting Dependencies
⚠️ Conflicting dependencies
US-0005:
dependencies:
blocked_by: [US-0008]
US-0008:
dependencies:
blocks: [US-0010] # Does not list US-0005
Inconsistency: US-0005 says it's blocked by US-0008,
but US-0008 doesn't list US-0005 in its "blocks" field.
Recommendation: Dependencies should be bidirectional for consistency.
Auto-fix: Add US-0005 to US-0008's "blocks" array? (yes/no)
Configuration
Uses settings from .claude/skills/user-story-generator/config/automation-config.yaml:
dependencies: check_circular: true max_depth: 10 # Warn if dependency chain exceeds this warn_on_long_chains: true max_chain_length: 5 # Chains longer than this trigger warning bottleneck_threshold: 3 # Stories blocking ≥ this many are bottlenecks
Best Practices
Dependency Management
- •Keep chains short (≤5 stories ideal)
- •Avoid circular dependencies (always)
- •Minimize bottlenecks (stories blocking many)
- •Maximize independent stories (enables parallel work)
When to Analyze
- •Always: Before sprint planning
- •Usually: After adding/modifying stories
- •Sometimes: Mid-sprint to check progress
- •Rarely: During development (changes are risky)
Interpreting Results
- •Independent stories: Start these first to maximize progress
- •Bottleneck stories: Prioritize to unblock others
- •Long chains: Look for optimization opportunities
- •Circular dependencies: Must be resolved immediately
Examples
Example 1: Quick Check
Input: "Check dependencies"
Output:
📊 Quick Dependency Check Stories: 25 Dependencies: 32 Independent: 6 ✅ Bottlenecks: 3 ⚠️ Circular: 0 ✅ Long chains: 2 ⚠️ Overall: Generally healthy with some optimizations possible
Example 2: Pre-Sprint Planning
Input: "Analyze dependencies for sprint planning"
Output:
[Full analysis with all sections] Sprint Planning Recommendations: - 6 stories can start immediately (23 pts) - Prioritize US-0001 (blocks 8 others) - Resolve circular dependency before sprint - Plan for 2-3 parallel work streams
Remember
- •Visual First: Dependency graphs are powerful communication tools
- •Action-Oriented: Always provide specific next steps
- •Risk-Aware: Highlight blocking issues prominently
- •Optimization-Focused: Suggest improvements
- •Planning-Friendly: Format output for sprint planning use