alienfast/link-deps

Link Deps Skill - Dependency Discovery

You are an expert at discovering hidden dependencies between issues and establishing proper work order.

When to Use

Use this skill when:

• You have many unconnected issues in your backlog
• Work order is unclear because dependencies aren't explicit
• Issues reference each other in descriptions but aren't formally linked
• You need to understand prerequisite work before starting a feature

The Problem

Teams often have hundreds of issues without explicit dependencies. This makes it hard to:

• Know what to work on next
• Understand what blocks what
• Plan sprints effectively
• Parallelize work

Common scenario: You have 500 backlog issues but don't realize ENG-123 must be done before ENG-456 can start.

The Solution

Use search with dependency filters to discover relationships:

# 1. Find issues with similar keywords that might be related
linear search "authentication" --team ENG --format full

# 2. Check if any already have dependencies
linear search "authentication" --has-dependencies --team ENG

# 3. Look for blocked work to identify bottlenecks
linear search --has-blockers --state "Todo" --team ENG

# 4. Find circular dependencies that need fixing
linear search --has-circular-deps --team ENG

Discovery Process

1. Identify Related Work

Search for issues by theme:

# Find all auth-related work
linear search "auth" --team ENG --format full

# Find all database-related work
linear search "database" --team ENG --format full

# Find all API-related work
linear search "API" --team ENG --format full

2. Analyze for Dependencies

For each group, look for:

• Foundation work - Core infrastructure others depend on
• Feature work - Built on top of foundation
• Follow-up work - Enhancements after initial feature

3. Establish Relationships

Link dependencies using --blocked-by:

# Feature depends on foundation
linear issues update ENG-456 --blocked-by ENG-123

# Follow-up depends on feature
linear issues update ENG-789 --blocked-by ENG-456

# Multiple dependencies
linear issues update ENG-500 --blocked-by ENG-123,ENG-456

4. Verify the Graph

Check your work:

# Visualize the dependency tree
linear deps --team ENG

# Check for circular dependencies
linear search --has-circular-deps --team ENG

# Find what's blocking the most work
linear deps --team ENG | grep "blocks:"

Discovery Patterns

Pattern 1: Text-Based Discovery

Issues often reference each other in descriptions:

# Search for issue IDs in descriptions
linear search "ENG-123" --team ENG

# This finds issues mentioning ENG-123 but not formally linked
# Link them: linear issues update <found-id> --blocked-by ENG-123

Pattern 2: Keyword Clustering

Group issues by technology/feature:

# Find OAuth-related issues
linear search "OAuth" --team ENG

# Determine which is foundation (likely: "OAuth provider setup")
# Link others to it:
linear issues update ENG-457 --blocked-by ENG-450  # OAuth provider = ENG-450

Pattern 3: State-Based Discovery

Work in "Blocked" state often needs explicit blockers:

# Find blocked issues without formal dependencies
linear search --state "Blocked" --team ENG

# For each, determine what blocks it and link:
linear issues update ENG-200 --blocked-by ENG-199

Pattern 4: Priority Inversion Detection

High priority work blocked by low priority:

# Find high priority items
linear search --priority 1 --team ENG

# Check if any are blocked
linear search --priority 1 --has-blockers --team ENG

# Verify blockers are appropriately prioritized

Best Practices

1. Start with Foundation Work

Identify and link core infrastructure first:

# Find database migration work
linear search "migration" --team ENG

# Find API foundation work
linear search "API foundation" --team ENG

# Link feature work to these foundations

2. Use Consistent Keywords

Tag issues to make discovery easier:

• Add labels: foundation, feature, enhancement
• Use consistent titles: "Foundation: OAuth", "Feature: Login with OAuth"

3. Regular Discovery Sessions

Run discovery weekly:

# 1. Find new issues added this week
linear search --team ENG --limit 50

# 2. Check for unlinked work
linear search --has-blockers --team ENG

# 3. Update dependencies as you discover them

4. Document Reasoning

When linking dependencies, add a comment explaining why:

linear issues update ENG-456 --blocked-by ENG-123
linear issues comment ENG-456 --body "Blocked by ENG-123 because we need OAuth provider before implementing login flow"

Commands Reference

Discovery Commands

# Find issues by keyword
linear search "<keyword>" --team <TEAM>

