gh-jpicklyk-task-orchestrator-claude-plugins-task-orchestrator/skills/dependency-analysis/troubleshooting.md

Dependency Analysis Skill - Troubleshooting Guide

Common Dependency Issues

Issue 1: Tasks Stuck in "Pending" Despite No Dependencies

Symptoms:

• Task shows status="pending"
• get_task_dependencies returns empty list
• Task has been pending for days
• get_blocked_tasks doesn't include this task

Possible Causes:

Cause A: Task Never Started

Problem: Task has no dependencies but hasn't been assigned or started

Diagnosis:

get_task(id="task-id")
// Check: assignedTo field empty? No start date?

Solution: Task is actually ready to start, just needs assignment

Response: "This task has no dependencies and is ready to start. It appears
nobody has been assigned yet. Recommend: Assign to [specialist] and begin work."

Cause B: Implicit Dependencies Not Captured

Problem: Real-world dependencies exist but weren't added to system

Diagnosis:

• Check task comments/sections for mentions of "waiting for..."
• Ask user if there are unstated dependencies

Solution: Add missing dependencies

Response: "Task shows no formal dependencies, but team may be waiting for
external factors (access, approval, resources). Recommend: Add explicit
dependencies or start task if truly ready."

Cause C: Completed Dependencies Not Marked

Problem: Dependency tasks are done but status not updated

Diagnosis:

get_task_dependencies(taskId="task-id")
// Check if dependency tasks are actually complete but status=in_progress

Solution: Update dependency statuses

Response: "Task is blocked by 'X', but checking that task shows work is
complete. Recommend: Mark task X as complete to unblock this task."

---

Issue 2: Circular Dependency Not Detected

Symptoms:

• User reports deadlock situation
• Multiple tasks all "waiting" on each other
• get_task_dependencies doesn't show circular reference
• No tasks can start

Possible Causes:

Cause A: Indirect Circular Dependency

Problem: Cycle exists through 3+ tasks, not immediately obvious

Diagnosis:

// Trace full chain for each suspicious task
get_task_dependencies(taskId="A", includeTransitive=true)
get_task_dependencies(taskId="B", includeTransitive=true)
get_task_dependencies(taskId="C", includeTransitive=true)

// Look for task appearing in its own transitive dependencies

Example:

Task A depends on Task B
Task B depends on Task C
Task C depends on Task D
Task D depends on Task A ← Cycle found

Solution: Map full dependency graph, identify cycle, recommend breaking link

Response: "Indirect circular dependency found: A→B→C→D→A.
Recommend: Remove D→A dependency and restructure work to be linear: D→A→B→C"

Cause B: Feature-Level Circular Dependency

Problem: Tasks in Feature X depend on tasks in Feature Y, and vice versa

Diagnosis:

// Check cross-feature dependencies
search_tasks(featureId="feature-X")
// For each task, check if dependencies are in different feature
get_task_dependencies(taskId="task-in-X")
// Does it depend on tasks in Feature Y that depend on Feature X?

Solution: Identify shared foundation work, extract to separate feature

Response: "Features X and Y have circular dependencies. Both need 'Auth Service'.
Recommend: Create new Feature Z 'Shared Authentication' and make both X and Y
depend on it (linear: Z→X, Z→Y)."

---

Issue 3: Tasks Show as Blocked But Dependencies Are Complete

Symptoms:

• get_blocked_tasks returns task
• Checking dependencies shows all are status="completed"
• Task still can't be started

Possible Causes:

Cause A: Database/Cache Inconsistency

Problem: Dependency status cached or not updated in DB

Diagnosis:

// Re-query with fresh data
get_task(id="task-id", includeDependencies=true)

// Check dependency statuses individually
for each dep in dependencies:
  get_task(id=dep.id)

Solution: If all dependencies truly complete, this is a data issue

Response: "All dependencies show as complete but task still marked as blocked.
This may be a caching issue. Recommend: Try updating the task (change and
revert priority) to force refresh, or report this bug."

Cause B: Soft Dependencies

Problem: Task has informal dependencies not captured in system

Diagnosis: Ask user about the task context

Questions to ask:
- "Are there any unstated requirements for this task?"
- "Is the task waiting for approval, access, or resources?"
- "Are there external dependencies outside Task Orchestrator?"

