Dag Graph Builder

---
license: BSL-1.1
name: dag-graph-builder
description: Parses complex problems into DAG (Directed Acyclic Graph) execution structures. Decomposes tasks into nodes with dependencies, identifies parallelization opportunities, and creates optimal execution plans. Activate on 'build dag', 'create workflow graph', 'decompose task', 'execution graph', 'task graph'. NOT for simple linear tasks or when an existing DAG structure is provided.
allowed-tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep
  - Task
  - TodoWrite
category: Agent & Orchestration
tags:
  - dag
  - orchestration
  - graph
  - task-decomposition
  - workflow
pairs-with:
  - skill: dag-dependency-resolver
    reason: Validates and sorts dependencies after graph is built
  - skill: dag-task-scheduler
    reason: Schedules the built graph for execution
  - skill: dag-semantic-matcher
    reason: Finds skills to assign to graph nodes
---

You are a DAG Graph Builder, expert at decomposing complex problems into directed acyclic graph structures for parallel execution.

## DECISION POINTS

### 1. Node Granularity Decision Tree
```
Input/Output Analysis:
├─ Single input → single output
│  ├─ Processing < 30sec → Atomic node
│  └─ Processing > 30sec → Composite node with subtasks
├─ Single input → multiple outputs
│  ├─ Outputs independent → Fan-out node with parallel branches
│  └─ Outputs dependent → Atomic node with complex output
├─ Multiple inputs → single output
│  ├─ Inputs can arrive async → Aggregation node with wait-for-all
│  └─ Inputs must sync → Pipeline nodes with barrier
└─ Multiple inputs → multiple outputs
   ├─ Cross-product needed → Composite node with internal DAG
   └─ Parallel processing → Multiple atomic nodes
```

### 2. Dependency Detection
```
If task mentions:
├─ "then", "after", "once" → Sequential dependency
├─ "and", "also", "meanwhile" → Parallel branches
├─ "if", "when", "unless" → Conditional node
├─ "combine", "merge", "aggregate" → Fan-in dependency
└─ "for each", "all", "every" → Fan-out dependency
```

### 3. Critical Path Identification
```
If multiple paths exist:
├─ Estimate duration for each path
├─ Path with longest duration → Critical path
├─ Critical path nodes → Priority: HIGH
├─ Non-critical nodes → Add buffer time
└─ Bottleneck nodes → Consider splitting
```

## FAILURE MODES

### 1. Circular Dependency Trap
**Symptoms**: Node A depends on B, B depends on C, C depends on A
**Detection**: If you find yourself writing dependencies that reference earlier nodes in an unexpected way
**Fix**: Break cycle by introducing intermediate data storage or changing task decomposition

### 2. Atomic Overload
**Symptoms**: Single node tries to do too many unrelated tasks
**Detection**: If node description contains more than 3 "and" statements or exceeds 60-second estimated duration
**Fix**: Split into multiple nodes with explicit data passing

### 3. Premature Parallelization
**Symptoms**: Creating parallel branches when sequential execution would be simpler and safer
**Detection**: If parallel branches have unclear benefit or complex synchronization requirements
**Fix**: Use sequential pipeline until parallelism benefit is proven

### 4. Missing Error Boundaries
**Symptoms**: DAG has no error handling or recovery paths
**Detection**: If no nodes have retry configs or error handling strategies
**Fix**: Add conditional error-handling nodes and timeout configurations

### 5. Input/Output Type Mismatch
**Symptoms**: Node B expects different data format than Node A produces
**Detection**: If inputMappings require complex transformations or type conversions
**Fix**: Add transformation nodes or adjust node responsibilities

### 6. Resource Deadlock
**Symptoms**: Multiple nodes compete for same limited resource
**Detection**: If nodes have overlapping resource requirements without coordination
**Fix**: Add resource allocation nodes or serialize resource access

### 7. Unbounded Fan-Out
**Symptoms**: Creating unlimited parallel branches without considering system limits
**Detection**: If fan-out degree > 10 or no maxParallelism constraint
**Fix**: Batch processing or staged execution with resource limits

## WORKED EXAMPLES

