tim-hub/plan

CRITICAL CONSTRAINTS — Read Before Anything Else

You MUST NOT call EnterPlanMode or ExitPlanMode at any point during this skill. This skill operates in normal mode and hands off to subagent-driven-development at the end. Calling EnterPlanMode traps the session in plan mode where Write/Edit are restricted. Calling ExitPlanMode breaks the workflow and skips execution. If you feel the urge to call either, STOP — follow this skill's instructions instead.

Overview

Create an implementation plan informed by a prior exploration, and save it alongside the exploration document.

Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits.

Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well.

Step 1: Derive name and locate exploration

Same naming convention as the explore skill:

1. Parse the user's argument to determine scope and derive a kebab-case name.
2. Search .powerball/specs/ for a directory whose name ends with -{{name}} (ignoring the date prefix). If multiple matches, list them and ask.
3. If a matching directory with exploration.md is found, read it — this is the context for planning.
4. If not found, use /explore with the same argument, then read the resulting exploration.
5. If no argument is provided, ask the user to input one.

Step 2: Plan

Design an implementation plan informed by the exploration:

• Define the goal and architectural decisions
• Flag risks, unknowns, or decisions that need user input
• Consider architectural trade-offs

Step 3: Present plan

Present the plan to the user before saving:

1. Summarize the goal and key architectural decisions.
2. Flag any risks or open questions that need user input.
3. Proceed to Step 4 to save.

Step 4: Save plan

You MUST save the plan to disk before proceeding to any other step. Do NOT skip this.

1. Ensure the directory .powerball/specs/YYYY-MM-DD-{{name}}/ exists (create it if not).
2. Read the template from this skill's templates/plan.md.
3. Fill in the template with the plan from Steps 2-3:
   • Replace {{NAME}} with the derived name (title case, spaces)
   • Replace {{DATE}} with today's date (YYYY-MM-DD)
   • Fill all sections with actual plan content — remove placeholder text
   • Delete sections that don't apply
   • Keep any important information that doesn't fit other sections in the Other section
4. Use the Write tool to save the filled template to .powerball/specs/YYYY-MM-DD-{{name}}/plan.md.
5. Verify the file was written by reading it back. If it was not written, stop and report the failure.

Step 5: Write tasks and checklist in parallel

Use both skills concurrently as parallel agents:

• writing-tasks — breaks the plan into ordered, phased tasks with dependencies. Saves tasks.md.
• writing-checklist — defines verification checkpoints. Saves checklist.md.

Both skills read from the same inputs (exploration.md and plan.md) but must NOT read each other's output. This is intentional: tasks describe what to do (implementation steps), while the checklist describes what to verify (observable outcomes). Running them in parallel prevents the checklist from mirroring tasks 1:1 and instead forces outcome-oriented thinking.

For example, if the tasks are "change button text to X" and "add onClick handler to button", the checklist should NOT be "button text is X" + "onClick handler exists." It should be "clicking the button triggers action Y and log Z is visible" — verifying the combined outcome.

Step 6: Cross-validate tasks and checklist

After both artifacts are written, do a quick cross-validation:

• Every checklist item should be achievable by the tasks in tasks.md — if a checklist item has no supporting tasks, add the missing task(s).
• Every task phase should have at least one checklist item that verifies its outcome — if a phase has no coverage, add a checkpoint.
• Fix any gaps by editing the relevant file directly. Do not re-invoke the writing skills.

Step 7: Report

Tell the user:

• Summary of the plan (key phases, task count)
• Any decisions or risks that need their input
• Where the artifacts were saved:
  • plan.md — goal, architecture, risks
  • tasks.md — step-by-step implementation tasks
  • checklist.md — verification checkpoints
• Suggest /build if the plan work is complete, the build skill reads from the same specs directory