plan-decompose

[H1][PLAN-DECOMPOSE]

Dictum: Work units become issues; issues enable parallel agent execution.

Decompose plan into GitHub issues via work unit extraction.

Workflow:

1. §PARSE — Extract work units from plan
2. §VALIDATE — Verify labels exist, check structure
3. §CREATE — Create issues in dependency order
4. §LINK — Add blocker references to dependent issues

Dependencies:

• github-tools — Issue creation via gh CLI
• plan.md — Input with Work Units section

Input:

• Plan: Path to plan artifact with Work Units section

---

[1][PARSE]

Dictum: Accurate issues require complete context extraction.

Extract from plan:

Work Unit Structure:

### [N.M][WU_M]: [Name]
| [INDEX] | [KEY]    | [VALUE]   |
| :-----: | -------- | --------- |
|   [1]   | Scope    | ...       |
|   [2]   | Tasks    | N.X, N.Y  |
|   [3]   | Priority | ...       |
|   [4]   | Depends  | WU-M or — |

[VERIFY]:
- [ ] check 1
- [ ] check 2

[IMPORTANT]:

• [ALWAYS] Parse ALL work units before creating any issues.
• [ALWAYS] Extract task details for embedding in issue body.
• [NEVER] Proceed if Work Units section missing.

---

[2][VALIDATE]

Dictum: Failed operations waste agent cycles.

[2.1][VALIDATE_LABELS]

Fetch available labels via github-tools:

uv run .claude/skills/github-tools/scripts/gh.py label-list

Verify labels exist:

• task — agentic category
• triage — initial status
• Priority labels: critical, high, medium, low

[IMPORTANT] If priority label missing, fall back to task,triage only.

[2.2][VALIDATE_STRUCTURE]

[CRITICAL] Abort if structure invalid—report missing elements.

---

[3][CREATE]

Dictum: Dependency tracking requires creation order.

Create issues in dependency order (WU-1 before WU-2 if WU-2 depends on WU-1).

Per Work Unit:

[3.1][BUILD_TITLE]

[TASK]: [Work unit descriptive name]

[3.2][BUILD_LABELS]

task,triage,[priority]

[3.3][BUILD_BODY]

## [1][WORK_UNIT]: [Name]

**Plan:** [Plan title]

---
## [2][SCOPE]

[File/module area from work unit]

---
## [3][TASKS]

### [3.1][TASK_N_X]

| [INDEX] | [KEY]  | [VALUE]           |
| :-----: | ------ | ----------------- |
|   [1]   | Target | `path/to/file.ts` |
|   [2]   | Action | [Specific change] |

[Repeat for each task in work unit]

---
## [4][DEPENDENCIES]

[None OR Blocked by: #[prior issue numbers]]

---
## [5][VALIDATION]

[VERIFY]:
[Copied from work unit validation section]

---
## [6][PR_WORKFLOW]

**Branch:** `feat/[issue-number]-[slug]`

[EXECUTE]:
1. [ ] Create branch: `git checkout -b feat/[issue-number]-[slug]`
2. [ ] Implement all tasks in §TASKS
3. [ ] Run validation checks in §VALIDATION
4. [ ] Commit changes with message referencing issue
5. [ ] Push branch: `git push -u origin feat/[issue-number]-[slug]`
6. [ ] Create PR: `gh pr create --title "[TASK]: [name]"` (uses `.github/PULL_REQUEST_TEMPLATE.md`)
7. [ ] Add `Closes #[issue-number]` to PR summary section

---
## [7][COMPLETION]

[VERIFY]:
- [ ] All tasks implemented
- [ ] `nx run-many -t typecheck` — zero errors
- [ ] `nx run-many -t check` — zero Biome violations
- [ ] `pnpm sonar` — no new code smells/issues
- [ ] PR created and linked to issue

[3.4][CREATE_ISSUE]

uv run .claude/skills/github-tools/scripts/gh.py issue-create \
  --title "[TASK]: [name]" \
  --body "[body]"

Then add labels:

uv run .claude/skills/github-tools/scripts/gh.py issue-edit \
  --number [N] \
  --labels "task,triage,[priority]"

Track mapping: {WU-N: issue_number}

[CRITICAL]:

• [ALWAYS] Create in dependency order.
• [ALWAYS] Track WU → issue number mapping.
• [ALWAYS] Wait for creation success before next issue.

---

[4][LINK]

Dictum: Workflow sequencing requires explicit blockers.

After all issues created, update dependent issues with blocker references.

For each issue with dependencies:

1. Look up prior issue numbers from mapping
2. Edit issue body to include: Blocked by: #[N], #[M]

uv run .claude/skills/github-tools/scripts/gh.py issue-edit \
  --number [dependent_issue] \
  --body "[updated body with blocker refs]"

[IMPORTANT] Blocker format: Blocked by: #42, #43

---

[5][OUTPUT]

Dictum: Verification confirms successful decomposition.

Return creation summary:

## [1][DECOMPOSITION_COMPLETE]

| [INDEX] | [WORK_UNIT] | [ISSUE] | [TITLE] | [PRIORITY] | [DEPENDS] |
| :-----: | ----------- | ------- | ------- | ---------- | --------- |
|   [1]   | WU-1        | #42     | [name]  | high       | —         |
|   [2]   | WU-2        | #43     | [name]  | medium     | #42       |
|   [3]   | WU-3        | #44     | [name]  | medium     | #42, #43  |

**Total:** N issues created<br>
**Plan:** [plan title]

---

[6][VALIDATION]

Dictum: Incomplete execution corrupts downstream workflow.

[VERIFY]:

• Parse: All work units extracted
• Validate: Labels verified, structure valid
• Create: Issues created in order
• Link: Dependencies added to issue bodies
• Output: Summary table returned

---

[7][CONSTRAINTS]

[CRITICAL]:

• [ALWAYS] Parse before create—never stream.
• [ALWAYS] Create in dependency order.
• [ALWAYS] Track WU → issue mapping.
• [ALWAYS] Include validation checklist in every issue.
• [ALWAYS] Include PR_WORKFLOW section in every issue.
• [ALWAYS] Use [TASK]: prefix for titles.
• [NEVER] Create issues without Work Units section.
• [NEVER] Skip dependency linking.
• [NEVER] Hardcode labels—verify they exist first.