Detailed Execution Planner

Skill Purpose

Write detailed execution plans that are specific, test-gated, and aligned with requirements and technical specifications. Invoke this workflow only when explicitly requested by the user.

Use This Skill When

The user asks to create a plan.
The user asks to update or refine an existing plan.
A task needs a step-by-step implementation sequence before coding starts.
A workstream must explicitly follow BDD/TDD with functional testing.

Before Building Plan

Ask the user detailed questions about anything on which you are not 100% certain. Ask questions one at a time. Continue asking questions until you are sure you have all needed information and there are zero ambiguities.

Select the Plan Target

Determine the requested consumer from the user's request, the existing plan artifact, and the available host tools before choosing a format. If those signals conflict or neither Cursor nor Xorc is established, ask which target is intended rather than guessing or combining schemas.

For Xorc .xorcp.md plans, read and follow Xorc Planning Workflow, including its validation and update rules. Do not use the Cursor template, todos frontmatter, or Cursor TODO synchronization for Xorc. After completing that workflow, stop; every section below this target-selection section applies only to Cursor plans.
For Cursor .plan.md plans, follow the remaining sections and the Cursor template they reference. Keep native Xorc fields and lifecycle operations out of the Cursor artifact.

Cursor Plan Frontmatter (Required)

For Cursor plans only, every generated plan must begin with YAML frontmatter that matches the Cursor plan shape so plans can be imported and tracked as todos.

name: short human-readable plan title (string).
overview: multi-line summary of goal, scope, and approach (YAML | block string).
todos: ordered list of steps; one todo per execution step, in the same order as the checklist under ## Execution Plan (see below).

Each todo entry must include:

id: stable unique id for that step (e.g. my-plan-step-001, incrementing).
content: same intent as the matching markdown checkbox line; must be as specific as the checkbox (commands, paths, test names - not shortened into vague summaries).
status: pending or completed (use pending for new plans unless the user marks work done).
dependencies: optional; for a linear plan, each step after the first should list the previous step's id so ordering is explicit.
For parallel work, use the same dependency pattern only when the user asks for it.

Synchronization Rule

The number of items in todos, their order, and their meaning must match every - [ ] / - [x] line under ## Execution Plan (only those lines; section headings are not steps).

When you update the plan body, update todos in lockstep.

Flat Checklist Only: No Nested Step Bullets

Use a single flat list of top-level checkboxes for all work.

Do not nest checklist items under other checklist items.

Anti-Pattern Examples

- [ ] Higher-level step:
  - [ ] Sub-step 1
  - [ ] Sub-step 2

Preferred Pattern

Split into separate top-level steps (same content, no hierarchy under a parent checkbox):

- [ ] Higher-level step - sub-step 1 (describe concrete action).
- [ ] Higher-level step - sub-step 2 (describe concrete action).

