# Dag Generation

> Generate task DAGs for modernization projects — select fragments from task catalog, produce initial DAG (Stage 1), and execute/validate DAG from plan artifacts (Stage 2).

- Skill: `microsoft/dag-generation` (Agent Skill, multi-file: 4 files)
- Install (CLI): `npx skillmds@latest add microsoft/dag-generation`
- Raw SKILL.md: https://api.skillmd.com/api/skills/microsoft/dag-generation/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: Microsoft (https://skillmd.com/u/microsoft)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/microsoft/dag-generation

---


# DAG Generation

Two-stage DAG generation for modernization projects:
1. **Stage 1** (§1.4) — select fragments from task-catalog, determine deep_planning, produce DAG JSON
2. **Stage 2** (§3.2.2) — when deep planning, read plan artifacts, produce execute+validate DAG

## Reference Files

- `references/task-catalog.md` — fragment library with when/skip-when/after/scope
- `references/dag-rules.md` — DAG construction rules (dependencies, compression, sizing)

## Stage 1: Initial DAG

Select fragments from the task catalog and produce a DAG.

### Inputs

1. **Project profile** — read from `{{BASE_PATH}}/artifacts/project-profile.yaml` (project.loc, project.languages, project.modules, assessment.change_type, assessment.grouping_needed)
2. **user_ask** — natural-language migration target (passed by coordinator)

If `user_ask` names an explicit target stack or version, preserve it verbatim in every selected task. Do not replace, downgrade, or reinterpret the requested version based on model familiarity or LTS defaults.

### Decision Procedure

#### Step 1: Determine deep_planning

Decide whether the project needs deep planning (two-stage DAG) or can produce a complete DAG upfront.

**`deep_planning: true`** when:
- Multiple modules with cross-module dependencies that require discovery before execute tasks can be defined
- change_type is rewrite or extract AND the target architecture is not yet clear (needs design exploration)
- The project is large enough that execute task structure genuinely cannot be enumerated without plan-phase artifacts

**`deep_planning: false`** when:
- Single module or few modules with clear structure
- change_type is upgrade — target is well-defined (version to version)
- Execute tasks can be directly derived from the project profile without intermediate artifacts
- Small projects where one developer could hold the full context

#### Step 2: Select fragments
Read `references/task-catalog.md`. For each fragment, decide include/exclude based on:
- change_type (upgrade | extract | rewrite)
- user_ask intent
- Project profile (LOC, modules)
- `deep_planning` decision from Step 1 (drives `implementation-plan` selection)

Always include `target-env-prep` when the target runtime/framework/language/tooling differs from source or when the user specifies an explicit target version. This is an environment preparation task: it must install/provision/activate the requested target when possible, produce a preparation artifact, and run before scaffold/implementation/build/test tasks. It normally has no dependency on architecture/source analysis and should run in parallel with those tasks. This is true even for small projects and even when `deep_planning: false`.

Respect `when` / `skip-when` conditions and `after` ordering from the catalog.

**⛔ Skip-when enforcement (mandatory post-selection gate):**
After initial selection, sweep every selected fragment and check its `skip-when` against the current context (deep_planning value, change_type, project scale, other selected fragments). Any fragment whose skip-when condition is satisfied MUST be removed — no exceptions. Specifically:
- `implementation-plan`: remove if `deep_planning: false`

This gate catches cases where the initial selection included fragments that looked relevant but conflict with the deep_planning decision or project scale.

**✅ Explicit-request override (runs AFTER skip-when enforcement — highest precedence):**
If `user_ask` explicitly requests a completeness, consistency, or feature-parity check (e.g. "run a completeness check", "verify nothing was missed", "enforce consistency", "feature parity sign-off"), force-include the completeness/conformance validation fragment (`conformance-review`, and `feature-parity-signoff` when applicable) **even if its `skip-when` condition matched and removed it above**. User intent overrides the size/type heuristic. This override is **one-directional** — it can only ADD a gate the heuristics dropped, never remove one they selected. It must run after the skip-when sweep, otherwise the sweep would strip the fragment back out (e.g. `skip-when: same-stack upgrade`).

Fragment selection is an internal decision — do NOT output the selection rationale to the user. The DAG itself is the user-facing result.

#### Step 3: Generate DAG
Read `references/dag-rules.md` for construction rules.

- **If `deep_planning: true`** → produce only plan-phase tasks as JSON
- **If `deep_planning: false`** → produce the complete DAG (plan + execute + validate) as JSON

### Output

Return JSON to the coordinator (do NOT write files):

```json
{
  "deep_planning": true,
  "tasks": [
    {"id": "t1", "role": "<role>", "title": "<title>", "depends_on": [], "phase_label": "<label>"},
    {"id": "t2", "role": "<role>", "title": "<title>", "depends_on": ["t1"], "phase_label": "<label>"}
  ]
}
```

## Stage 2: Execute+Validate DAG

When plan phase completes and `deep_planning: true`, generate the execute+validate DAG from plan artifacts.

### Inputs (provided by coordinator)

- Artifact base path
- User ask (original migration request)
- Change type (upgrade / extract / rewrite)
- Grouping mode and in-scope groups
- Fan-out file path
- Task ID offset (continue from last plan-phase task)

### Procedure

1. Read plan artifacts (implementation plan, architecture analysis, etc.)
2. Read `references/dag-rules.md` for construction rules
3. Read `references/task-catalog.md` for fragment definitions
4. Generate JSON task graph per dag-rules.md

### Output

```json
{"tasks": [{"id": "t<N>", "role": "<role>", "title": "<title>", "depends_on": ["<id>", ...], "phase_label": "<label>"}]}
```

## What this skill does NOT do

- Does NOT decide grouping / topology (coordinator decides in §1.3)
- Does NOT compute topology groupings (that's `project-decomposition`)
- Does NOT perform role discovery from charters (assigns roles based on task content; coordinator refines using team-charters at dispatch)
- Does NOT match task → skill (that's worker subagent)
- Does NOT execute anything (that's coordinator + workers)
- Does NOT prompt user (that's coordinator at checkpoint)