Solution: Document actual blockers

Response: "System shows dependencies complete, but task may be waiting for:
[external dependency]. Recommend: Add comment to task documenting external
blocker, or create placeholder task for external dependency."

---

Issue 4: Dependency Chain Seems Too Long

Symptoms:

• Task has 5+ levels of dependencies
• Critical path is 8+ tasks deep
• Timeline seems unrealistic

Possible Causes:

Cause A: Over-Specified Dependencies

Problem: Dependencies added for tasks that could be parallel

Diagnosis:

get_task_dependencies(taskId="task-id", includeTransitive=true)
// Examine each dependency: is it truly required, or just "nice to have"?

Example of Over-Specification:

Bad:
  "Write API docs" depends on "Implement API" ✓ (correct)
  "Write API docs" depends on "Design database" ✗ (too strict)

Better:
  "Write API docs" depends on "Implement API"
  "Implement API" depends on "Design database"
  (Docs inherit transitive dependency naturally)

Solution: Remove unnecessary direct dependencies

Response: "Dependency chain is 8 tasks deep. Several dependencies are
transitive and don't need explicit links. Recommend: Remove direct dependencies
between 'A' and 'D' (A already depends on B→C→D)."

Cause B: Work Not Properly Parallelized

Problem: Tasks made sequential that could run in parallel

Diagnosis: Look for tasks with same complexity that don't actually conflict

// Example: Frontend and Backend tasks made sequential unnecessarily
Task "Build API" (backend)
Task "Build UI" depends on "Build API"

// But UI could use mock API during development

Solution: Break hard dependencies where possible

Response: "Frontend is waiting for backend completion, but could proceed with
mock API. Recommend: Create task 'Create API mocks' with no dependencies, make
'Build UI' depend on mocks instead of real API. Real API integration happens later."

---

Issue 5: Bottleneck Task Seems Low Priority

Symptoms:

• Task blocks 5+ other tasks
• Task has priority="low" or priority="medium"
• Team is focusing on other work first

Possible Causes:

Cause A: Priority Not Updated

Problem: Task was low priority when created, but importance increased

Diagnosis:

get_task(id="bottleneck-task-id")
// Check: When was priority last updated?
// Compare: How many tasks depend on this?

Solution: Recommend priority adjustment

Response: "Task X is blocking 6 other tasks but has priority='medium'. Based
on impact, this should be priority='critical'. Recommend: Increase priority
to reflect blocking status."

Cause B: Tasks Shouldn't Depend on Bottleneck

Problem: Dependencies were added incorrectly, inflating bottleneck importance

Diagnosis: Review each dependent task

// For each task blocked by bottleneck
for each dependent:
  get_task(id=dependent.id)
  // Question: Does this REALLY need bottleneck to complete first?

Solution: Remove incorrect dependencies

Response: "Task X appears to block 6 tasks, but reviewing dependents shows
3 don't actually need it. Recommend: Remove dependencies from tasks Y and Z
(they can proceed independently)."

---

Issue 6: Feature Appears Stalled Despite Available Work

Symptoms:

• Feature has many pending tasks
• get_blocked_tasks shows most tasks blocked
• Only 1-2 tasks in progress
• Team reports not enough work to do

Possible Causes:

Cause A: Bottleneck Task Not Prioritized

Problem: Root blocker not being worked on actively

Diagnosis:

get_blocked_tasks(featureId="feature-id")
// Identify: What task blocks the most work?
// Check: Is that task in-progress? Assigned?

Solution: Prioritize the bottleneck

Response: "Task 'Setup database' is blocking 8 tasks but hasn't been started.
Recommend: Assign database engineer immediately to unblock majority of feature work."

Cause B: False Perception of Blocking

Problem: Team assumes everything is blocked, but some tasks are ready

Diagnosis:

search_tasks(featureId="feature-id", status="pending")
// For each pending task: get_task_dependencies(taskId=X)
// Filter: Which tasks have NO incomplete dependencies?

Solution: Identify ready-to-start tasks

Response: "Feature appears stalled, but 4 tasks are actually ready to start
with no dependencies: [list tasks]. Team has work available. Recommend: Assign
these tasks immediately."

---

