planning-github-issue-tasks

Planning GitHub Issue Tasks

Plan a GitHub issue snapshot into docs/<ISSUE_SLUG>-tasks.md. This is the Phase 2 orchestrator for the GitHub planning workflow: it routes stages, dispatches specialists, preserves stage artifacts for resume and critique, and returns a concise handoff.

The orchestrator keeps only workflow state, subagent verdicts, paths, counts, and user decisions in context. Detailed contracts, templates, validation checks, and source-backed background are loaded just in time from bundled references or optional external URLs.

Inputs

Input	Required	Example
ISSUE_SLUG	Yes	acme-app-42
RE_PLAN	No	true
DECISIONS	No	SSO decision changes task dependencies

Phase 2 is file-driven. docs/<ISSUE_SLUG>.md must already exist as the GitHub issue snapshot.

Progressive Loading Map

Need	Load
Normal run, dispatch payloads, retry loop	./references/execution-guide.md
Final artifact contract, branch policy, child-issue handling	./references/output-contract.md
Critique-driven re-plan or recovery from stage artifacts	./references/re-plan-cycle.md
Source-backed background or current platform syntax	./references/external-sources.md
Subagent-specific guides, templates, or validation checks	Load only from the dispatched subagent

Bundled paths in this file are relative to this SKILL.md; files loaded later use paths relative to their own locations. All bundled files travel with the package. External URLs are optional progressive enhancement: fetch them only when local contracts need background or current syntax, and proceed from bundled references when network access is unavailable.

Subagent Registry

Subagent	Path	Purpose
task-planner	./subagents/task-planner.md	Decompose the issue and draft the stage 1 plan
dependency-prioritizer	./subagents/dependency-prioritizer.md	Add dependency order, priority, and branch names
task-validator	./subagents/task-validator.md	Validate the prioritized plan and append QA findings
stage-validator	./subagents/stage-validator.md	Check preflight, inter-stage, and final structural gates

Workflow

Path	When	Next reference
Normal	RE_PLAN is absent or false	./references/execution-guide.md
Re-plan	RE_PLAN=true with critique decisions	./references/re-plan-cycle.md, then ./references/execution-guide.md

The normal path is: preflight snapshot validation, Stage 1 detailed planning, Stage 1 validation, Stage 2 dependency/branch planning, Stage 2 validation, Stage 3 final validation report, Stage 3 validation, postpipeline validation, handoff.

Preserve docs/<ISSUE_SLUG>-stage-1-detailed.md, docs/<ISSUE_SLUG>-stage-2-prioritized.md, and docs/<ISSUE_SLUG>-tasks.md on disk. They are orchestration state for resume, critique, and targeted retries; they are not implementation outputs.

Use targeted fix loops only. Re-dispatch the stage that produced the failing artifact, pass only the validator's issue list, rerun only the failing gate, and stop after 3 failed cycles for the same gate.

Return Format

Return only this phase handoff. Use PLANNING: PASS only when every stage and stage-validation gate has passed.

PLANNING: PASS | FAIL
ISSUE_SLUG: <ISSUE_SLUG>
File: <final file path or "not written">
Tasks: <N>
Branches: <N unique branch names>
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>

Example

1. Load ./references/execution-guide.md for the dispatch payloads.
2. Dispatch stage-validator for preflight; it returns STAGE_VALIDATION: PASS.
3. Dispatch task-planner, dependency-prioritizer, and task-validator in sequence, validating after each produced artifact.
4. Dispatch stage-validator for postpipeline; it returns STAGE_VALIDATION: PASS.
5. Return the concise PLANNING: PASS handoff with preserved artifact paths.