Planning Jira Tasks

Phase 2 is file-driven, so TICKET_KEY is sufficient. JIRA_URL is not required once the ticket snapshot already exists on disk.

The ticket snapshot must already exist at docs/<TICKET_KEY>.md with these sections, produced by fetching-jira-ticket:

Stable context sections (## Metadata, ## Retrieval Warnings, ## Attachments, ## Custom Fields) are also required by the stage-validator preflight and are produced by fetching-jira-ticket 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 TICKET_KEY, 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/<TICKET_KEY>-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
TICKET_KEY: <TICKET_KEY>
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/<TICKET_KEY>.md (ticket snapshot)
       │
       ▼
┌──────────────────────────┐
│  task-planner            │  -> Detailed tasks (what + how)
└────────┬─────────────────┘
         ▼
┌──────────────────────────┐
│  dependency-prioritizer  │  -> Dependencies + execution order
└────────┬─────────────────┘
         ▼
┌──────────────────────────┐
│  task-validator          │  -> Final validated plan + report
└──────────────────────────┘
         │
         ▼
docs/<TICKET_KEY>-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 ticket 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 ticket snapshot itself changed or must be revalidated.

2. Preflight Read the stage-validator definition and dispatch it with:

   • TICKET_KEY=<TICKET_KEY>
   • STAGE=preflight
   • FILE_PATH=docs/<TICKET_KEY>.md

   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.

3. Stage 1 - Plan Read the task-planner definition and dispatch it with:

   • TICKET_KEY=<TICKET_KEY>
   • INPUT_PATH=docs/<TICKET_KEY>.md
   • OUTPUT_PATH=docs/<TICKET_KEY>-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

   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:

   • TICKET_KEY=<TICKET_KEY>
   • STAGE=1
   • FILE_PATH=docs/<TICKET_KEY>-stage-1-detailed.md

   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.

4. Stage 2 - Prioritize Read the dependency-prioritizer definition and dispatch it with:

   • TICKET_KEY=<TICKET_KEY>
   • INPUT_PATH=docs/<TICKET_KEY>-stage-1-detailed.md
   • OUTPUT_PATH=docs/<TICKET_KEY>-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

   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:

   • TICKET_KEY=<TICKET_KEY>
   • STAGE=2
   • FILE_PATH=docs/<TICKET_KEY>-stage-2-prioritized.md

   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.

5. Stage 3 - Validate Read the task-validator definition and dispatch it with:

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

   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:

   • TICKET_KEY=<TICKET_KEY>
   • STAGE=3
   • FILE_PATH=docs/<TICKET_KEY>-tasks.md

   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.

6. Post-pipeline gate Read the stage-validator definition and dispatch it with:

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

   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.

7. 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.

8. 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, TICKET_KEY=JNS-6065, FILE_PATH=docs/JNS-6065.md -> PASS

2. Dispatch task-planner with TICKET_KEY=JNS-6065, INPUT_PATH=docs/JNS-6065.md, OUTPUT_PATH=docs/JNS-6065-stage-1-detailed.md -> wrote stage 1 artifact

3. Validate stage 1 -> PASS

4. Dispatch dependency-prioritizer with TICKET_KEY=JNS-6065, INPUT_PATH=docs/JNS-6065-stage-1-detailed.md, OUTPUT_PATH=docs/JNS-6065-stage-2-prioritized.md -> wrote stage 2 artifact

5. Validate stage 2 -> PASS

6. Dispatch task-validator with TICKET_KEY=JNS-6065, SNAPSHOT_PATH=docs/JNS-6065.md, PLAN_PATH=docs/JNS-6065-stage-2-prioritized.md, OUTPUT_PATH=docs/JNS-6065-tasks.md -> wrote final plan

7. Dispatch stage-validator with TICKET_KEY=JNS-6065, STAGE=3, FILE_PATH=docs/JNS-6065-tasks.md -> PASS

8. Dispatch stage-validator with TICKET_KEY=JNS-6065, STAGE=postpipeline, FILE_PATH=docs/JNS-6065-tasks.md -> PASS

9. Return:

   PLANNING: PASS TICKET_KEY: JNS-6065 File: docs/JNS-6065-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/JNS-6065-stage-1-detailed.md, docs/JNS-6065-stage-2-prioritized.md, docs/JNS-6065-tasks.md