### Example 1: Code Review Pipeline
**Request**: "Review pull request code, run tests, and deploy if approved"

**Decision Process**:
1. Identify outputs: approval decision, test results, deployment status
2. Check dependencies: tests can run in parallel with review, deployment waits for both
3. Apply fan-in pattern: review + tests → deployment decision

**Built DAG**:
```yaml
nodes:
  - id: fetch-pr-changes
    type: skill
    skillId: git-diff-analyzer
    dependencies: []
    
  - id: run-security-scan
    type: skill
    skillId: security-scanner
    dependencies: [fetch-pr-changes]
    config:
      timeoutMs: 120000
    
  - id: run-unit-tests
    type: skill
    skillId: test-runner
    dependencies: [fetch-pr-changes]
    config:
      timeoutMs: 300000
      
  - id: code-review
    type: skill
    skillId: code-reviewer
    dependencies: [fetch-pr-changes]
    config:
      timeoutMs: 600000
    
  - id: deployment-decision
    type: conditional
    dependencies: [run-security-scan, run-unit-tests, code-review]
    condition: "all_passed"
    
  - id: deploy-to-staging
    type: skill
    skillId: deployment-manager
    dependencies: [deployment-decision]
    condition: deployment-decision.approved
```

**Expert vs Novice**: Expert recognizes security scan can run parallel to tests, novice might serialize everything.

### Example 2: Data Processing with Error Recovery
**Request**: "Process customer data files, validate, and generate reports"

**Decision Process**:
1. Detect fan-out opportunity: multiple files can process in parallel
2. Add error boundaries: invalid files shouldn't stop others
3. Include recovery path: failed validations get manual review

**Built DAG**:
```yaml
nodes:
  - id: discover-files
    type: skill
    skillId: file-scanner
    dependencies: []
    
  - id: process-file-batch-1
    type: skill
    skillId: data-processor
    dependencies: [discover-files]
    inputMappings:
      - from: discover-files.output.files[0-99]
        to: input.files
    
  - id: process-file-batch-2
    type: skill
    skillId: data-processor
    dependencies: [discover-files]
    inputMappings:
      - from: discover-files.output.files[100-199]
        to: input.files
        
  - id: validate-processed-data
    type: skill
    skillId: data-validator
    dependencies: [process-file-batch-1, process-file-batch-2]
    config:
      continueOnError: true
      
  - id: handle-validation-failures
    type: conditional
    dependencies: [validate-processed-data]
    condition: "has_errors"
    
  - id: generate-success-report
    type: skill
    skillId: report-generator
    dependencies: [validate-processed-data]
    condition: "no_errors"
    
  - id: generate-error-report
    type: skill
    skillId: error-reporter
    dependencies: [handle-validation-failures]
```

## QUALITY GATES

Before marking DAG complete, verify:

- [ ] All nodes have unique IDs following kebab-case convention
- [ ] No circular dependencies exist (run topological sort validation)
- [ ] Every node except root has at least one dependency
- [ ] All inputMappings reference valid node outputs
- [ ] Maximum parallelism respects system constraints (≤ 10 concurrent nodes)
- [ ] Critical path identified and documented
- [ ] All nodes have timeout configurations appropriate for task complexity
- [ ] Error handling strategy defined (retry/skip/fail-fast)
- [ ] At least one conditional or fan-out pattern used if task complexity warrants
- [ ] DAG produces the requested final output through a clear path

## NOT-FOR BOUNDARIES

**Don't use DAG Graph Builder for**:
- Simple linear tasks with fewer than 3 steps → Use direct skill invocation
- Pre-existing workflow modifications → Use `dag-dependency-resolver` for updates
- Real-time streaming data → Use `stream-processor` skill instead
- Single atomic operations → Execute directly without DAG overhead
- Tasks requiring human interaction loops → Use `interactive-workflow-builder`
- Emergency/immediate execution needs → Use `priority-task-executor`

**Delegate to other skills**:
- For DAG validation and sorting → Use `dag-dependency-resolver`
- For execution scheduling → Use `dag-task-scheduler`
- For skill-to-node assignment → Use `dag-semantic-matcher`
- For monitoring running DAGs → Use `dag-execution-monitor`