fusion-issue-task-planning

---
name: fusion-issue-task-planning
description: Plan and break down user-story issues into ordered, traceable task issue drafts with explicit publish gates.
license: MIT
---

# User Story Task Planning

## Experimental caveat

This skill is experimental and not yet stable. Behavior, structure, and outputs may change between versions.

## When to use

Use this skill when you need an actionable task plan for a User Story issue before implementation.

Typical triggers:
- "plan tasks for #123"
- "break this story into steps"
- "create task issue drafts from this user story"

## When not to use

Do not use this skill for direct code implementation, PR review, or GitHub mutations without explicit confirmation.

## Required inputs

- Target issue reference (`owner/repo#number` or URL)
- Desired planning depth (`minimal`, `standard`, `detailed`)
- Run mode (`draft-only`, `draft+publish-ready`, or `publish-now`)

If missing inputs block planning, ask up to 3 focused follow-up questions from `assets/follow-up-questions.md`.

## Defaults

- Planning depth: `standard`
- Run mode: `draft-only`
- Publish behavior: explicit same-turn confirmation required before any mutation

## Tool format

- Tool names follow `<mcp_server>::<tool>` (example: `mcp_github::sub_issue_write`).

## Instructions

Execute in order and state assumptions explicitly.

1. Probe preferred skills and classify drafting mode
   - `orchestrated`: both `fusion-issue-authoring` and `fusion-issue-author-task` available; full workflow with explicit publish gates handled by the orchestrator.
   - `direct-subordinate`: only `fusion-issue-author-task` available; operate in **draft-only** mode using its templates and safeguards, do **not** perform any GitHub mutations, and surface drafts plus clear instructions for how an orchestrator or user should publish them.
   - `inline`: neither available; stay in **draft-only** mode, generate task drafts with a minimal built-in structure (`Title`, `Problem`, `Scope`, `Acceptance criteria mapping`, `Verification`, `Dependencies`), and avoid direct references to another skill's `assets/` files.
   - Prefer `fusion-issue-author-task` whenever it is available; do not bypass it with direct cross-skill file references.
   - Never stop due to missing preferred skills; degrade gracefully.

2. Research the user story
   - Gather title, body, acceptance criteria, scenarios, ancestor chain, existing sub-issues, and related links.
   - If issue type is ambiguous, confirm whether to proceed as `User Story`.

3. Clarify only when needed
   - Ask at most 3 questions per batch.
   - Continue with explicit assumptions when safe defaults exist.

4. Extract planning anchors
   - Outcomes
   - Constraints and non-goals
   - Verification points

5. Build dependency-ordered tasks
   - For each task include objective, scope boundary, deliverable, verification method, and mapped AC references.
   - Prefer independently verifiable slices.

6. Run devil's-advocate review before drafting
   - Inspect the proposed task set for architecture-ambiguity signals:
     - Unresolved design or architecture decisions mentioned in the story, comments, or ancestor issues
     - Backend and frontend tasks that share an implicit API, data model, or ownership contract not yet agreed
     - A discovery, research, or alignment task alongside concrete implementation tasks with no explicit blocking relationship
     - Dependency statements that are vague or circular ("after backend is done", "when design is ready")
     - Component, API, or data-model ownership that is unclear or contested
   - If two or more signals are present:
     - `orchestrated` mode: route through `fusion-issue-authoring` → `agents/devils-advocate.agent.md` in **interrogator mode** automatically — no user trigger required.
     - `direct-subordinate` or `inline` mode: run an inline DA checklist using the same five signals above; surface findings as a structured `⚠ Ambiguity checklist` and require the user to resolve or explicitly accept each before draft generation.
   - If zero or one signal is present, run in **moderate mode**: surface up to 3 concerns and continue after the user acknowledges.
   - **Publish gate** (all modes): do not publish tasks until either the devil's advocate confirms the split is sound or the user explicitly accepts the listed risks.
   - **Draft-only exception**: in `draft-only` mode, draft generation may proceed even with unresolved ambiguities, but emit an `⚠ Ambiguity warning` block at the top of the plan preview listing each unresolved item. Publication remains blocked until risks are accepted.

7. Generate task issue drafts
   - `orchestrated`: route through `fusion-issue-authoring` with issue type `Task`
   - `direct-subordinate`: invoke `fusion-issue-author-task` in draft-only mode and output explicit publish instructions that delegate final mutation to `fusion-issue-authoring`
   - `inline`: write `.tmp/TASK-<nn>-<slug>.md` drafts using the minimal built-in structure from step 1
   - Keep drafts local until explicit publish approval.

8. Generate plan preview
   - Write `.tmp/USER-STORY-TASK-PLAN-<context>.md` from `assets/task-plan-template.md`.
   - Include summary, traceability, ordered tasks, draft paths, publish plan, assumptions, risks.

9. Publish only after explicit confirmation
   - Require explicit confirmation in the same turn.
   - Stop if unresolved assumptions remain.
   - Delegate publish execution to `fusion-issue-authoring` and prefer sub-agent invocation for task issue creation/update/linking.
   - Pass required context to `fusion-issue-authoring`: `owner`, `repo`, parent story reference, ordered task drafts, labels/assignee intent, and dependency ordering.
   - Require `fusion-issue-authoring` to keep MCP-first behavior and apply GraphQL fallback only when MCP write coverage is unavailable.
   - The orchestrator's session-cache rules apply to all delegated calls: labels, assignee candidates, and issue types are fetched once per session and reused across all task issues in the batch.
   - Budget awareness: a task-planning publish of N tasks costs ~N issue-write mutations + optional sub-issue link mutations. If N > 5, warn the user about rate-limit risk and offer to publish in batches.
   - Do not call MCP write tools directly from this skill in publish mode.
   - Hard fail publish mode if delegated execution returns unresolved item-level failures.

10. Repair mode for already-created tasks
   - If tasks were created but are missing `Issue Type` or parent linkage, delegate repair to `fusion-issue-authoring` and prefer sub-agent invocation.
   - Provide per-issue repair intent (`set type=Task`, add missing parent links, preserve order) and require verification results from the delegated run.
   - Repair mode must be idempotent: skip already-correct issues and fix only missing metadata.
   - Run post-flight verification after repairs and return actionable failures.

## Common failures and resolution

- `fusion-issue-authoring` is unavailable in the runtime
   - Stay in draft-only mode and return publish-ready artifacts plus explicit handoff instructions.
- Delegated publish returns partial failures
   - Return per-issue `failed` status with exact reason and stop further mutations until user confirmation.
- Task issues are created but not linked to the parent story
   - Trigger delegated repair through `fusion-issue-authoring` and require post-flight verification output.
- Task exists but `Issue Type` is missing or incorrect
   - Trigger delegated repair through `fusion-issue-authoring` with `type=Task` intent and verify results.
- Post-flight verification reports partial failures
   - Return per-issue `failed` status with exact reason, stop publish flow, and keep unresolved items for explicit user decision.

## Expected output

Return in this heading order:
1. Experimental caveat
2. Story summary
3. Acceptance-criteria traceability
4. Ordered tasks
5. Draft file paths
6. Publish plan
7. Assumptions, risks, and open questions

Always include: `Status: Awaiting user approval` until publish is confirmed and completed.

For `publish-now` or `repair` mode, include a per-issue post-flight report with:
- issue exists
- issue type equals requested type
- parent equals expected story number
- status (`ok`, `fixed`, or `failed`)

## Assets

- [assets/follow-up-questions.md](assets/follow-up-questions.md)
- [assets/task-plan-template.md](assets/task-plan-template.md)

## Safety & constraints

- This skill is mutation-capable. Repository-local workflow instructions take precedence over inline guidance when they conflict.
- Never mutate GitHub state without explicit confirmation.
- Never infer acceptance criteria without flagging assumptions.
- Always preserve AC traceability in the task plan.
- Keep drafts in `.tmp/` before any publish action.
- In publish/repair mode, treat missing `Issue Type` or missing parent linkage as a failure until post-flight checks pass.
- Delegate mutation/repair execution to `fusion-issue-authoring` (prefer sub-agent) and do not call MCP write tools directly from this skill.