planning-github-issue-tasks（规划 GitHub issue tasks）

Planning GitHub Issue Tasks

Plan a GitHub issue into a structured execution artifact at docs/<ISSUE_SLUG>-tasks.md. This skill is the Phase 2 orchestrator in the GitHub workflow: it dispatches specialist subagents, validates each artifact boundary, preserves planning artifacts for resume and critique, and returns only concise handoff summaries to the parent workflow. It does not decompose work, prioritize dependencies, or validate plan quality inline.

Compatibility:

• Downstream phases use TICKET_KEY-oriented handoffs and paths.
• In this workflow, TICKET_KEY and ISSUE_SLUG are the same string (for example acme-app-42).
• For cross-workflow comparison only, treat <KEY> as shorthand for this skill's platform-native work-item identifier. Runtime dispatches and returned summaries still use ISSUE_SLUG.

All artifact paths in this skill use docs/<ISSUE_SLUG>….

Inputs

Phase 2 is file-driven, so ISSUE_SLUG is sufficient. ISSUE_URL is not required once the issue snapshot already exists on disk.

The issue snapshot must already exist at docs/<ISSUE_SLUG>.md with these sections, produced by fetching-github-issue:

Stable context sections (## Metadata, ## Retrieval Warnings, ## Labels, ## Assignees, ## Milestone, ## Projects, ## Attachments) are also required by the stage-validator preflight and are produced by fetching-github-issue even when empty.

If any are missing, treat Phase 1 as incomplete and stop with a preflight failure.

If RE_PLAN=true, reuse the same ISSUE_SLUG, load ./references/re-plan-cycle.md, and pass the supplied DECISIONS only to the stages that need plan revisions.

This skill is self-contained at runtime. Use this file plus the co-located references/ and subagents/ files as the full execution contract. Treat the documented upstream snapshot artifact and parent workflow handoff as inputs, not as external runtime specs.

Output Contract

Artifact contract

Final artifact path: docs/<ISSUE_SLUG>-tasks.md

The final plan must contain all of these sections for downstream phases:

Each final task entry must include these eight subsections:

• **Objective:**
• **Relevant requirements and context:**
• **Questions to answer before starting:**
• **Implementation notes:**
• **Definition of done:**
• **Likely files / artifacts affected:**
• **Dependencies / prerequisites:**
• **Priority:**

Add **Dependency rationale:** immediately after **Dependencies / prerequisites:** when a dependency relationship needs a short explanation for downstream execution or review.

Phase 2 does not add ## Decisions Log; that artifact is appended later by Phase 3.

Return handoff

Return only the concise phase handoff below. Use PLANNING: PASS only when PLAN: PASS, PRIORITIZATION: PASS, TASK_VALIDATION: PASS, and every STAGE_VALIDATION gate returned PASS. If any stage-validator dispatch returns STAGE_VALIDATION: ERROR, stop at that gate and return PLANNING: FAIL with the existing stage-specific Failure category; the Reason must explicitly state that the validator errored.

PLANNING: PASS | FAIL
ISSUE_SLUG: <ISSUE_SLUG>
File: <final file path or "not written">
Tasks: <N>
Cross-cutting questions: <N>
Validation warnings: <N>
Failure category: PREFLIGHT | STAGE_1 | STAGE_2 | STAGE_3 | POSTPIPELINE | NONE
Reason: <one line>
Artifacts preserved: <comma-separated paths>

Workflow Overview

docs/<ISSUE_SLUG>.md (issue snapshot)
       │
       ▼
┌──────────────────────────┐
│  task-planner            │  -> Detailed tasks (what + how)
└────────┬─────────────────┘
         ▼
┌──────────────────────────┐
│  dependency-prioritizer  │  -> Dependencies + execution order
└────────┬─────────────────┘
         ▼
┌──────────────────────────┐
│  task-validator          │  -> Final validated plan + report
└──────────────────────────┘
         │
         ▼
docs/<ISSUE_SLUG>-tasks.md

Each stage writes a Category A orchestration artifact that stays on disk for Phase 3 critique, targeted retries, and workflow resume:

Preserve these planning artifacts on disk. They support resume and critique workflows, and they stay out of git history as orchestration artifacts.

Subagent Registry

Read a subagent definition only when you are about to dispatch that subagent. Do not read the stage artifacts inline unless a validator or subagent contract explicitly requires it.

How This Skill Works

This skill does exactly three things:

• Dispatch the planning subagents in sequence.
• Validate each artifact boundary with stage-validator.
• Report only stage verdicts and summary counts to the parent workflow.

The orchestrator keeps only decision-relevant handoff data between stages:

• The stage subagent status summary (PLAN, PRIORITIZATION, or TASK_VALIDATION)
• The validator verdict
• The output file path for the passing stage
• The specific issues that failed the current gate
• Retry count for the current gate

Do not carry raw plan content forward in the orchestrator context.

Phase Guide

Execution order lives in ## Execution Steps. Use this table as the gate and recovery map when deciding which stage to dispatch or retry next.

Execution Paths

Use one of these paths:

• Normal path: preflight → stage 1 → stage 2 → stage 3 → postpipeline
• Re-plan path: read ./references/re-plan-cycle.md, identify the earliest affected stage, resume from that stage using the preserved on-disk artifacts, then rerun every downstream stage and finish with postpipeline

Use targeted fix loops only. When a gate fails, re-dispatch the stage that produced the failing artifact, pass only the validator's issues list, and re-run only the failing gate. Do not restart already-passing stages unless the re-plan rules require it.

Execution Steps

1. Choose execution path

- If RE_PLAN is absent or false, run the normal path. - If RE_PLAN=true, read ./references/re-plan-cycle.md, determine the earliest affected stage, and resume from that point using the on-disk artifacts from the prior run. - Stop after 3 critique-driven re-plan iterations and escalate instead of looping indefinitely. - This re-plan cap is separate from the per-gate retry cap in Step 7. - Start at Stage 1 when the critique changes issue interpretation, scope, assumptions, or task decomposition. - Start at Stage 2 when the stage 1 task content is still valid but ordering, dependencies, or priority need to change. - Start at Stage 3 when only the final validated artifact or report needs correction. - After rerunning the earliest affected stage, rerun every downstream stage and finish with the post-pipeline gate. Skip preflight on a re-plan unless the issue snapshot itself changed or must be revalidated.

1. Preflight Read the stage-validator definition and dispatch it with: If the validator returns STAGE_VALIDATION: FAIL, stop and return PLANNING: FAIL with Failure category: PREFLIGHT. If the validator returns STAGE_VALIDATION: ERROR, stop and return PLANNING: FAIL with Failure category: PREFLIGHT. The Reason must explicitly state that the validator errored.

- ISSUE_SLUG=<ISSUE_SLUG> - STAGE=preflight - FILE_PATH=docs/<ISSUE_SLUG>.md

1. Stage 1 - Plan Read the task-planner definition and dispatch it with: If PLAN returns FAIL, BLOCKED, or ERROR, stop and return PLANNING: FAIL with Failure category: STAGE_1. Then validate stage 1 by reading the stage-validator definition and dispatching it with: If that validator returns STAGE_VALIDATION: FAIL, apply Step 7 before returning a phase failure. If that validator returns STAGE_VALIDATION: ERROR, stop and return PLANNING: FAIL with Failure category: STAGE_1. The Reason must explicitly state that the validator errored.

- ISSUE_SLUG=<ISSUE_SLUG> - INPUT_PATH=docs/<ISSUE_SLUG>.md - OUTPUT_PATH=docs/<ISSUE_SLUG>-stage-1-detailed.md - DECISIONS=<DECISIONS> only when Stage 1 is part of a re-plan - VALIDATION_ISSUES=<issues list> only when retrying Stage 1 after a failed validator gate - ISSUE_SLUG=<ISSUE_SLUG> - STAGE=1 - FILE_PATH=docs/<ISSUE_SLUG>-stage-1-detailed.md

1. Stage 2 - Prioritize Read the dependency-prioritizer definition and dispatch it with: If PRIORITIZATION returns FAIL, BLOCKED, or ERROR, stop and return PLANNING: FAIL with Failure category: STAGE_2. Then validate stage 2 by reading the stage-validator definition and dispatching it with: If that validator returns STAGE_VALIDATION: FAIL, apply Step 7 before returning a phase failure. If that validator returns STAGE_VALIDATION: ERROR, stop and return PLANNING: FAIL with Failure category: STAGE_2. The Reason must explicitly state that the validator errored.

- ISSUE_SLUG=<ISSUE_SLUG> - INPUT_PATH=docs/<ISSUE_SLUG>-stage-1-detailed.md - OUTPUT_PATH=docs/<ISSUE_SLUG>-stage-2-prioritized.md - DECISIONS=<DECISIONS> only when Stage 2 is part of a re-plan - VALIDATION_ISSUES=<issues list> only when retrying Stage 2 after a failed validator gate - ISSUE_SLUG=<ISSUE_SLUG> - STAGE=2 - FILE_PATH=docs/<ISSUE_SLUG>-stage-2-prioritized.md

1. Stage 3 - Validate Read the task-validator definition and dispatch it with: If TASK_VALIDATION returns FAIL, BLOCKED, or ERROR, stop and return PLANNING: FAIL with Failure category: STAGE_3. Then validate stage 3 by reading the stage-validator definition and dispatching it with: If that validator returns STAGE_VALIDATION: FAIL, apply Step 7 before returning a phase failure. If that validator returns STAGE_VALIDATION: ERROR, stop and return PLANNING: FAIL with Failure category: STAGE_3. The Reason must explicitly state that the validator errored.

- ISSUE_SLUG=<ISSUE_SLUG> - SNAPSHOT_PATH=docs/<ISSUE_SLUG>.md - PLAN_PATH=docs/<ISSUE_SLUG>-stage-2-prioritized.md - OUTPUT_PATH=docs/<ISSUE_SLUG>-tasks.md - VALIDATION_ISSUES=<issues list> only when retrying Stage 3 or repairing a failed post-pipeline gate - ISSUE_SLUG=<ISSUE_SLUG> - STAGE=3 - FILE_PATH=docs/<ISSUE_SLUG>-tasks.md

1. Post-pipeline gate Read the stage-validator definition and dispatch it with: This confirms the full output contract for downstream phases. If that validator returns STAGE_VALIDATION: FAIL, apply Step 7. If that validator returns STAGE_VALIDATION: ERROR, stop and return PLANNING: FAIL with Failure category: POSTPIPELINE. The Reason must explicitly state that the validator errored.

- ISSUE_SLUG=<ISSUE_SLUG> - STAGE=postpipeline - FILE_PATH=docs/<ISSUE_SLUG>-tasks.md

1. Targeted retry loop This loop applies only to STAGE_VALIDATION: FAIL results for Stage 1, Stage 2, Stage 3, and postpipeline. STAGE_VALIDATION: ERROR is terminal at the current gate and never enters this loop. Preflight failures are terminal per Step 2. If a stage subagent returns PLAN: FAIL | BLOCKED | ERROR, PRIORITIZATION: FAIL | BLOCKED | ERROR, or TASK_VALIDATION: FAIL | BLOCKED | ERROR, stop and return PLANNING: FAIL. Re-plan iterations and per-gate retry cycles are tracked separately. For any failing validator gate:

- Collect only the validator's issues list. - Re-dispatch only the stage that produced that artifact. - Pass the original inputs plus VALIDATION_ISSUES=<issues list>. - Re-run only the previously failing validator gate. - If the failed gate is postpipeline, re-dispatch Stage 3 with VALIDATION_ISSUES, then rerun STAGE=3 and STAGE=postpipeline. - Stop after 3 failed cycles for the same gate and return PLANNING: FAIL with the relevant failure category.

1. Report On success, return the completion handoff from ## Output Contract. Include the final file path, task count, cross-cutting question count, warning count, and the preserved artifact paths. State explicitly that planning is complete and implementation has not started.

Example

1. Dispatch stage-validator with STAGE=preflight, ISSUE_SLUG=acme-app-42, FILE_PATH=docs/acme-app-42.md -> PASS
2. Dispatch task-planner with ISSUE_SLUG=acme-app-42, INPUT_PATH=docs/acme-app-42.md, OUTPUT_PATH=docs/acme-app-42-stage-1-detailed.md -> wrote stage 1 artifact
3. Validate stage 1 -> PASS
4. Dispatch dependency-prioritizer with ISSUE_SLUG=acme-app-42, INPUT_PATH=docs/acme-app-42-stage-1-detailed.md, OUTPUT_PATH=docs/acme-app-42-stage-2-prioritized.md -> wrote stage 2 artifact
5. Validate stage 2 -> PASS
6. Dispatch task-validator with ISSUE_SLUG=acme-app-42, SNAPSHOT_PATH=docs/acme-app-42.md, PLAN_PATH=docs/acme-app-42-stage-2-prioritized.md, OUTPUT_PATH=docs/acme-app-42-tasks.md -> wrote final plan
7. Dispatch stage-validator with ISSUE_SLUG=acme-app-42, STAGE=3, FILE_PATH=docs/acme-app-42-tasks.md -> PASS
8. Dispatch stage-validator with ISSUE_SLUG=acme-app-42, STAGE=postpipeline, FILE_PATH=docs/acme-app-42-tasks.md -> PASS
9. Return: PLANNING: PASS ISSUE_SLUG: acme-app-42 File: docs/acme-app-42-tasks.md Tasks: 7 Cross-cutting questions: 3 Validation warnings: 1 Failure category: NONE Reason: Final plan validated and ready for Phase 3. Artifacts preserved: docs/acme-app-42-stage-1-detailed.md, docs/acme-app-42-stage-2-prioritized.md, docs/acme-app-42-tasks.md