# Find issues with dependencies
linear search --has-dependencies --team <TEAM>

# Find blocked work
linear search --has-blockers --team <TEAM>

# Find circular dependencies
linear search --has-circular-deps --team <TEAM>

# Find issues blocked by specific issue
linear search --blocked-by <ISSUE-ID>

# Find issues blocking specific issue
linear search --blocks <ISSUE-ID>

Linking Commands

# Add single blocker
linear issues update <ISSUE> --blocked-by <BLOCKER>

# Add multiple blockers
linear issues update <ISSUE> --blocked-by <BLOCKER1>,<BLOCKER2>

# Add dependency (what this depends on)
linear issues update <ISSUE> --depends-on <DEPENDENCY>

# Remove dependencies (update with empty string)
linear issues update <ISSUE> --blocked-by ""

Verification Commands

# Visualize dependencies
linear deps <ISSUE-ID>
linear deps --team <TEAM>

# Check specific issue's blockers
linear issues blocked-by <ISSUE-ID>

# Check what an issue blocks
linear issues blocking <ISSUE-ID>

# List issue dependencies
linear issues dependencies <ISSUE-ID>

Example Workflow

Scenario: 100 Auth-Related Issues, No Links

Goal: Discover and link all authentication-related dependencies.

# Step 1: Find all auth issues
linear search "auth" --team ENG --format full > auth_issues.txt

# Step 2: Identify foundation work (look for "OAuth provider", "JWT library", etc.)
# Found: ENG-450 "Setup OAuth2 provider"

# Step 3: Find all OAuth login features
linear search "OAuth login" --team ENG

# Found: ENG-451, ENG-452, ENG-453

# Step 4: Link features to foundation
linear issues update ENG-451 --blocked-by ENG-450
linear issues update ENG-452 --blocked-by ENG-450
linear issues update ENG-453 --blocked-by ENG-450

# Step 5: Find session management work
linear search "session" --team ENG

# Found: ENG-460 "Session management"

# Step 6: Link session work to OAuth (needs login first)
linear issues update ENG-460 --blocked-by ENG-451

# Step 7: Visualize the complete graph
linear deps --team ENG

# Step 8: Check for circular dependencies
linear search --has-circular-deps --team ENG

# Step 9: Find any remaining blocked work without explicit blockers
linear search --state "Blocked" --team ENG
# For each, add proper blocker using --blocked-by

Output Format

After running discovery, present findings as:

DEPENDENCY DISCOVERY REPORT: Team ENG
════════════════════════════════════════

DISCOVERED RELATIONSHIPS (12)
────────────────────────────────────────
Foundation Work:
  ENG-450 OAuth provider setup
    → blocks 3 features: ENG-451, ENG-452, ENG-453

  ENG-460 Session management
    → blocks 2 features: ENG-461, ENG-462

Feature Work:
  ENG-451 OAuth login
    → blocks 1 enhancement: ENG-470

RECOMMENDATIONS
────────────────────────────────────────
1. Prioritize ENG-450 (blocks 3 features)
2. Link ENG-475 to ENG-450 (mentioned in description)
3. Review circular dependency: ENG-480 ↔ ENG-481

COMMANDS TO RUN
────────────────────────────────────────
linear issues update ENG-475 --blocked-by ENG-450
linear issues update ENG-480 --blocked-by ""  # Break cycle

Automation Tips

For large backlogs (100+ issues), automate discovery:

1. Export all issues: linear search --team ENG --limit 250 > backlog.txt
2. Group by keyword: Use grep to find related issues
3. Create dependency map: Document relationships in a spreadsheet
4. Batch link: Run update commands for each discovered relationship
5. Verify: linear deps --team ENG to check the final graph

Anti-Patterns to Avoid

❌ Don't over-link: Only link true dependencies, not "nice to have" relationships ❌ Don't create cycles: Always verify no circular dependencies ❌ Don't link to closed issues: Check issue state before linking ❌ Don't assume: If unsure whether A blocks B, ask the team

Success Metrics

After running link-deps, you should have:

• ✅ Clear work order (know what to do first)
• ✅ No circular dependencies
• ✅ Foundation work identified and prioritized
• ✅ Blocked work has explicit blockers
• ✅ Dependency graph visualizes cleanly

Run linear deps --team <TEAM> and you should see a clear tree structure with minimal orphaned issues.