Section headings (###, ####) still group work; only the checkbox list stays flat.

Explicit Step Wording (Required)

Every step (checkbox line and matching todos[].content) must be specific enough that an executor never has to guess what to run, open, or change.

What Each Step Must Name (When Applicable)

Commands: the exact invocation (e.g. just e2e, go test ./package/..., npx markdownlint-cli2 path), not "run tests" or "run the suite".
Scopes: package paths, directories, or file globs (repo-relative paths in backticks).
Tests: concrete test names, files, modules, tags, or BDD scenario titles - not "all tests", "the failing tests", or "all 3 tests" without naming which three.
Code or docs: files or symbols to edit, or a clear discovery sub-step that lists them first.
Artifacts: outputs to produce (e.g. report path, migration name) when the step is not obvious from the command alone.

If the exact names are unknown at plan time, the step must say how they will be identified (e.g. "list failing tests from go test ./... output and add each as its own step in the next plan revision") - not leave a vague single step in place of that work.

Ambiguous Wording to Avoid

Steps that rely on unstated context: "Run all 3 tests", "run the new tests", "fix the handler", "update as needed".
Counts or groups without identifiers: "run every E2E", "run the integration tests" (unless the repo has a single documented target and the step names it, e.g. just integration).

Explicit Wording for Steps

Use imperative text plus identifiers: paths, commands, test IDs, or scenario names so the step is self-contained.

Core Rules

Treat requirements as the source of truth, then technical specs, then current implementation.
Before planning, read the relevant requirements, tech specs, and implementation context.
If requirements or specs are missing, ambiguous, or contradictory, stop and call out the gap.
Write the plan in markdown, using only top-level - [ ] / - [x] lines for steps and headings to group them (see Flat Checklist Only: No Nested Step Bullets).
Make the plan executable: each checkbox must be a concrete action with explicit scope, not a vague intention (see Explicit Step Wording (Required)). Prefer short, imperative step text that still names what and where, and be explicit about files, tests, commands, and artifacts. Vague phrases like "run all targeted tests" are not enough unless the plan already lists those targets by path or name.
Use BDD/TDD explicitly:
- add or update behavior specs first
- write failing tests before implementation
- implement the smallest change to make tests pass
- refactor only after tests are green
Include additional functional tests for user-facing or API-facing behavior.
Task independence: each task has its own Requirements and Specifications list, Discovery steps, and Testing, so tasks can be read and executed independently with all steps needed to complete that task.
Add validation gates after each task (within that task's Testing sub-section) and require them to pass before moving on.
Do not allow a later task to start until the current task's validation steps are complete, and include explicit hold points that say so (e.g. "do not proceed until this passes", "do not start the next task until ...").
Include Cursor Plan Frontmatter (Required) with todos mirroring every checkbox under ## Execution Plan.
Avoid filler sections and generic advice.
When updating an existing plan, preserve completed work where possible and revise only what is still pending or invalidated.

Planning Workflow

Follow these phases in the order given when producing or revising a plan.

Gather Inputs

Identify the user goal.
Identify the relevant requirement documents.
Identify the relevant technical specifications.
Identify the current code, tests, and docs that will likely change.
Identify missing information, assumptions, dependencies, and risks.

Define Scope and Constraints

Record the following:

what must change
what must not change
required parity, compatibility, or migration constraints
required test types
completion criteria

Build the Execution Sequence

Order the plan as a sequence of tasks (phases of work). Each task is self-contained and independently executable: it has its own discovery, implementation, and testing sub-sections so that the work in that task can be completed and validated without relying on later tasks.

Within each task, use this shape:

Requirements and Specifications: include in the plan a list of the canonical requirement and spec documents for this task (so executors do not need to guess).
Discovery steps: gather current implementation and context for this task (e.g. read the listed specs, inspect code and tests, identify gaps).
Red phase: add or update specs and failing tests for this task.
Green phase: implement the smallest change to make those tests pass.
Refactor phase: refine implementation without changing behavior; keep tests green.
Testing: validation gate for this task (targeted tests, lint, etc.); do not proceed until they pass.
Closeout (Task N): generate a task completion report (what was done, what passed, any deviations or notes), then mark all completed steps in the plan with - [x] as the last step in the task before starting the next task.

Add a final documentation and closeout task for cross-cutting docs and follow-up.

Add Mandatory Test Gates

The plan must explicitly require, within each task:

spec or behavior definition updates before implementation (Discovery / Red)
failing automated tests before code changes (Red)
functional test coverage when behavior is user-facing or API-facing (Red)
targeted validation in that task's Testing sub-section before moving to the next task
closeout for each task: mark completed steps with - [x] and generate a task completion report before starting the next task
final verification in the last task (or a dedicated closeout task) before the plan is complete, including a final plan completion report

Update Plans Carefully

When updating an existing plan:

read the whole current plan first
keep completed items checked unless they are now invalid
insert new steps at the correct point in sequence (within the right task and sub-section)
update validation steps if scope or task boundaries changed
ensure the revised plan still enforces task ordering and per-task validation
update YAML todos so it stays aligned with every checkbox line under ## Execution Plan

Default Plan Template

Use assets/plan-template.md unless the user asks for a different structure. Read it before drafting, and follow its task shape: every task carries its own Requirements and Specifications list, Discovery steps, Red, Green, Refactor, Testing, and Closeout, so it can be executed and validated on its own.

After drafting the body, fill in todos so each entry's content matches one checkbox line in order (same specificity; do not shorten to vague summaries). Set dependencies to chain linear steps (step N depends on step N-1) unless the user needs parallel tracks.

Quality Bar

Before finalizing a plan, verify that it:

includes valid YAML frontmatter with name, overview, and todos per Cursor Plan Frontmatter (Required)
has one todos entry per - [ ] / - [x] line under ## Execution Plan, in the same order, with ids and dependencies consistent with that sequence
uses only flat checklist lines (no nested - [ ] under another - [ ])
is detailed enough for an executor to execute without guessing
uses explicit step wording everywhere: no ambiguous shortcuts like "run all N tests" without naming which tests, files, or commands (see Explicit Step Wording (Required))
includes in each task a Task N Requirements and Specifications list so executors do not need to guess (or calls out that they still need to be identified)
includes BDD/TDD and functional testing where applicable
gives each task its own Requirements and Specifications, Discovery steps, Testing, and Closeout (task completion report, then mark completed steps as the last step) so tasks are independently executable
enforces validation within each task before the next task starts
uses checkbox steps throughout the execution section
stays concise and avoids unnecessary narrative

detailed-execution-planner

SKILL.mdskills/detailed-execution-planner/SKILL.md