prepare-execution-plan

name	prepare-execution-plan
description	Decompose a high-level delivery plan into a precise, file-level execution sequence with explicit ordering, edge cases, and test checkpoints. Activate after delivery-high-level-plan for complex or multi-phase Stories before implementation begins.
license	ELv2
compatibility	Works with any filesystem-based AI coding agent
metadata	{"author":"gaai-framework","version":"1.0","category":"delivery","track":"delivery","id":"SKILL-DEL-006","updated_at":"2026-02-26T00:00:00.000Z","status":"stable"}
inputs	["contexts/artefacts/plans/*.plan.md (from delivery-high-level-plan)","contexts/artefacts/stories/** (validated)","contexts/rules/**","memory_context_bundle","codebase_map (optional, from codebase-scan)"]
outputs	["contexts/artefacts/plans/{id}.execution-plan.md"]

Prepare Execution Plan

Purpose / When to Activate

Activate after delivery-high-level-plan when the Story meets at least one of:

• Touches more than 3 files or modules
• Has cross-cutting concerns (shared state, API contracts, migrations)
• Requires a specific implementation order to avoid breakage
• Contains edge cases or error paths that are non-trivial to sequence
• Has a history of QA failures on similar work

For simple Stories (1-2 files, clear criteria, no order constraints), delivery-high-level-plan output is sufficient — skip this skill.

---

Process

CRITICAL — Anti-Collision Guard (MUST execute before writing any output file): Before writing contexts/artefacts/plans/{id}.execution-plan.md (or {id}.plan-blocked.md), check if the target file already exists on disk:

• If it does NOT exist → proceed normally.
• If it DOES exist → read the existing file first. Then decide:
  • If the existing content is from a different entity (different story ID, different epic) → STOP immediately, surface the ID collision to the human, do not proceed.
  • If the existing content is from the same entity and an update is warranted → proceed, but preserve any human edits or prior findings that remain relevant. Treat this as an update, not a replacement.
  • If the existing content is identical or still valid → skip writing, report "no changes needed". This guard prevents the silent data loss incident of 2026-03-17 where concurrent sessions overwrote story files.

Phase 0 — Required Skills Contract Resolution

Execute this phase FIRST, before any codebase mapping.

0. Read the Story frontmatter required_skills field.
   • If required_skills is absent or empty: record that no custom skills are contracted. The plan MUST NOT include any step that invokes a custom skill. Proceed directly to Phase 1.
   • If required_skills contains one or more entries: for each entry X: a. Resolve skill X: check that a SKILL.md file exists for X in the skill catalog (.gaai/core/skills/** or .gaai/project/skills/**).
     • If X cannot be resolved → STOP. Write {id}.plan-blocked.md at the plans output path with: PLAN BLOCKED: required_skills entry "${X}" cannot be resolved — no matching SKILL.md found. Check the skill name and that the skill file exists. Exit non-zero. Do not proceed. b. Identify the bound output AC co-declared with X in the story. (A entry without a co-declared output AC is rejected by before the plan runs — treat its absence here as a STOP condition identical to an unresolvable skill.) c. Emit an explicit plan step: "Invoke skill X [path to SKILL.md] — satisfies bound output AC: [AC text]".