technical-planning

name	technical-planning
description	Transform specifications into actionable implementation plans with phases, tasks, and acceptance criteria. Use when: (1) User asks to create/write an implementation plan, (2) User asks to plan implementation from a specification, (3) Converting specifications from .workflows/specification/{topic}/specification.md into implementation plans, (4) User says 'plan this' or 'create a plan', (5) Need to structure how to build something with phases and concrete steps. Creates plans in .workflows/planning/{topic}/plan.md that can be executed via strict TDD.
user-invocable	false

Technical Planning

Act as expert technical architect, product owner, and plan documenter. Collaborate with the user to translate specifications into actionable implementation plans.

Your role spans product (WHAT we're building and WHY) and technical (HOW to structure the work).

Purpose in the Workflow

This skill can be used:

• Sequentially: From a validated specification
• Standalone (Contract entry): From any specification meeting format requirements

Either way: Transform specifications into actionable phases, tasks, and acceptance criteria.

What This Skill Needs

• Specification content (required) - The validated decisions and requirements to plan from
• Topic name (optional) - Will derive from specification if not provided
• Output format preference (optional) - Will ask if not specified
• Recommended output format (optional) - A format suggestion for consistency with existing plans
• Work type (optional) — greenfield, feature, or bugfix. Determines which context-specific guidance is loaded during phase and task design. Defaults to greenfield when not provided.
• Cross-cutting references (optional) - Cross-cutting specifications that inform technical decisions in this plan

Before proceeding, verify the required input is available and unambiguous. If anything is missing or unclear, STOP — do not proceed until resolved.

If no specification content provided

Output the next fenced block as a code block:

I need the specification content to plan from. Could you point me to the
specification file (e.g., .workflows/specification/{topic}/specification.md),
or provide the content directly?

STOP. Wait for user response.

If specification seems incomplete or not concluded

Output the next fenced block as a code block:

The specification at {path} appears to be {concern — e.g., 'still in-progress'
or 'missing sections that are referenced elsewhere'}. Should I proceed with
this, or is there a more complete version?

STOP. Wait for user response.

---

Resuming After Context Refresh

Context refresh (compaction) summarizes the conversation, losing procedural detail. When you detect a context refresh has occurred — the conversation feels abruptly shorter, you lack memory of recent steps, or a summary precedes this message — follow this recovery protocol:

1. Re-read this skill file completely. Do not rely on your summary of it. The full process, steps, and rules must be reloaded.
2. Read all tracking and state files for the current topic — plan index files, review tracking files, implementation tracking files, or any working documents this skill creates. These are your source of truth for progress. Check for scratch files at .workflows/.cache/planning/{topic}/. If a scratch file exists, you are mid-authoring for that phase — resume the approval loop in author-tasks.md.
3. Check git state. Run git status and git log --oneline -10 to see recent commits. Commit messages follow a conventional pattern that reveals what was completed.
4. Announce your position to the user before continuing: what step you believe you're at, what's been completed, and what comes next. Wait for confirmation.
5. Check task_list_gate_mode, author_gate_mode, and finding_gate_mode in the Plan Index File frontmatter — if auto, the user previously opted in during this session. Preserve these values.

Do not guess at progress or continue from memory. The files on disk and git history are authoritative — your recollection is not.

---

The Process

This process constructs a plan from a specification. A plan consists of:

• Plan Index File — .workflows/planning/{topic}/plan.md. Contains frontmatter (topic, format, status, progress), phases with acceptance criteria, and task tables tracking status. This is the single source of truth for planning progress.
• Authored Tasks — Detailed task files written to the chosen Output Format (selected during planning). The output format determines where and how task detail is stored.

Follow every step in sequence. No steps are optional.

Output Formatting

When announcing a new step, output ── ── ── ── ── on its own line before the step heading.

---

Step 0: Resume Detection

Check if a Plan Index File already exists at .workflows/planning/{topic}/plan.md.

If no Plan Index File exists

→ Proceed to Step 1.

If Plan Index File exists

If status: concluded, update it to status: planning.

Note the current phase and task position from the planning: block.

Load spec-change-detection.md to check whether the specification has changed since planning started. Then present the user with an informed choice:

Found existing plan for {topic} (previously reached phase {N}, task {M}).

{spec change summary from spec-change-detection.md}

Output the next fenced block as markdown (not a code block):

· · · · · · · · · · · ·
- **`c`/`continue`** — Walk through the plan from the start. You can review, amend, or navigate at any point — including straight to the leading edge.
- **`r`/`restart`** — Erase all planning work for this topic and start fresh. This deletes the Plan Index File and any Authored Tasks. Other topics are unaffected.
· · · · · · · · · · · ·

STOP. Wait for user response.

If continue

If the specification changed, update spec_commit in the Plan Index File frontmatter to the current commit hash.

Reset task_list_gate_mode, author_gate_mode, and finding_gate_mode to gated in the Plan Index File frontmatter (fresh invocation = fresh gates).

→ Proceed to Step 1.

If restart

1. Read output-formats.md, find the entry matching the format: field in the Plan Index File, and load the format's authoring.md
2. Follow the authoring file's cleanup instructions to remove Authored Tasks for this topic
3. Delete the scratch directory if it exists: rm -rf .workflows/.cache/planning/{topic}/
4. Delete the Plan Index File
5. Commit: planning({topic}): restart planning

→ Proceed to Step 1.

---

Step 1: Initialize Plan

If Plan Index File already exists

Read output-formats.md, find the entry matching the format: field, and load the format's about.md and authoring.md.

→ Proceed to Step 2.

If no Plan Index File exists

First, choose the Output Format.

If a recommended output format was provided (non-empty, not "none"):

Present the recommendation:

Existing plans use {format}. Use the same format for consistency?

Output the next fenced block as markdown (not a code block):

· · · · · · · · · · · ·
- **`y`/`yes`** — Use {format}
- **`n`/`no`** — See all available formats
· · · · · · · · · · · ·

STOP. Wait for user choice. If declined, fall through to the full list below.

If no recommendation, or user declined:

Present the formats from output-formats.md to the user — including description, pros, cons, and "best for". Number each format and ask the user to pick.

STOP. Wait for the user to choose.

Once selected:

1. Read output-formats.md, find the chosen format entry, and load the format's about.md and authoring.md

2. Capture the current git commit hash: git rev-parse HEAD

3. Create the Plan Index File at .workflows/planning/{topic}/plan.md using the Frontmatter and Title templates from plan-index-schema.md. Set status: planning, spec_commit to the captured git hash, today's actual date for created and updated, and work_type to the value provided by the caller (or greenfield if not provided).

4. Commit: planning({topic}): initialize plan

→ Proceed to Step 2.

---

Step 2: Load Planning Principles

Load planning-principles.md and follow its instructions as written.

→ Proceed to Step 3.

---

Step 3: Verify Source Material

Load verify-source-material.md and follow its instructions as written.

→ Proceed to Step 4.

---

Step 4: Plan Construction

Load plan-construction.md and follow its instructions as written.

→ Proceed to Step 5.

---

Step 5: Analyze Task Graph

Load analyze-task-graph.md and follow its instructions as written.

→ Proceed to Step 6.

---

Step 6: Resolve External Dependencies

Load resolve-dependencies.md and follow its instructions as written.

→ Proceed to Step 7.

---

Step 7: Plan Review

Load plan-review.md and follow its instructions as written.

→ Proceed to Step 8.

---

Step 8: Conclude the Plan

CHECKPOINT: Do not conclude if any tasks in the Plan Index File show status: pending. All tasks must be authored before concluding.

Output the next fenced block as markdown (not a code block):

· · · · · · · · · · · ·
- **`y`/`yes`** — Conclude plan and mark as concluded
- **Comment** — Add context before concluding
· · · · · · · · · · · ·

STOP. Wait for user response.

If comment

Discuss the user's context. If additional work is needed, route back to Step 6 or Step 7 as appropriate. Otherwise, re-present the sign-off prompt above.

If yes

1. Update plan status — Set status: concluded in the Plan Index File frontmatter
2. Final commit — Commit the concluded plan: planning({topic}): conclude plan
3. Present completion summary:

Output the next fenced block as markdown (not a code block):

Planning is complete for **{topic}**.

The plan contains **{N} phases** with **{M} tasks** total, reviewed for traceability against the specification and structural integrity.

Status has been marked as `concluded`. The plan is ready for implementation.