map-dependencies

name	map-dependencies
description	Use when asked to find dependencies between issues or prepare a dependency-aware sprint plan.
disable-model-invocation	true
model	sonnet
allowed-tools	["Read","Glob","Grep","Bash(ll-deps:*, git:*)"]
metadata	{"short-description":"Use when asked to find dependencies between issues or prepare a dependency-aware"}

Map Dependencies Skill

This skill performs cross-issue dependency analysis to discover missing relationships, validate existing references, and propose new dependency links using the canonical 6-field relationship vocabulary.

Canonical Relationship Fields

Issues use six frontmatter fields to express relationships:

Field	Type	Meaning	Ordering
parent	string	Parent issue this was decomposed from	—
blocked_by	list	Hard dependencies — ──→ — must complete before this issue can start (wave-gated)	Hard stop
depends_on	list	Soft ordering prerequisites — --> — wave-gated (scheduled in a later wave) but non-fatal if the prerequisite is absent	Soft
relates_to	list	Thematically related issues (no ordering constraint)	—
duplicate_of	string	Superseded by another issue	—
blocks	list	Computed inverse of blocked_by; written by ll-deps fix	—

Use blocked_by only when ISSUE-B must complete before ISSUE-A can start. For preferred-but-not-required ordering, use depends_on instead.

When to Activate

Proactively offer or invoke this skill when the user:

• Asks about issue dependencies or relationships
• Wants to find which issues overlap or conflict
• Is preparing for sprint planning and needs dependency context
• Asks to validate or check existing dependency references
• Mentions missing or broken dependency links
• Wants a dependency graph visualization

Arguments

$ARGUMENTS

Parse arguments for flags:

AUTO_MODE=false
CHECK_MODE=false

# Auto-enable in automation contexts
if [[ "$ARGUMENTS" == *"--dangerously-skip-permissions"* ]] || [[ -n "${LL_NON_INTERACTIVE:-}" ]] || [[ -n "${DANGEROUSLY_SKIP_PERMISSIONS:-}" ]]; then AUTO_MODE=true; fi

# Explicit flags
if [[ "$ARGUMENTS" == *"--auto"* ]]; then AUTO_MODE=true; fi
if [[ "$ARGUMENTS" == *"--check"* ]]; then CHECK_MODE=true; AUTO_MODE=true; fi

• flags (optional):
  • --auto - Non-interactive mode: apply all HIGH-confidence dependency proposals (≥0.7 conflict score) without prompting. Skip MEDIUM-confidence proposals.
  • --check — Check-only mode for FSM loop evaluators. Run dependency analysis without applying changes, print [ID] deps: N unmapped dependencies per issue with unmapped deps, exit 1 if any unmapped, exit 0 if all mapped. Implies --auto.

How to Use

Run the ll-deps CLI command based on user needs:

Full Analysis

For comprehensive dependency analysis (file overlaps + validation):

ll-deps analyze

With Dependency Graph

Include an ASCII dependency graph visualization:

ll-deps analyze --graph

JSON Output

For programmatic access:

ll-deps analyze --format json

Sprint-Scoped Analysis

Restrict analysis to only issues in a named sprint:

ll-deps analyze --sprint my-sprint
ll-deps analyze --sprint my-sprint --graph
ll-deps validate --sprint my-sprint

Validation Only

Check existing dependency references for broken refs, cycles, and missing backlinks:

ll-deps validate
ll-deps validate --json

Note: ll-deps validate uses --json/-j for structured output (consistent with most ll-* CLIs), while ll-deps analyze uses --format json. This is a known pattern inconsistency — analyze predates the universal --json contract.

EPIC Tree View

Render an EPIC's child issue hierarchy with dependency edges:

ll-deps tree --epic EPIC-1773          # Text tree with ├──/└── connectors
ll-deps tree --epic EPIC-1773 -f json  # Structured JSON (root, nodes, edges)

Custom Issues Directory

If issues are not in the default .issues directory:

ll-deps -d path/to/issues analyze

Examples

User Says	Action
"Find missing dependencies"	ll-deps analyze
"Check dependency references"	ll-deps validate
"Show dependency graph"	ll-deps analyze --graph
"Are there broken dependency links?"	ll-deps validate
"Prepare for sprint planning"	ll-deps analyze --graph
"Analyze deps for my sprint"	ll-deps analyze --sprint <name>
"Validate sprint dependencies"	ll-deps validate --sprint <name>
"Which issues conflict?"	ll-deps analyze
"Map deps non-interactively"	/ll:map-dependencies --auto
"Check if all deps are mapped"	/ll:map-dependencies --check
"Show EPIC child hierarchy"	ll-deps tree --epic EPIC-NNN
"EPIC tree as JSON"	ll-deps tree --epic EPIC-NNN --format json