Issue 7: Dependency Analysis Returns Unexpected Results

Symptoms:

• get_blocked_tasks returns empty list, but user insists tasks are blocked
• get_task_dependencies returns different results on repeated calls
• Dependency counts don't match expectations

Possible Causes:

Cause A: Query Filtering Issues

Problem: Filters excluding relevant tasks

Diagnosis:

// Try broader query
get_blocked_tasks(projectId="project-id") // Instead of featureId
search_tasks(status="pending,in_progress,blocked") // Include all statuses

Solution: Adjust query scope

Response: "Query was limited to featureId=X, but blocking dependencies are in
different feature. Recommend: Use projectId filter instead for cross-feature
dependency analysis."

Cause B: Task Status Ambiguity

Problem: Tasks marked with non-standard status values

Diagnosis:

search_tasks(featureId="feature-id")
// Check: Are there tasks with status="on_hold", "waiting", etc?

Solution: Clarify status meanings

Response: "Some tasks have status='on_hold' which isn't included in blocked
task queries. Recommend: Use status='pending' for tasks with dependencies,
status='in_progress' for active work only."

---

Diagnostic Workflows

Workflow 1: Why Is This Task Blocked?

Step-by-Step Diagnosis:

1. Get task details:

   get_task(id="task-id", includeDependencies=true)
   

2. Check dependency statuses:

   for each dependency:
     get_task(id=dep.id)
     // Is status="completed"? If not, that's the blocker
   

3. Trace transitive dependencies:

   get_task_dependencies(taskId="dependency-id", includeTransitive=true)
   // Find root cause (deepest incomplete dependency)
   

4. Report findings:

   "Task X is blocked by Task Y (in-progress).
   Task Y is blocked by Task Z (pending).
   Root cause: Task Z has no dependencies but hasn't been started.
   Recommendation: Start Task Z to unblock chain."
   

Workflow 2: Why Isn't Feature Making Progress?

Step-by-Step Diagnosis:

1. Get feature overview:

   get_feature(id="feature-id", includeTasks=true, includeTaskCounts=true)
   

2. Analyze task distribution:

   Total: X tasks
   Completed: Y tasks
   In-progress: Z tasks
   Pending: W tasks
   

3. Find blocked tasks:

   get_blocked_tasks(featureId="feature-id")
   

4. Identify bottlenecks:

   // For each in-progress or pending task
   // Count how many tasks depend on it
   

5. Report findings:

   "Feature has X tasks:
   - Y completed (good progress)
   - Z in-progress (currently active)
   - W pending, of which:
     - N blocked by dependencies
     - M ready to start (no dependencies)
   
   Bottleneck: Task 'Q' is blocking N tasks.
   Recommendation: Prioritize completing Task Q."
   

Workflow 3: Is This a Valid Dependency?

Questions to Ask:

1. Strict dependency?

   • Must TaskB ABSOLUTELY wait for TaskA to complete?
   • Or can TaskB start with partial results from TaskA?

2. Could work in parallel?

   • Can TaskB use mocks/stubs while TaskA completes?
   • Can TaskB work on independent parts?

3. Is dependency transitive?

   • Does TaskC need to depend on both TaskA and TaskB?
   • Or is TaskC→TaskB enough (TaskB already depends on TaskA)?

4. Is dependency bidirectional? (Red flag)

   • Does TaskA depend on TaskB AND TaskB depend on TaskA?
   • This is always incorrect (circular dependency)

Valid Dependency Examples:

• ✅ "Implement API" → "Write API docs" (docs need API to exist)
• ✅ "Design database" → "Implement API" (API needs schema)
• ✅ "Create UI mockups" → "Implement UI" (implementation needs design)

Invalid Dependency Examples:

• ❌ "Write tests" → "Deploy to production" (tests should run before deploy)
• ❌ "Backend API" → "Frontend UI" → "Backend API" (circular)
• ❌ "Add logging" → "Implement feature" (logging is orthogonal)

---

Error Messages and Solutions

Error: "Circular dependency detected"

What it means: Tasks depend on each other in a loop

How to fix:

1. Run dependency analysis to find the cycle
2. Identify the weakest link in the cycle
3. Remove that dependency
4. Restructure work to be linear

Example Fix:

Before: A→B→C→A (circular)
After:  C→A→B (linear)

Error: "Task has no dependencies but shows as blocked"

What it means: Data inconsistency or external blocker

How to fix:

1. Refresh task data
2. Check for comments mentioning blockers
3. Ask user if there are external dependencies
4. If truly ready, mark as "in-progress"

Error: "Dependency chain exceeds maximum depth"

What it means: More than 10 levels of dependencies (overly complex)

How to fix:

1. Review chain for unnecessary dependencies
2. Remove transitive dependencies that are explicitly stated
3. Consider breaking into multiple features
4. Parallelize work where possible

---

Prevention Best Practices

1. Keep Dependency Chains Short

Goal: Maximum 3-4 levels of dependencies

How:

• Only add strict dependencies (must complete first)
• Don't add "nice to have" dependencies
• Let transitive dependencies be implicit

2. Review Dependencies During Planning

When: During task breakdown (Planning Specialist work)

Check:

• Does every dependency make sense?
• Could tasks run in parallel with mocks/stubs?
• Are we over-specifying dependencies?

3. Update Priorities Based on Blocking

Rule: If task blocks 3+ other tasks, consider increasing priority

Automation idea: Hook that warns when low-priority task becomes bottleneck

4. Use Tags to Indicate Dependency Type

Suggested tags:

• hard-dependency - Must complete first
• soft-dependency - Would be nice to complete first
• data-dependency - Needs data from other task
• approval-dependency - Waiting for external approval

This helps during analysis to understand which dependencies are flexible.

---

When to Escalate

Escalate to user/team when:

1. Circular dependencies found

   • Can't be resolved automatically
   • Requires team decision on work restructuring

2. Bottleneck blocking >50% of feature

   • May need resource reallocation
   • May need to break up bottleneck task

3. External dependencies blocking work

   • Need user to follow up with external parties
   • May need to create workarounds

4. Dependency chain >5 levels deep

   • Suggests poor planning
   • May need feature re-architecture

5. Tasks blocked for >1 week

   • Dependencies not being resolved
   • May need priority adjustment or intervention

Don't escalate when:

• Normal sequential work (A→B→C is fine)
• Bottleneck is actively being worked on
• Dependencies are clear and expected
• Timeline is on track

---

Advanced Debugging

Tool: Manual Dependency Trace

When automated analysis isn't working, manually trace dependencies:

// Start with problem task
task = get_task(id="problem-task")

// Get direct dependencies
deps = get_task_dependencies(taskId="problem-task")

// For each dependency
for each dep in deps:
  status = get_task(id=dep.id).status
  if status != "completed":
    // This is a blocker, recurse
    subdeps = get_task_dependencies(taskId=dep.id)
    // Continue tracing...

Build a tree structure manually and identify root causes.

Tool: Dependency Impact Matrix

Create a matrix showing which tasks block which:

         | T1 | T2 | T3 | T4 | T5
---------|----|----|----|----|----
Blocks→  |    |    |    |    |
---------|----|----|----|----|----
T1       |    | X  | X  |    |
T2       |    |    |    | X  |
T3       |    |    |    | X  | X
T4       |    |    |    |    | X
T5       |    |    |    |    |

Interpretation:
- T1 blocks 2 tasks (T2, T3) → Medium bottleneck
- T3 blocks 2 tasks (T4, T5) → Medium bottleneck
- T4 blocks 1 task (T5) → Minor bottleneck
- T2, T5 block nothing → No bottleneck

This helps visualize the dependency graph when troubleshooting.

---

Getting Help

If you've tried these troubleshooting steps and still have issues:

1. Document the problem:

   • Which task(s) are affected?
   • What analysis did you run?
   • What were you expecting vs what happened?

2. Check for edge cases:

   • Cross-feature dependencies?
   • External dependencies?
   • Tasks with unusual statuses?

3. Review with team:

   • Is the dependency structure actually correct?
   • Are there unspoken dependencies?
   • Should work be restructured?

4. Report bugs (if data inconsistency):

   • Provide task IDs
   • Provide exact tool calls that showed inconsistent data
   • Describe expected behavior

Remember: Dependency analysis is about understanding relationships, not just running tools. Use your judgment to interpret results and make recommendations that help teams deliver faster.