Spell Task Graph

## Summary

**Map task dependencies into execution order, or diagram a process workflow.** Uses directed acyclic graphs (DAGs), topological sorting, and critical path analysis to produce Mermaid diagrams with structured analysis. Operates in two modes depending on input.

**Arguments:** `$ARGUMENTS` (required) - Task list, process description, or file path

**Output:** Mermaid diagram + structured text analysis output directly to the conversation

---

## Skill References

Before proceeding, load the relevant skill documents for reference:

Read the following files from the repository root:
- `docs/skills/dag-analysis.md`
- `docs/skills/topological-sort.md`
- `docs/skills/mermaid-flowcharts.md`

---

## Process

### Step 1: Determine Mode

Parse `$ARGUMENTS` to determine which mode to operate in:

| Input | Mode | What happens |
|-------|------|--------------|
| A task list, backlog, or "tasks" keyword | **Task Mapping** | Build dependency DAG, compute execution order |
| "process", "flow", "pipeline", "workflow" keyword | **Process Flow** | Diagram a workflow with decision points |
| A file path or "codebase" | **Task Mapping** | Scan codebase for TODOs/tasks, build DAG |

**If `$ARGUMENTS` is ambiguous:**
Ask the user whether they want to map task dependencies or diagram a process flow.

---

### Mode A: Task Mapping

Build a dependency graph, compute execution order, and identify the critical path.

**Step A1: Gather tasks**

Collect tasks from one of these sources:

1. **User-provided list:** Parse tasks and dependencies from `$ARGUMENTS`
2. **Codebase scan:**
   Search the codebase for TODO, FIXME, and task markers.
3. **Interactive:** If the task list is unclear, ask the user to list their tasks

For each task, capture:
- **Name** (short, actionable — verb phrase)
- **Dependencies** (what must finish before this can start)
- **Duration estimate** (optional — use 1 if unknown)

**Step A2: Identify dependencies**

For each pair of tasks, determine if a dependency exists. Rules:
- **Never invent dependencies** — only include dependencies the user stated or that are logically necessary
- If dependencies aren't explicit, ask the user: "Which of these tasks depend on others?"
- Look for signals: "after", "needs", "requires", "blocks", "then"
- Shared resources (same file, same service) suggest possible dependencies — flag but don't assume

**Step A3: Build and validate the DAG**

1. Construct the directed graph from tasks and dependencies
2. **Detect cycles:** If found, report immediately with the cycle path and stop — ask the user to resolve
3. **Apply transitive reduction:** Remove redundant edges (if A→B→C exists, remove A→C)
4. **Validate against checklist** from `docs/skills/dag-analysis.md`:
   - No orphan nodes, no dead ends
   - Fan-in/fan-out within limits
   - Edge/node ratio reasonable
5. **Check node count:** If > 15 nodes, suggest decomposition per the skill doc

**Step A4: Compute execution order**

Using the approach from `docs/skills/topological-sort.md`:

1. **Topological sort** (Kahn's algorithm with priority queue):
   - Priority: critical path > fan-out > duration > alphabetical
2. **Critical path:** Compute ES/EF/LS/LF for each task, identify slack-0 chain
3. **Parallel waves:** Group tasks by wave (level-based grouping)
   - Wave 1 = all tasks with no dependencies
   - Wave N = tasks whose last dependency completes in wave N-1

**Step A5: Output results**

Generate a Mermaid diagram following `docs/skills/mermaid-flowcharts.md` conventions:
- Direction: `flowchart TD` (dependencies flow top-down)
- Thick edges (`==>`) for critical path
- Dotted edges (`-.->`) for optional dependencies
- `classDef` for task status if status is known
- Subgraphs if > 15 nodes

Then output the structured analysis: