Dependency Manager

dependency-manager — Dependency Visualization, Creation, and Diagnosis

Manage BLOCKS, IS_BLOCKED_BY, and RELATES_TO edges between work items. Handles all four paths: view existing dependencies, create new edges, delete edges, and diagnose why items cannot start.

Step 1: Determine Intent

Classify the user request before making any tool calls.

Resolve $ARGUMENTS to a UUID via query_items search (operation="search", query=$ARGUMENTS, limit=5); if ambiguous, present matches via AskUserQuestion. If $ARGUMENTS is already a UUID, default intent to VIEW for that item.

If $ARGUMENTS is empty, infer intent from the surrounding conversation. If intent is still unclear, ask via AskUserQuestion: "What would you like to do with dependencies? Options: view, create, delete, diagnose."

Compound requests (e.g., "show what blocks this and remove the dependency"): handle the VIEW path first, then proceed to the second action using the results.

Intent signal words:

Step 2: View Dependencies

Once you have an item ID and intent is VIEW, query its dependency edges:

Copy code
query_dependencies(operation="get", itemId="<uuid>", direction="all", includeItemInfo=true)

Format the result as an ASCII tree:

Copy code
◉ Design API schema (work)
  ↳ BLOCKS → ○ Implement data models (queue)
  ↳ BLOCKS → ○ Build REST endpoints (queue)
  ← BLOCKED BY → ◉ Finalize data contract (work)

Use the visual symbols to indicate role at a glance:

Direction parameter meanings:

For a full chain view (ancestors and descendants beyond immediate neighbors), add neighborsOnly=false:

Copy code
query_dependencies(operation="get", itemId="<uuid>", direction="all", includeItemInfo=true, neighborsOnly=false)

This performs BFS traversal and returns the full dependency graph. Use it when the user asks to "show the full chain" or "trace all blockers."

After displaying the tree, note any items in ⊘ blocked state and offer to run DIAGNOSE (Step 5) on them.

Step 3: Create Dependencies

Identify the structure from what the user described, then select the right creation pattern.

Decision tree:

Copy code
Two specific items to link → single edge (dependencies array)
Three or more items in a sequence (A then B then C) → linear pattern
One item that blocks many others → fan-out pattern
Many items that all block one item → fan-in pattern

Pattern reference:

Confirm the derived edges with the user before creating. Show them what you're about to create in a readable way, for example:

Copy code
About to create: A → B → C → D as a linear chain. Proceed?

Adjust the format to fit the actual pattern (single edge, fan-out, fan-in, etc.).

Then call manage_dependencies(operation="create") with the selected pattern:

Copy code
manage_dependencies(
  operation="create",
  pattern="linear",
  itemIds=["<uuid-a>", "<uuid-b>", "<uuid-c>", "<uuid-d>"]
)

For a single edge or custom edges, use the dependencies array directly:

Copy code
manage_dependencies(
  operation="create",
  dependencies=[
    { fromItemId: "<uuid-a>", toItemId: "<uuid-b>", type: "BLOCKS" }
  ]
)

After creation, show the edges created:

Copy code
✓ Created 3 dependency edges:
  A → BLOCKS → B
  B → BLOCKS → C
  C → BLOCKS → D

To set a partial unblock threshold (so the blocked item unblocks before the blocker is terminal), include unblockAt in the dependency spec. See the unblockAt reference table below.

Step 4: Delete Dependencies

Query existing edges first so the user knows what can be deleted:

Copy code
query_dependencies(operation="get", itemId="<uuid>", direction="all", includeItemInfo=true)

Present the edges to the user:

Copy code
Existing edges for "Implement data models":
  [1] ◉ Design API schema → BLOCKS → this item  (dep-uuid-1)
  [2] this item → BLOCKS → ○ Build REST endpoints  (dep-uuid-2)

Which edge(s) would you like to remove?

Confirm before deleting. Then call manage_dependencies(operation="delete") using the appropriate mode:

Copy code
manage_dependencies(operation="delete", dependencyId="<dep-uuid>")

Delete parameter modes:

After deletion, confirm:

Copy code
✓ Removed: Design API schema → BLOCKS → Implement data models

Step 5: Diagnose Blocked Items

For DIAGNOSE intent, identify why a specific item cannot start or is stuck in blocked state.

Path A — User provided an item ID:

Copy code
query_dependencies(operation="get", itemId="<uuid>", direction="incoming", includeItemInfo=true)

Path B — User wants a broad view of all blocked work:

Copy code
get_blocked_items(includeDetails=true)

For each blocker returned, show:

Copy code
⊘ "Build REST endpoints" cannot start because:

  Blocker 1: ◉ Design API schema (work)
    Must reach: terminal (unblockAt: terminal)
    Action: advance Design API schema to terminal first

  Blocker 2: ○ Write OpenAPI spec (queue)
    Must reach: terminal (unblockAt: terminal)
    Action: start and complete Write OpenAPI spec first

For each blocker, determine what must happen:

If any blocker is itself blocked, offer to recurse: "The blocker is also blocked. Would you like to diagnose that item too?"

Not every "why can't this start" is a dependency. This skill diagnoses BLOCKED-role items and unsatisfied BLOCKS edges only. A separate, unrelated cause can produce a similar symptom: advance_item rejecting a start/resume transition with errorCode: "resource_unavailable" (errorKind: "transient") — a shared resource the item declares via a resources: trait is currently held by another item. That item's role does not change to blocked; it stays in its current role (typically queue) and the transition simply fails transiently. If query_dependencies shows no incoming edges yet the item still won't advance, suspect resource contention instead — check the advance_item error for errorCode/contendedResources, or inspect get_context(itemId=...) → resourceLeases for the item's declared/held keys. Do not treat this as a dependency problem; retrying the dependency diagnosis will not help.

After the diagnosis, link to the resolution path:

• To advance the blocking item: use /status-progression with its UUID
• To fill missing notes on the blocker first: use manage_notes(operation="upsert") to fill required notes

Dependency Type Reference

unblockAt Threshold Reference

Troubleshooting

Problem: Cycle detection error when creating a dependency

Cause: The proposed edge would create a circular dependency chain (A blocks B, B blocks C, C blocks A). The server detects this and rejects the entire batch atomically.

Solution: Review the dependency direction. One of the edges is backwards. Identify which item actually depends on the other, flip the fromItemId and toItemId on that edge, and retry.

Problem: "dependency not found" error on delete

Cause: The dependency UUID or relationship does not exist. The edge may have already been deleted, or the IDs are from a different environment.

Solution: Re-query to confirm current state:

Copy code
query_dependencies(operation="get", itemId="<uuid>", direction="all", includeItemInfo=true)

Use a dependency UUID from the fresh query result for the delete call. If the edge is not present, it was already removed.

Problem: Item is still blocked after the blocker reached terminal

Cause: Either the unblockAt threshold is set to a role the blocker has not yet reached (e.g., unblockAt: "review" but the blocker went straight to terminal via complete), or there are additional incoming edges from other items that are not yet satisfied.

Solution: Query incoming edges to check all blockers:

Copy code
query_dependencies(operation="get", itemId="<uuid>", direction="incoming", includeItemInfo=true)

Check each blocker's role. If all blockers are terminal and the item is still in blocked role, use advance_item(transitions=[{itemId: "<uuid>", trigger: "resume"}]) to manually return it to its previous role via /status-progression.

Problem: Pattern shortcut creates wrong edges

Cause: The wrong parameter name was used for the pattern. linear uses itemIds (an ordered array). fan-out uses fromItemId (single UUID) and toItemIds (array). fan-in uses fromItemIds (array) and toItemId (single UUID). Mixing these up creates edges in the wrong direction or fails silently.

Solution: Double-check the parameter names against the pattern table in Step 3. Re-query the item after creation to verify edge direction, and delete any incorrect edges using Step 4.

Examples

Example 1: View dependencies for an item

User: "Show me what blocks the REST endpoints task."

Search → one match uuid-rest. Query incoming deps:

Copy code
query_dependencies(operation="get", itemId="uuid-rest", direction="incoming", includeItemInfo=true)

Display:

Copy code
○ Build REST endpoints (queue)
  ← BLOCKED BY ◉ Design API schema (work)
  ← BLOCKED BY ○ Write OpenAPI spec (queue)

Both blockers must reach terminal. Use /status-progression on each.

Example 2: Create a linear chain

User: "Set up A → B → C → D as a chain." Resolve UUIDs, confirm, then:

Copy code
manage_dependencies(operation="create", pattern="linear",
  itemIds=["uuid-a", "uuid-b", "uuid-c", "uuid-d"])

Result:

Copy code
✓ Created 3 edges: A → B → C → D

Example 3: Diagnose why an item cannot start

User: "Why can't 'Write integration tests' start?" Search → uuid-tests. Query incoming:

Copy code
query_dependencies(operation="get", itemId="uuid-tests", direction="incoming", includeItemInfo=true)

Display:

Copy code
⊘ "Write integration tests" cannot start:
  Blocker 1: ○ Build REST endpoints (queue) — must reach terminal
  Blocker 2: ◉ Implement data models (work) — must reach terminal

Recommended: complete both blockers via /status-progression

Quick Decision Guide