# Prepare Execution Plan

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

- Skill: `fr-e-d/prepare-execution-plan` (Agent Skill)
- Install (CLI): `npx skillmds@latest add fr-e-d/prepare-execution-plan`
- Raw SKILL.md: https://api.skillmd.com/api/skills/fr-e-d/prepare-execution-plan/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: ELv2
- Author: Fr-e-d (https://skillmd.com/u/fr-e-d)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/fr-e-d/prepare-execution-plan

---


# 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 — Frontmatter Contract (MUST apply to every file this skill writes):**
Read the plan template at `contexts/artefacts/plans/_template.plan.md` and open every
output with its YAML frontmatter block. Both `type: artefact` and `id:` are required —
artefact validation reads those two fields and rejects a file that lacks either. The
requirement applies equally to `{id}.execution-plan.md` and `{id}.plan-blocked.md`;
both live under `contexts/artefacts/plans/` and are validated identically.
When updating an existing file, never overwrite frontmatter that is already there —
add only what is missing.
- **Rationale:** this skill previously documented its output as a markdown body starting
  at the `#` heading, with no frontmatter anywhere in its instructions, while the template
  it never told anyone to read did carry it. Generated plans therefore failed artefact
  validation from the start, and because sibling skills (story generation) do instruct
  reading their template, the gap showed up as plans being the one artefact class that
  failed en masse. Fixing the backlog of files without fixing this instruction would
  simply regenerate the defect on the next delivery.

**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 `required_skills` entry without a co-declared output AC is rejected by
        `validate-artefacts` 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]".

**Autonomy-never-originates invariant (hard constraint, no exceptions):** the plan MUST
contain a contracted skill step for each `required_skills` entry and MUST NOT contain any
custom skill step not present in `required_skills`. The planning agent may not discover,
invent, or suggest a custom skill not declared by the human in Discovery.

### Phase 1 — Codebase Mapping

1. Identify all files that will be created or modified
2. Map dependencies between those files (who imports whom)
3. Identify shared state, interfaces, or contracts that must remain stable across changes
4. Flag any files with existing tests that may be affected

### Phase 2 — Implementation Sequence

4. Order changes to minimize broken states at each intermediate step:
   - Define interfaces/types first (if applicable)
   - Implement lowest-dependency modules first
   - Update consumers after providers are stable
   - Database/schema changes before logic changes
5. Mark explicit checkpoints: points where partial work is testable and safe to commit
6. Identify rollback boundaries: the last safe state before each risky change

### Phase 3 — Edge Cases and Error Paths

7. For each acceptance criterion, enumerate:
   - Happy path behavior (must pass QA)
   - Boundary conditions (empty, null, max values)
   - Error paths (what should fail and how)
   - Concurrency or timing concerns (if applicable)
8. Map each edge case to an explicit test checkpoint

### Phase 4 — Test Sequence

9. Define test order aligned with implementation order:
   - Unit tests for each module (written alongside implementation)
   - Integration checkpoints where cross-module behavior is verified
   - Acceptance criteria tests (the QA gate inputs)
10. Flag which tests must pass before proceeding to the next implementation step

### Phase 5 — Risk Register

11. Surface any remaining ambiguities or risks:
    - Acceptance criteria that are still partially ambiguous
    - Files where blast radius is uncertain
    - External dependencies or APIs that cannot be tested locally
12. For each risk: proposed mitigation or escalation condition

### Phase 6 — Consistency Gate

13. Before finalizing: if the Story references multiple artefacts (Epic, PRD, prior decisions), flag any contradictions found between the plan and those artefacts. Record them in the Risk Register. **Do not write the plan artefact if contradictions exist** — write a `{id}.plan-blocked.md` instead with the specific inconsistencies listed. The Planning Sub-Agent (not this skill) is responsible for invoking `consistency-check` before this skill runs.

---

## Outputs

```markdown
---
type: artefact
artefact_type: execution-plan
id: {Story ID}
track: delivery
related_backlog_id: {Story ID}
created_at: {YYYY-MM-DD}
updated_at: {YYYY-MM-DD}
---

# Execution Plan — {Story ID}: {Story Title}

## Implementation Sequence

| Step | Action | Files | Checkpoint |
|------|--------|-------|------------|
| 1 | {action} | {files} | {test or review gate} |
| 2 | {action} | {files} | {test or review gate} |

## Edge Cases

### {Acceptance Criterion 1}
- Happy path: {behavior}
- Boundary: {condition → expected behavior}
- Error path: {condition → expected behavior}

## Test Checkpoints

1. After step N: {what must pass}
2. After step M: {what must pass}
3. Final QA gate: all acceptance criteria pass

## Risk Register

| Risk | Severity | Mitigation |
|------|----------|------------|
| {risk} | high/medium/low | {action} |

## Rollback Boundaries

- Safe state after step N: {what is stable}
- Full rollback point: {last known good state}
```

Saves to `contexts/artefacts/plans/{id}.execution-plan.md`.

---

## Quality Checks

- The output opens with a YAML frontmatter block carrying both `type: artefact` and `id:` — a file missing either is rejected by artefact validation
- Every acceptance criterion maps to at least one implementation step and one test checkpoint
- Implementation sequence has no circular dependencies
- Every risky step has an explicit rollback boundary
- Edge cases cover: happy path, at least one boundary, at least one error path
- No ambiguity remains in the implementation sequence — all files are named

---

## Non-Goals

This skill must NOT:
- Write any code
- Modify the Story's acceptance criteria or scope
- Make architectural decisions not already implied by the high-level plan
- Produce test code (only test checkpoints and assertions to verify)
- Introduce any custom skill step not explicitly contracted via `required_skills` in the story frontmatter

**A precise execution plan makes implementation mechanical. Mechanical is auditable. Auditable is governed.**