Interpreting Results

Proposed Dependencies

The analysis identifies issue pairs that reference overlapping files and computes a semantic conflict score:

• HIGH conflict (>= 0.7): Issues modify the same component/section — strong dependency
• MEDIUM conflict (>= 0.4): Issues share files with moderate semantic overlap
• Confidence: Based on file overlap ratio (higher = more overlapping files)

Direction is determined by:

1. Priority: Higher priority issue blocks lower
2. Modification type: Structural blocks infrastructure blocks enhancement
3. Fallback: ID ordering with reduced confidence

Parallel-Safe Pairs

Pairs with conflict score < 0.4 are reported as safe to run in parallel. These touch the same files but different sections/components.

Validation Issues

• Broken references: ## Blocked By entries referencing nonexistent issues
• Missing backlinks: A blocked by B, but B doesn't list A in Blocks
• Cycles: Circular dependency chains
• Stale references: Dependencies on already-completed issues
• Broken depends-on references: depends_on frontmatter entries referencing nonexistent issues
• Broken relates-to references: relates_to frontmatter entries referencing nonexistent issues

Applying Proposals

After reviewing the analysis output, apply proposed dependencies using ll-deps apply:

ll-deps apply                           # Apply all proposals >= 0.7 confidence
ll-deps apply --min-confidence 0.5      # Lower threshold
ll-deps apply --dry-run                 # Preview without writing
ll-deps apply --sprint my-sprint        # Sprint-scoped apply
ll-deps apply FEAT-001 blocks FEAT-002  # Manual explicit pair

ll-deps apply writes only the ## Blocked By direction. Run ll-deps fix afterward to add missing ## Blocks backlinks, then ll-deps validate to confirm a clean state.

Auto Mode Behavior

When AUTO_MODE is true: Skip the AskUserQuestion prompt below. Run ll-deps apply automatically (default threshold 0.7). Emit one status line per applied proposal: [SOURCE-ID] → [TARGET-ID]: dependency added (confidence: HIGH)

Check Mode Behavior (--check)

When CHECK_MODE is true: Run dependency analysis without applying any changes. For each issue with unmapped dependencies (HIGH-confidence proposals not yet in ## Blocked By), print [ID] deps: N unmapped dependencies. After all issues analyzed, if any had unmapped deps: print N issues with unmapped dependencies, then exit 1. If all mapped: print All dependencies mapped, then exit 0. This integrates with FSM evaluate: type: exit_code routing.

Interactive Mode (default)

1. Use AskUserQuestion to confirm which proposals to apply:

   • "Apply all" — run ll-deps apply
   • "Select individually" — run ll-deps apply <source> blocks <target> per pair
   • "Skip all" — don't write changes

2. After applying, fix backlinks and validate:

ll-deps fix
ll-deps validate

3. Stage changes. ll-deps fix rewrites backlinks across an open-ended set of tracked issue files, so stage tracked modifications only — do not add the whole directory, which would also sweep in unrelated untracked drafts under .issues/ (BUG-1976):

git add -u {{config.issues.base_dir}}/

Configuration

Uses project configuration from .ll/ll-config.json:

• issues.base_dir - Base directory for issues (default: .issues)
• issues.categories - Bug/feature/enhancement directory config
• sprints.sprints_dir - Sprint definitions directory (default: .sprints)

Integration

After running dependency mapping:

• Review changes with git diff
• Commit with /ll:commit
• Use /ll:create-sprint for dependency-aware sprint planning
• Run ll-sprint show [name] to see execution wave structure
• Use /ll:verify-issues to validate dependency integrity

Best Practices

Good Dependencies

• Based on file overlap + semantic conflict — issues modifying the same component/section should be sequenced
• Priority ordering — higher priority issues block lower priority ones
• Modification type ordering — structural changes block infrastructure, which blocks enhancements (at same priority)
• Dependencies represent real sequencing needs, not just related topics

Parallel-Safe Pairs

• Issues touching the same file but different sections (e.g., header vs body) are identified as parallel-safe
• The conflict score threshold is 0.4 — pairs below this are not proposed as dependencies
• Review parallel-safe pairs to confirm the tool's assessment is correct for your context

Avoid

• Creating dependencies between unrelated issues just because they have similar titles
• Circular dependencies (the tool will warn about these)
• Over-connecting — not every pair of related issues needs a dependency edge
• Overriding parallel-safe assessments without good reason — false-positive dependencies reduce sprint throughput