Initial commit
This commit is contained in:
Zhongwei Li
417
skills/dependency-analysis/SKILL.md
Normal file
417
skills/dependency-analysis/SKILL.md
Normal file
@@ -0,0 +1,417 @@
|
||||
---
|
||||
name: Dependency Analysis
|
||||
description: Analyze task dependencies including finding blocked tasks, checking dependency chains, and identifying bottlenecks. Use when investigating why tasks are blocked or planning parallel work.
|
||||
allowed-tools: mcp__task-orchestrator__query_container, mcp__task-orchestrator__query_dependencies
|
||||
---
|
||||
|
||||
# Dependency Analysis Skill
|
||||
|
||||
## Purpose
|
||||
|
||||
This Skill helps you analyze task dependencies within Task Orchestrator to:
|
||||
- Find all blocked tasks in a feature
|
||||
- Analyze dependency chains to understand task relationships
|
||||
- Identify bottleneck tasks that are blocking multiple others
|
||||
- Recommend which dependencies to resolve first for maximum parallel work
|
||||
|
||||
## When to Use This Skill
|
||||
|
||||
**Use Dependency Analysis when:**
|
||||
- ✅ User asks "what's blocking progress?" or "why can't we start this task?"
|
||||
- ✅ Planning parallel work across team members
|
||||
- ✅ Feature appears stalled with no tasks in progress
|
||||
- ✅ Need to prioritize which tasks to complete first
|
||||
- ✅ Investigating circular dependencies
|
||||
- ✅ Optimizing task execution order
|
||||
|
||||
**Don't use this Skill when:**
|
||||
- ❌ Creating new dependencies (use `manage_dependency` directly)
|
||||
- ❌ Removing dependencies (use `manage_dependency` directly)
|
||||
- ❌ Just checking a single task's dependencies (use `query_dependencies` directly)
|
||||
|
||||
## Core Workflows
|
||||
|
||||
### Workflow 1: Find All Blocked Tasks
|
||||
|
||||
**When to use**: User wants to know what tasks can't be started yet
|
||||
|
||||
**Steps**:
|
||||
1. Get feature ID (from context or ask user)
|
||||
2. Search for all tasks in feature: `query_container(operation="search", containerType="task", featureId=<id>)`
|
||||
3. For each task, check dependencies: `query_dependencies(taskId=<id>, direction="incoming")`
|
||||
4. Filter tasks that have incomplete blocking dependencies
|
||||
5. Present summary: "X tasks are blocked, waiting on Y dependencies"
|
||||
|
||||
**Example**:
|
||||
```
|
||||
User: "What's blocking progress on the authentication feature?"
|
||||
|
||||
You (using this Skill):
|
||||
1. query_container(operation="search", containerType="task", featureId="auth-feature-id", status="pending,in-progress")
|
||||
2. For each task: query_dependencies(taskId="...", direction="incoming", includeTaskInfo=true)
|
||||
3. Found 3 blocked tasks:
|
||||
- "Implement login UI" (blocked by "Create auth API" - status: in-progress)
|
||||
- "Add logout flow" (blocked by "Create auth API" - status: in-progress)
|
||||
- "Add password reset" (blocked by "Create auth API", "Implement login UI")
|
||||
4. Response: "3 tasks are blocked. Priority: Complete 'Create auth API' first (unblocks 3 tasks)"
|
||||
```
|
||||
|
||||
### Workflow 2: Analyze Dependency Chains
|
||||
|
||||
**When to use**: Need to understand full sequence of task dependencies
|
||||
|
||||
**Steps**:
|
||||
1. Start with target task ID
|
||||
2. Call `query_dependencies(taskId=<id>, direction="incoming")`
|
||||
3. Build dependency tree:
|
||||
- Direct dependencies (must complete immediately before)
|
||||
- Full dependency chain from returned data
|
||||
4. Identify longest chain (critical path)
|
||||
5. Present visual representation
|
||||
|
||||
**Example**:
|
||||
```
|
||||
User: "What needs to happen before we can deploy the feature?"
|
||||
|
||||
You (using this Skill):
|
||||
1. query_dependencies(taskId="deploy-task-id", direction="incoming", includeTaskInfo=true)
|
||||
2. Chain discovered:
|
||||
- Deploy Feature (target)
|
||||
← Integration Tests
|
||||
← Frontend Implementation
|
||||
← API Implementation
|
||||
← Database Schema
|
||||
3. Response: "Critical path is 5 tasks deep. Start with 'Database Schema' (no dependencies)"
|
||||
```
|
||||
|
||||
### Workflow 3: Identify Bottleneck Tasks
|
||||
|
||||
**When to use**: Want to know which tasks are blocking the most work
|
||||
|
||||
**Steps**:
|
||||
1. Get all tasks in feature with `query_container(operation="search", containerType="task", featureId=<id>)`
|
||||
2. For each pending/in-progress task:
|
||||
- Count how many tasks depend on it (outgoing dependencies)
|
||||
3. Sort by dependent count (descending)
|
||||
4. Highlight top bottlenecks with dependent task counts
|
||||
|
||||
**Example**:
|
||||
```
|
||||
User: "Which tasks should we prioritize to unblock the most work?"
|
||||
|
||||
You (using this Skill):
|
||||
1. query_container(operation="search", containerType="task", featureId="feature-id", status="pending,in_progress")
|
||||
2. Analyze outgoing dependencies:
|
||||
- "Create auth API" → 5 tasks depend on this (BOTTLENECK)
|
||||
- "Setup database" → 3 tasks depend on this
|
||||
- "Design user flow" → 2 tasks depend on this
|
||||
- "Write documentation" → 0 tasks depend on this
|
||||
3. Response: "Priority 1: 'Create auth API' (unblocks 5 tasks). Priority 2: 'Setup database' (unblocks 3 tasks)"
|
||||
```
|
||||
|
||||
### Workflow 4: Recommend Resolution Order
|
||||
|
||||
**When to use**: Multiple blocked tasks, need to decide what to work on
|
||||
|
||||
**Steps**:
|
||||
1. Search for all tasks: `query_container(operation="search", containerType="task", featureId=<id>)`
|
||||
2. For each task, get dependencies: `query_dependencies(taskId=<id>, direction="all", includeTaskInfo=true)`
|
||||
3. Identify tasks that are blocking others (outgoing dependencies with incomplete status)
|
||||
4. For each blocking task:
|
||||
- Count how many tasks it unblocks
|
||||
- Get task priority and complexity from search results
|
||||
5. Calculate resolution score:
|
||||
- Higher score = unblocks more tasks + higher priority + lower complexity
|
||||
6. Recommend top 3 tasks to complete first
|
||||
|
||||
**Scoring formula**:
|
||||
```
|
||||
Score = (tasks_unblocked × 10) + (priority_weight × 5) - (complexity_weight × 2)
|
||||
|
||||
Priority weights: critical=5, high=4, medium=3, low=2, trivial=1
|
||||
Complexity: use inverse (10 - complexity_rating)
|
||||
```
|
||||
|
||||
**Example**:
|
||||
```
|
||||
User: "We have 10 blocked tasks. What should we work on first?"
|
||||
|
||||
You (using this Skill):
|
||||
1. query_container(operation="search", containerType="task", featureId="feature-id", status="pending,in-progress")
|
||||
2. For each task: query_dependencies(taskId="...", direction="outgoing", includeTaskInfo=true)
|
||||
3. Analyze blocking dependencies:
|
||||
- "Create auth API": unblocks 5 tasks, priority=high, complexity=6
|
||||
Score = (5×10) + (4×5) - (6×2) = 50 + 20 - 12 = 58
|
||||
- "Setup database": unblocks 3 tasks, priority=critical, complexity=8
|
||||
Score = (3×10) + (5×5) - (8×2) = 30 + 25 - 16 = 39
|
||||
4. Response: "Work on 'Create auth API' first (score: 58, unblocks 5 tasks)"
|
||||
```
|
||||
|
||||
## Advanced Patterns
|
||||
|
||||
### Pattern: Detect Circular Dependencies
|
||||
|
||||
**Problem**: Tasks depend on each other, creating a deadlock
|
||||
|
||||
**Detection**:
|
||||
1. Get task dependencies recursively
|
||||
2. Track visited tasks
|
||||
3. If you encounter a task already in the chain → circular dependency found
|
||||
|
||||
**Response**:
|
||||
```
|
||||
"⚠️ Circular dependency detected:
|
||||
Task A depends on Task B, which depends on Task C, which depends on Task A.
|
||||
Action required: Remove one dependency to break the cycle."
|
||||
```
|
||||
|
||||
### Pattern: Find Parallelizable Work
|
||||
|
||||
**Goal**: Identify tasks that can be worked on simultaneously
|
||||
|
||||
**Steps**:
|
||||
1. Get all pending tasks
|
||||
2. Filter to tasks with no incomplete dependencies
|
||||
3. Group by specialist type (backend, frontend, etc.)
|
||||
4. Recommend parallel assignments
|
||||
|
||||
**Example output**:
|
||||
```
|
||||
"Ready to start in parallel:
|
||||
- Implementation Specialist (Haiku): 'Implement user service' (backend-implementation Skill)
|
||||
- Implementation Specialist (Haiku): 'Create login form' (frontend-implementation Skill)
|
||||
- Implementation Specialist (Haiku): 'Add user indexes' (database-implementation Skill)
|
||||
All 3 tasks have no dependencies and can proceed simultaneously."
|
||||
```
|
||||
|
||||
### Pattern: Critical Path Analysis
|
||||
|
||||
**Goal**: Find the longest sequence of dependent tasks
|
||||
|
||||
**Steps**:
|
||||
1. Build complete dependency graph
|
||||
2. Calculate longest path from start to each task
|
||||
3. Identify tasks on critical path (longest sequence)
|
||||
4. Recommend focusing on critical path to minimize total time
|
||||
|
||||
## Tool Usage Guidelines
|
||||
|
||||
### Finding Blocked Tasks
|
||||
|
||||
**Approach**: Search for tasks, then check each for blocking dependencies
|
||||
|
||||
**Steps**:
|
||||
1. Search for tasks: `query_container(operation="search", containerType="task", featureId=<id>, status="pending,in-progress")`
|
||||
2. For each task: `query_dependencies(taskId=<id>, direction="incoming", includeTaskInfo=true)`
|
||||
3. Filter tasks where any incoming dependency has status != "completed" and status != "cancelled"
|
||||
|
||||
**Usage**:
|
||||
```javascript
|
||||
// Step 1: Get all active tasks
|
||||
query_container(operation="search", containerType="task", featureId="550e8400-e29b-41d4-a716-446655440000", status="pending,in-progress")
|
||||
|
||||
// Step 2: Check each task for blockers
|
||||
query_dependencies(taskId="task-id", direction="incoming", includeTaskInfo=true)
|
||||
|
||||
// Step 3: Identify blocked tasks from dependency status
|
||||
```
|
||||
|
||||
### query_dependencies
|
||||
|
||||
**Purpose**: Get dependencies for a specific task
|
||||
|
||||
**Parameters**:
|
||||
- `taskId` (required): Task to analyze
|
||||
- `direction` (optional): "incoming", "outgoing", or "all" (default: all)
|
||||
- `type` (optional): "BLOCKS", "IS_BLOCKED_BY", "RELATES_TO", or "all"
|
||||
- `includeTaskInfo` (optional): Include task titles and status
|
||||
|
||||
**Returns**: Dependencies with direction filtering and counts
|
||||
|
||||
**Usage**:
|
||||
```javascript
|
||||
// All dependencies
|
||||
query_dependencies(taskId="task-id")
|
||||
|
||||
// Just incoming dependencies (what blocks this task)
|
||||
query_dependencies(taskId="task-id", direction="incoming", includeTaskInfo=true)
|
||||
```
|
||||
|
||||
### query_container (get task)
|
||||
|
||||
**Purpose**: Get full task details including summary and priority
|
||||
|
||||
**Parameters**:
|
||||
- `operation`: "get" (required)
|
||||
- `containerType`: "task" (required)
|
||||
- `id` (required): Task UUID
|
||||
- `includeSections` (optional): Include detailed content sections
|
||||
|
||||
**Usage**:
|
||||
```javascript
|
||||
query_container(
|
||||
operation="get",
|
||||
containerType="task",
|
||||
id="task-id",
|
||||
includeSections=false
|
||||
)
|
||||
```
|
||||
|
||||
### query_container (search tasks)
|
||||
|
||||
**Purpose**: Find tasks by criteria
|
||||
|
||||
**Parameters**:
|
||||
- `operation`: "search" (required)
|
||||
- `containerType`: "task" (required)
|
||||
- `featureId` (optional): Filter by feature
|
||||
- `status` (optional): Filter by status
|
||||
- `tags` (optional): Filter by tags
|
||||
|
||||
**Usage**:
|
||||
```javascript
|
||||
// Find all pending tasks in feature
|
||||
query_container(operation="search", containerType="task", featureId="feature-id", status="pending")
|
||||
|
||||
// Find all in-progress tasks
|
||||
query_container(operation="search", containerType="task", status="in_progress")
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Start Broad, Then Narrow
|
||||
|
||||
Always begin with feature-level analysis:
|
||||
```
|
||||
Step 1: query_container(operation="search", containerType="task", featureId=X) → Get all tasks
|
||||
Step 2: query_dependencies(taskId=Y, ...) for each task → Identify blocked tasks
|
||||
Step 3: Analyze patterns and prioritize resolution
|
||||
```
|
||||
|
||||
### 2. Consider Task Metadata
|
||||
|
||||
When recommending priorities, factor in:
|
||||
- **Priority**: Critical tasks should be resolved first
|
||||
- **Complexity**: Lower complexity = faster to complete
|
||||
- **Blocking count**: More tasks unblocked = higher impact
|
||||
- **Specialist availability**: Can the right person work on it?
|
||||
|
||||
### 3. Visualize Chains
|
||||
|
||||
Present dependency chains visually:
|
||||
```
|
||||
Task E (Deploy)
|
||||
← Task D (Integration Tests)
|
||||
← Task C (Frontend)
|
||||
← Task B (API)
|
||||
← Task A (Database Schema)
|
||||
|
||||
Critical path: 5 tasks, start with Task A
|
||||
```
|
||||
|
||||
### 4. Provide Actionable Recommendations
|
||||
|
||||
Don't just report problems, suggest solutions:
|
||||
- ❌ "Task X is blocked by Task Y"
|
||||
- ✅ "Complete Task Y first to unblock 3 tasks including Task X"
|
||||
|
||||
### 5. Watch for Anti-Patterns
|
||||
|
||||
**Warn users about**:
|
||||
- Circular dependencies (deadlock situation)
|
||||
- Long dependency chains (>5 tasks deep = brittle)
|
||||
- Single bottleneck tasks (risk if that person is unavailable)
|
||||
- Tasks with many dependencies (complexity, coordination overhead)
|
||||
|
||||
## Common Mistakes to Avoid
|
||||
|
||||
### Mistake 1: Not Checking Complete Dependency Chains
|
||||
|
||||
**Problem**: Missing hidden dependencies in the chain
|
||||
|
||||
**Solution**: Recursively query dependencies using `direction="incoming"` to build complete dependency tree
|
||||
|
||||
### Mistake 2: Ignoring Task Status
|
||||
|
||||
**Problem**: Counting completed tasks as blockers
|
||||
|
||||
**Solution**: Filter to `status=pending,in_progress` when analyzing blockers
|
||||
|
||||
### Mistake 3: Overwhelming Users
|
||||
|
||||
**Problem**: Dumping full dependency graph without interpretation
|
||||
|
||||
**Solution**: Summarize findings, prioritize recommendations
|
||||
|
||||
### Mistake 4: Not Updating Analysis
|
||||
|
||||
**Problem**: Dependencies change, old analysis becomes stale
|
||||
|
||||
**Solution**: Re-run analysis when tasks complete or dependencies change
|
||||
|
||||
## Response Templates
|
||||
|
||||
### Blocked Tasks Summary
|
||||
```
|
||||
Found [N] blocked tasks in feature "[Feature Name]":
|
||||
|
||||
Priority 1: Complete "[Task Title]" → Unblocks [X] tasks
|
||||
Priority 2: Complete "[Task Title]" → Unblocks [Y] tasks
|
||||
Priority 3: Complete "[Task Title]" → Unblocks [Z] tasks
|
||||
|
||||
[N-3] other tasks blocked with lower impact.
|
||||
|
||||
Recommendation: Focus on Priority 1 for maximum parallel work.
|
||||
```
|
||||
|
||||
### Bottleneck Identification
|
||||
```
|
||||
Dependency Analysis for "[Feature Name]":
|
||||
|
||||
Bottleneck Tasks (blocking multiple others):
|
||||
1. "[Task Title]" (complexity: [X]/10) → Blocking [N] tasks
|
||||
Status: [status] | Priority: [priority]
|
||||
|
||||
2. "[Task Title]" (complexity: [Y]/10) → Blocking [M] tasks
|
||||
Status: [status] | Priority: [priority]
|
||||
|
||||
Recommendation: Complete task #1 first to unblock maximum work.
|
||||
```
|
||||
|
||||
### Critical Path Report
|
||||
```
|
||||
Critical Path Analysis for "[Feature Name]":
|
||||
|
||||
Longest dependency chain: [N] tasks deep
|
||||
Path: [Task A] → [Task B] → [Task C] → [Task D] → [Task E]
|
||||
|
||||
Estimated sequence:
|
||||
1. [Task A] (complexity: [X]/10, priority: [priority])
|
||||
2. [Task B] (complexity: [Y]/10, priority: [priority])
|
||||
... [etc]
|
||||
|
||||
Ready to start now: [Task A] (no dependencies)
|
||||
```
|
||||
|
||||
## Integration with Other Skills
|
||||
|
||||
### Works Well With
|
||||
|
||||
**Feature Management Skill**:
|
||||
- Use dependency analysis to recommend next task intelligently
|
||||
- Check for blockers before recommending new work
|
||||
|
||||
**Task Management Skill**:
|
||||
- Validate dependencies before marking task complete
|
||||
- Route blocked tasks appropriately
|
||||
|
||||
**Planning Specialist** (Subagent):
|
||||
- Provide dependency analysis to inform task breakdown
|
||||
- Identify dependencies during feature planning
|
||||
|
||||
## See Also
|
||||
|
||||
- **examples.md**: Concrete usage scenarios with sample data
|
||||
- **troubleshooting.md**: Common dependency issues and solutions
|
||||
- **Feature Management Skill**: Task recommendation workflow
|
||||
- **Task Management Skill**: Task completion workflow
|
||||
684
skills/dependency-analysis/examples.md
Normal file
684
skills/dependency-analysis/examples.md
Normal file
@@ -0,0 +1,684 @@
|
||||
# Dependency Analysis Skill - Usage Examples
|
||||
|
||||
## Example 1: Feature Appears Stalled
|
||||
|
||||
### Scenario
|
||||
Developer notices that a feature with 8 tasks has been "in development" for 2 weeks, but only 2 tasks are complete. They want to understand what's blocking progress.
|
||||
|
||||
### User Query
|
||||
> "The authentication feature seems stuck. What's blocking us?"
|
||||
|
||||
### Skill Execution
|
||||
|
||||
**Step 1**: Get feature ID from context or search
|
||||
```javascript
|
||||
search_features(name="authentication")
|
||||
// Returns: featureId = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
|
||||
```
|
||||
|
||||
**Step 2**: Find blocked tasks
|
||||
```javascript
|
||||
get_blocked_tasks(featureId="a1b2c3d4-e5f6-7890-abcd-ef1234567890")
|
||||
```
|
||||
|
||||
**Response Data**:
|
||||
```json
|
||||
{
|
||||
"blockedTasks": [
|
||||
{
|
||||
"id": "task-1",
|
||||
"title": "Implement login UI",
|
||||
"blockedBy": ["task-api"]
|
||||
},
|
||||
{
|
||||
"id": "task-2",
|
||||
"title": "Add logout functionality",
|
||||
"blockedBy": ["task-api"]
|
||||
},
|
||||
{
|
||||
"id": "task-3",
|
||||
"title": "Implement password reset",
|
||||
"blockedBy": ["task-api", "task-1"]
|
||||
},
|
||||
{
|
||||
"id": "task-4",
|
||||
"title": "Add session management",
|
||||
"blockedBy": ["task-api"]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Step 3**: Analyze blocking dependencies
|
||||
```javascript
|
||||
get_task(id="task-api", includeSections=false)
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```json
|
||||
{
|
||||
"id": "task-api",
|
||||
"title": "Create authentication API endpoints",
|
||||
"status": "in_progress",
|
||||
"priority": "high",
|
||||
"complexity": 7,
|
||||
"assignedTo": "Backend Engineer"
|
||||
}
|
||||
```
|
||||
|
||||
### Skill Response
|
||||
```
|
||||
Found 4 blocked tasks (50% of remaining work) in "Authentication Feature":
|
||||
|
||||
Root Cause: "Create authentication API endpoints" (in-progress) is blocking 4 tasks:
|
||||
- Implement login UI
|
||||
- Add logout functionality
|
||||
- Implement password reset
|
||||
- Add session management
|
||||
|
||||
Current Status: API task is in-progress (complexity: 7/10)
|
||||
|
||||
Recommendation:
|
||||
1. Prioritize completing the API task (unblocks 4 tasks)
|
||||
2. Once API is done, "Implement login UI" should be next (it blocks password reset)
|
||||
3. After that, 3 tasks can proceed in parallel
|
||||
|
||||
Estimated Impact: Completing API task will unblock 50% of remaining feature work.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example 2: Planning Parallel Work Across Team
|
||||
|
||||
### Scenario
|
||||
Team has 5 developers available. Project manager wants to maximize parallel work by identifying tasks with no dependencies.
|
||||
|
||||
### User Query
|
||||
> "We have 5 developers ready to work. What tasks can they start in parallel?"
|
||||
|
||||
### Skill Execution
|
||||
|
||||
**Step 1**: Get all pending tasks with no dependencies
|
||||
```javascript
|
||||
search_tasks(projectId="project-id", status="pending")
|
||||
// Filter to tasks where dependsOn is empty
|
||||
```
|
||||
|
||||
**Step 2**: For each task, verify no incomplete dependencies
|
||||
```javascript
|
||||
get_task_dependencies(taskId="task-x")
|
||||
// Repeat for all pending tasks
|
||||
```
|
||||
|
||||
**Step 3**: Group by specialist type (from tags)
|
||||
|
||||
### Response Data
|
||||
```
|
||||
Tasks Ready to Start (No Dependencies):
|
||||
|
||||
Backend Engineer:
|
||||
- "Implement user service API" (complexity: 6, priority: high)
|
||||
- "Add logging infrastructure" (complexity: 4, priority: medium)
|
||||
|
||||
Frontend Engineer:
|
||||
- "Create dashboard layout" (complexity: 5, priority: high)
|
||||
- "Design error page components" (complexity: 3, priority: low)
|
||||
|
||||
Database Engineer:
|
||||
- "Add database indexes" (complexity: 5, priority: medium)
|
||||
|
||||
Test Engineer:
|
||||
- "Setup integration test framework" (complexity: 6, priority: high)
|
||||
|
||||
Documentation:
|
||||
- "Write API documentation template" (complexity: 2, priority: medium)
|
||||
```
|
||||
|
||||
### Skill Response
|
||||
```
|
||||
7 tasks are ready to start with no dependencies:
|
||||
|
||||
Parallel Work Assignment (5 developers):
|
||||
|
||||
Priority 1 (High Priority, Start Immediately):
|
||||
- Backend: "Implement user service API" (complexity: 6/10)
|
||||
- Frontend: "Create dashboard layout" (complexity: 5/10)
|
||||
- Database: "Add database indexes" (complexity: 5/10)
|
||||
- Test: "Setup integration test framework" (complexity: 6/10)
|
||||
|
||||
Priority 2 (After completing Priority 1):
|
||||
- Backend: "Add logging infrastructure" (complexity: 4/10)
|
||||
- Docs: "Write API documentation template" (complexity: 2/10)
|
||||
|
||||
Priority 3 (Lower Priority):
|
||||
- Frontend: "Design error page components" (complexity: 3/10)
|
||||
|
||||
Recommendation: Start 4 developers on Priority 1 tasks, assign 5th developer to Priority 2 task. All can proceed in parallel without coordination.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example 3: Investigating Circular Dependencies
|
||||
|
||||
### Scenario
|
||||
Developer tries to mark a task complete but gets an error about circular dependencies. They need to understand and fix the issue.
|
||||
|
||||
### User Query
|
||||
> "I'm getting a circular dependency error with task T5. What's wrong?"
|
||||
|
||||
### Skill Execution
|
||||
|
||||
**Step 1**: Get dependency chain for task
|
||||
```javascript
|
||||
get_task_dependencies(taskId="T5", includeTransitive=true)
|
||||
```
|
||||
|
||||
**Response**:
|
||||
```json
|
||||
{
|
||||
"dependencies": [
|
||||
{"taskId": "T4", "title": "Design user flow"},
|
||||
{"taskId": "T3", "title": "Create wireframes", "transitive": true},
|
||||
{"taskId": "T5", "title": "Implement UI", "transitive": true}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Step 2**: Trace the cycle
|
||||
```
|
||||
T5 (Implement UI)
|
||||
→ depends on T4 (Design user flow)
|
||||
→ depends on T3 (Create wireframes)
|
||||
→ depends on T5 (Implement UI) ← CYCLE DETECTED
|
||||
```
|
||||
|
||||
### Skill Response
|
||||
```
|
||||
⚠️ Circular Dependency Detected:
|
||||
|
||||
Dependency Cycle:
|
||||
T5 "Implement UI"
|
||||
→ T4 "Design user flow"
|
||||
→ T3 "Create wireframes"
|
||||
→ T5 "Implement UI" (cycle back to start)
|
||||
|
||||
Problem: These tasks depend on each other in a loop, creating a deadlock where none can be started.
|
||||
|
||||
Root Cause Analysis:
|
||||
- T5 depends on T4: UI implementation needs finalized design
|
||||
- T4 depends on T3: Design needs wireframes
|
||||
- T3 depends on T5: Wireframes need to see existing UI (INCORRECT)
|
||||
|
||||
Solution: Remove the T3→T5 dependency. Wireframes should inform UI implementation, not depend on it.
|
||||
|
||||
Recommended Fix:
|
||||
1. Remove dependency: T3 → T5
|
||||
2. Correct sequence: T3 (wireframes) → T4 (design) → T5 (implement)
|
||||
|
||||
This creates a linear dependency chain with no cycles.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example 4: Finding Critical Path for Release
|
||||
|
||||
### Scenario
|
||||
Product manager needs to know the minimum time to complete a feature, assuming unlimited resources. Need to find the longest dependency chain (critical path).
|
||||
|
||||
### User Query
|
||||
> "What's the fastest we can ship the payment integration feature?"
|
||||
|
||||
### Skill Execution
|
||||
|
||||
**Step 1**: Get all tasks in feature
|
||||
```javascript
|
||||
search_tasks(featureId="payment-feature-id")
|
||||
```
|
||||
|
||||
**Step 2**: Build complete dependency graph
|
||||
```javascript
|
||||
// For each task, get dependencies
|
||||
get_task_dependencies(taskId="task-x", includeTransitive=true)
|
||||
```
|
||||
|
||||
**Step 3**: Calculate critical path (longest chain)
|
||||
|
||||
### Dependency Graph
|
||||
```
|
||||
Tasks and Dependencies:
|
||||
|
||||
T1: Setup Stripe account (no dependencies) - 1 day
|
||||
T2: Implement payment API (depends on T1) - 3 days
|
||||
T3: Create payment UI (depends on T2) - 2 days
|
||||
T4: Add error handling (depends on T2) - 1 day
|
||||
T5: Write integration tests (depends on T3, T4) - 2 days
|
||||
T6: Deploy to staging (depends on T5) - 1 day
|
||||
|
||||
Parallel paths:
|
||||
Path A: T1 → T2 → T3 → T5 → T6 = 9 days
|
||||
Path B: T1 → T2 → T4 → T5 → T6 = 8 days
|
||||
```
|
||||
|
||||
### Skill Response
|
||||
```
|
||||
Critical Path Analysis for "Payment Integration Feature":
|
||||
|
||||
Longest dependency chain: 5 tasks, 9 days total
|
||||
Critical Path: T1 → T2 → T3 → T5 → T6
|
||||
|
||||
Task Sequence (must complete in order):
|
||||
1. T1: Setup Stripe account (1 day, complexity: 3/10)
|
||||
2. T2: Implement payment API (3 days, complexity: 7/10) ← BOTTLENECK
|
||||
3. T3: Create payment UI (2 days, complexity: 5/10)
|
||||
4. T5: Write integration tests (2 days, complexity: 6/10)
|
||||
5. T6: Deploy to staging (1 day, complexity: 4/10)
|
||||
|
||||
Parallel Opportunity:
|
||||
- T4 "Add error handling" (1 day) can run in parallel with T3
|
||||
- Assign to different developer to save 1 day
|
||||
|
||||
Optimized Timeline:
|
||||
- Sequential: 9 days (one developer)
|
||||
- With parallel work: 8 days (two developers)
|
||||
|
||||
Recommendation: Prioritize T2 (API) as it's the most complex and blocks all downstream work.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example 5: Prioritizing Bug Fixes with Dependencies
|
||||
|
||||
### Scenario
|
||||
Multiple bugs reported, some bugs are blocking work on new features. Need to prioritize which bugs to fix first.
|
||||
|
||||
### User Query
|
||||
> "We have 8 bugs and 12 feature tasks. Which bugs should we fix first?"
|
||||
|
||||
### Skill Execution
|
||||
|
||||
**Step 1**: Get all blocked feature tasks
|
||||
```javascript
|
||||
get_blocked_tasks(projectId="project-id")
|
||||
```
|
||||
|
||||
**Step 2**: Identify bug tasks blocking features
|
||||
```javascript
|
||||
// Filter blockedBy tasks where tags include "bug"
|
||||
search_tasks(tags="bug", status="pending,in_progress")
|
||||
```
|
||||
|
||||
**Step 3**: Count how many tasks each bug is blocking
|
||||
|
||||
### Analysis Result
|
||||
```
|
||||
Bug Impact Analysis:
|
||||
|
||||
High Impact Bugs (blocking multiple tasks):
|
||||
- Bug #42 "API returns 500 on invalid input" → Blocking 5 feature tasks
|
||||
Status: pending, Complexity: 4/10, Priority: critical
|
||||
|
||||
- Bug #38 "Database migration fails on fresh install" → Blocking 3 feature tasks
|
||||
Status: in_progress, Complexity: 6/10, Priority: high
|
||||
|
||||
Medium Impact Bugs (blocking 1-2 tasks):
|
||||
- Bug #51 "Login session expires too quickly" → Blocking 2 tasks
|
||||
Status: pending, Complexity: 3/10, Priority: medium
|
||||
|
||||
Low Impact Bugs (not blocking features):
|
||||
- Bug #22, #33, #45, #49, #50 → Not blocking any tasks
|
||||
Priority: low to medium
|
||||
```
|
||||
|
||||
### Skill Response
|
||||
```
|
||||
Bug Fix Priority for Maximum Feature Unblocking:
|
||||
|
||||
URGENT (Fix Immediately):
|
||||
1. Bug #42 "API returns 500 on invalid input"
|
||||
- Blocking: 5 feature tasks
|
||||
- Complexity: 4/10 (relatively easy)
|
||||
- Impact Score: 58/100 (high impact, easy fix)
|
||||
- Estimated Time: 2-3 hours
|
||||
- Recommendation: Fix first, unblocks most work
|
||||
|
||||
2. Bug #38 "Database migration fails" (in-progress)
|
||||
- Blocking: 3 feature tasks
|
||||
- Complexity: 6/10
|
||||
- Impact Score: 39/100
|
||||
- Status: Already being worked on
|
||||
|
||||
MEDIUM PRIORITY (Fix Soon):
|
||||
3. Bug #51 "Session expires too quickly"
|
||||
- Blocking: 2 feature tasks
|
||||
- Complexity: 3/10
|
||||
- Impact Score: 32/100
|
||||
|
||||
LOW PRIORITY (Fix After Features):
|
||||
- Bugs #22, #33, #45, #49, #50
|
||||
- Not blocking any work
|
||||
- Schedule after feature tasks complete
|
||||
|
||||
Impact if prioritized correctly:
|
||||
- Fixing Bug #42 → Unblocks 5 tasks (4 hours of feature work available)
|
||||
- Fixing Bug #38 → Unblocks 3 more tasks
|
||||
- Total: 8 tasks unblocked (66% of blocked work)
|
||||
|
||||
Recommendation: Assign 1 developer to Bug #42 immediately (2-3 hours to unblock 5 tasks). Continue Bug #38 work. Defer low-priority bugs.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example 6: Sprint Planning - Maximizing Velocity
|
||||
|
||||
### Scenario
|
||||
Scrum master planning 2-week sprint. Want to maximize completed tasks by intelligently ordering work based on dependencies.
|
||||
|
||||
### User Query
|
||||
> "Help me plan the sprint. We have 2 weeks and 4 developers. What order should we tackle tasks?"
|
||||
|
||||
### Skill Execution
|
||||
|
||||
**Step 1**: Get all tasks ready for sprint
|
||||
```javascript
|
||||
search_tasks(projectId="project-id", status="pending")
|
||||
```
|
||||
|
||||
**Step 2**: Analyze dependencies and bottlenecks
|
||||
```javascript
|
||||
get_blocked_tasks(projectId="project-id")
|
||||
// For each task: get_task_dependencies(taskId="x")
|
||||
```
|
||||
|
||||
**Step 3**: Calculate optimal task ordering
|
||||
|
||||
### Analysis
|
||||
```
|
||||
Available Tasks: 20 pending tasks
|
||||
Sprint Capacity: 4 developers × 10 days = 40 developer-days
|
||||
Average task: 2-3 days
|
||||
|
||||
Dependency Analysis:
|
||||
- 8 tasks have no dependencies (ready to start)
|
||||
- 7 tasks have 1 dependency each
|
||||
- 5 tasks have 2+ dependencies
|
||||
|
||||
Bottleneck Tasks (blocking multiple):
|
||||
- T2 "Setup CI pipeline" → Blocks 4 tasks
|
||||
- T5 "Create database schema" → Blocks 6 tasks
|
||||
```
|
||||
|
||||
### Skill Response
|
||||
```
|
||||
Sprint Plan - 2 Weeks, 4 Developers:
|
||||
|
||||
Week 1 Strategy: Eliminate Bottlenecks
|
||||
|
||||
Monday-Tuesday (Days 1-2):
|
||||
- Dev 1: T5 "Create database schema" (2 days, unblocks 6 tasks)
|
||||
- Dev 2: T2 "Setup CI pipeline" (2 days, unblocks 4 tasks)
|
||||
- Dev 3: T8 "Implement auth service" (3 days, no dependencies)
|
||||
- Dev 4: T12 "Design homepage" (2 days, no dependencies)
|
||||
|
||||
Wednesday-Friday (Days 3-5):
|
||||
After T5 completes, 6 new tasks become available
|
||||
After T2 completes, 4 new tasks become available
|
||||
|
||||
- Dev 1: T15 "Add user CRUD" (depends on T5, now ready)
|
||||
- Dev 2: T20 "Setup automated tests" (depends on T2, now ready)
|
||||
- Dev 3: T8 continues (1 day left)
|
||||
- Dev 4: T13 "Build component library" (2 days)
|
||||
|
||||
Week 2 Strategy: Parallel Execution
|
||||
|
||||
Monday-Friday (Days 6-10):
|
||||
With bottlenecks cleared, 10 tasks now have no dependencies:
|
||||
- All 4 developers can work in parallel
|
||||
- No coordination overhead
|
||||
- Maximum velocity
|
||||
|
||||
Projected Sprint Completion:
|
||||
- Week 1: 6 tasks complete (focusing on bottlenecks)
|
||||
- Week 2: 10-12 tasks complete (parallel work)
|
||||
- Total: 16-18 tasks (80-90% of sprint backlog)
|
||||
|
||||
Key Insight: Prioritizing bottleneck tasks (T2, T5) in Week 1 unlocks maximum parallel work in Week 2.
|
||||
|
||||
Alternative Approach (Not Recommended):
|
||||
If we ignore dependencies and just pick tasks randomly:
|
||||
- Week 1: Complete 6 tasks, but 12 tasks still blocked
|
||||
- Week 2: Only 2 tasks available (both developers wait)
|
||||
- Total: 8 tasks complete (40% of sprint backlog)
|
||||
|
||||
Recommendation: Follow the suggested ordering to maximize sprint velocity.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example 7: Debugging "Why Can't I Start This Task?"
|
||||
|
||||
### Scenario
|
||||
Developer assigned to task, but unclear why they can't start yet. Need to trace back through dependency chain.
|
||||
|
||||
### User Query
|
||||
> "I'm assigned to 'Add payment webhooks' but it says dependencies aren't met. What am I waiting for?"
|
||||
|
||||
### Skill Execution
|
||||
|
||||
**Step 1**: Get the task with dependencies
|
||||
```javascript
|
||||
get_task(id="webhook-task-id", includeDependencies=true)
|
||||
```
|
||||
|
||||
**Step 2**: Trace dependency chain
|
||||
```javascript
|
||||
get_task_dependencies(taskId="webhook-task-id", includeTransitive=true)
|
||||
```
|
||||
|
||||
### Response Data
|
||||
```json
|
||||
{
|
||||
"task": {
|
||||
"id": "webhook-task-id",
|
||||
"title": "Add payment webhooks",
|
||||
"status": "pending"
|
||||
},
|
||||
"dependencies": [
|
||||
{
|
||||
"taskId": "T12",
|
||||
"title": "Implement payment processing",
|
||||
"status": "in_progress",
|
||||
"dependsOn": ["T9", "T10"]
|
||||
}
|
||||
],
|
||||
"transitiveDependencies": [
|
||||
{
|
||||
"taskId": "T9",
|
||||
"title": "Setup Stripe integration",
|
||||
"status": "completed"
|
||||
},
|
||||
{
|
||||
"taskId": "T10",
|
||||
"title": "Create payment database tables",
|
||||
"status": "in_progress"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Skill Response
|
||||
```
|
||||
Dependency Trace for "Add payment webhooks":
|
||||
|
||||
You are blocked by: T12 "Implement payment processing" (in-progress)
|
||||
|
||||
Full Dependency Chain:
|
||||
[Your Task] "Add payment webhooks"
|
||||
← T12 "Implement payment processing" (in-progress) ← YOU ARE HERE
|
||||
← T9 "Setup Stripe integration" (completed) ✓
|
||||
← T10 "Create payment database tables" (in-progress) ← ROOT CAUSE
|
||||
|
||||
Root Cause: T10 "Create payment database tables" is still in progress
|
||||
- T10 is being worked on by Database Engineer
|
||||
- Once T10 completes, T12 can finish
|
||||
- Once T12 completes, you can start your task
|
||||
|
||||
Current Status:
|
||||
- T9: ✓ Completed
|
||||
- T10: ⏳ In-progress (blocks T12)
|
||||
- T12: ⏳ In-progress (blocks your task)
|
||||
|
||||
Estimated Timeline:
|
||||
- T10 completion: Expected in 1-2 days
|
||||
- T12 completion: Expected 2 days after T10
|
||||
- Your task ready: ~3-4 days from now
|
||||
|
||||
What You Can Do Now:
|
||||
1. Review T12 "Implement payment processing" code to prepare
|
||||
2. Read Stripe webhook documentation
|
||||
3. Design webhook handling strategy
|
||||
4. Write unit tests (can start before implementation)
|
||||
5. Check if there are other tasks you can help with
|
||||
|
||||
Would you like me to find other tasks you can work on while waiting?
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example 8: Quarterly Planning - Long-term Dependencies
|
||||
|
||||
### Scenario
|
||||
Engineering manager planning Q4 roadmap. Need to understand high-level dependencies across multiple features.
|
||||
|
||||
### User Query
|
||||
> "Show me the dependency relationships between our Q4 features"
|
||||
|
||||
### Skill Execution
|
||||
|
||||
**Step 1**: Get all features in project
|
||||
```javascript
|
||||
search_features(projectId="project-id")
|
||||
```
|
||||
|
||||
**Step 2**: For each feature, analyze task dependencies
|
||||
```javascript
|
||||
// Identify cross-feature dependencies
|
||||
```
|
||||
|
||||
### Feature Dependency Map
|
||||
```
|
||||
Q4 Features (4 total):
|
||||
|
||||
F1: User Authentication (8 tasks)
|
||||
├─ No external dependencies
|
||||
└─ Blocks: F2, F3, F4
|
||||
|
||||
F2: User Dashboard (12 tasks)
|
||||
├─ Depends on: F1 (auth required)
|
||||
└─ Blocks: F4 (dashboard needed for settings)
|
||||
|
||||
F3: Payment Integration (10 tasks)
|
||||
├─ Depends on: F1 (auth required for payments)
|
||||
└─ Independent from F2, F4
|
||||
|
||||
F4: User Settings (6 tasks)
|
||||
├─ Depends on: F1 (auth), F2 (dashboard layout)
|
||||
└─ No downstream dependencies
|
||||
```
|
||||
|
||||
### Skill Response
|
||||
```
|
||||
Q4 Feature Dependency Analysis:
|
||||
|
||||
Critical Path: F1 → F2 → F4
|
||||
- Must complete sequentially
|
||||
- Total: 26 tasks across 3 features
|
||||
- Estimated: 8-10 weeks
|
||||
|
||||
Parallel Opportunity: F3 (Payment Integration)
|
||||
- Only depends on F1 (auth)
|
||||
- Can proceed in parallel with F2
|
||||
- 10 tasks, estimated: 4 weeks
|
||||
|
||||
Recommended Q4 Schedule:
|
||||
|
||||
Weeks 1-3: Feature F1 "User Authentication"
|
||||
- Critical foundation for all other features
|
||||
- 8 tasks, complexity: medium-high
|
||||
- Must complete first (blocks everything)
|
||||
|
||||
Weeks 4-7: Features F2 + F3 in parallel
|
||||
- F2 "User Dashboard" (12 tasks) ← Team A
|
||||
- F3 "Payment Integration" (10 tasks) ← Team B
|
||||
- Both can proceed simultaneously after F1
|
||||
|
||||
Weeks 8-10: Feature F4 "User Settings"
|
||||
- Depends on F1 + F2 completing
|
||||
- 6 tasks, complexity: low-medium
|
||||
- Can start once F2 completes
|
||||
|
||||
Bottleneck Analysis:
|
||||
⚠️ F1 is a critical bottleneck - it blocks ALL other Q4 work
|
||||
- Risk: If F1 slips, entire Q4 roadmap delays
|
||||
- Mitigation: Prioritize F1, assign best team, add buffer time
|
||||
|
||||
Velocity Optimization:
|
||||
- Sequential only: 16-18 weeks (F1→F2→F3→F4)
|
||||
- With parallelization: 10-12 weeks (F1→[F2+F3]→F4)
|
||||
- Time savings: 6 weeks (37% faster)
|
||||
|
||||
Recommendation:
|
||||
1. Over-invest in F1 (critical path blocker)
|
||||
2. Split teams after F1 to parallelize F2 + F3
|
||||
3. Build buffer time into F1 estimate
|
||||
4. Consider soft-launching F3 before F4 (independent feature)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Key Takeaways from Examples
|
||||
|
||||
### Pattern Recognition
|
||||
|
||||
**When user asks about**:
|
||||
- "What's blocking..." → Run `get_blocked_tasks`
|
||||
- "Can we work in parallel..." → Find tasks with no dependencies
|
||||
- "Circular dependency" → Trace dependency chain
|
||||
- "Fastest timeline" → Calculate critical path
|
||||
- "What should we prioritize" → Analyze bottlenecks + impact
|
||||
|
||||
### Response Quality
|
||||
|
||||
**Good responses include**:
|
||||
1. Clear identification of the problem
|
||||
2. Root cause analysis (why the blockage exists)
|
||||
3. Quantified impact (tasks blocked, time saved)
|
||||
4. Actionable recommendations (specific next steps)
|
||||
5. Alternative approaches when applicable
|
||||
|
||||
### Tool Combinations
|
||||
|
||||
**Most analyses require**:
|
||||
- `get_blocked_tasks` - Find what's blocked
|
||||
- `get_task_dependencies` - Understand why
|
||||
- `get_task` - Get task details (priority, complexity)
|
||||
- `search_tasks` - Find patterns across multiple tasks
|
||||
|
||||
**Power combo**:
|
||||
```javascript
|
||||
// 1. Find blocked tasks
|
||||
blockedTasks = get_blocked_tasks(featureId=X)
|
||||
|
||||
// 2. For each blocker, count impact
|
||||
for each blocker:
|
||||
impactCount = count(tasks where blockedBy contains blocker)
|
||||
|
||||
// 3. Get blocker details
|
||||
blockerDetails = get_task(id=blocker)
|
||||
|
||||
// 4. Calculate priority score
|
||||
score = (impactCount × 10) + (priority × 5) - (complexity × 2)
|
||||
|
||||
// 5. Recommend highest score task
|
||||
```
|
||||
|
||||
This pattern appears in Examples 1, 4, 5, and 6.
|
||||
650
skills/dependency-analysis/troubleshooting.md
Normal file
650
skills/dependency-analysis/troubleshooting.md
Normal file
@@ -0,0 +1,650 @@
|
||||
# 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**:
|
||||
```javascript
|
||||
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**:
|
||||
```javascript
|
||||
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**:
|
||||
```javascript
|
||||
// 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**:
|
||||
```javascript
|
||||
// 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**:
|
||||
```javascript
|
||||
// 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**:
|
||||
```javascript
|
||||
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
|
||||
```javascript
|
||||
// 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**:
|
||||
```javascript
|
||||
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
|
||||
```javascript
|
||||
// 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**:
|
||||
```javascript
|
||||
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**:
|
||||
```javascript
|
||||
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**:
|
||||
```javascript
|
||||
// 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**:
|
||||
```javascript
|
||||
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**:
|
||||
```javascript
|
||||
get_task(id="task-id", includeDependencies=true)
|
||||
```
|
||||
|
||||
2. **Check dependency statuses**:
|
||||
```javascript
|
||||
for each dependency:
|
||||
get_task(id=dep.id)
|
||||
// Is status="completed"? If not, that's the blocker
|
||||
```
|
||||
|
||||
3. **Trace transitive dependencies**:
|
||||
```javascript
|
||||
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**:
|
||||
```javascript
|
||||
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**:
|
||||
```javascript
|
||||
get_blocked_tasks(featureId="feature-id")
|
||||
```
|
||||
|
||||
4. **Identify bottlenecks**:
|
||||
```javascript
|
||||
// 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:
|
||||
|
||||
```javascript
|
||||
// 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.
|
||||
Reference in New Issue
Block a user