Plan Merge

---
name: plan-merge
description: Merge two overlapping plan documents into a single coherent plan. Identifies shared goals at different fidelity, resolves sequencing tensions, picks a spine, deletes subsumed phases, and archives originals. Use when two plans target related work and need to be reconciled before execution (e.g., a capability plan plus an infrastructure plan that together deliver the same feature).
user-invocable: true
---

# Plan Merge

Merge two (or more) plan documents into one. The output is a single plan
where overlapping goals are resolved, phases are re-sequenced into a
coherent order, and the originals are archived — not deleted — so their
context remains inspectable.

This skill is **conversational**. It does not auto-merge. It surfaces the
decisions a human has to make (which plan is the spine, how to resolve
overlaps, how to order dependencies) and then writes the merged plan only
after those decisions are settled.

## When to use

- Two plans in `documentation/plans/` target related work and the team
  hasn't decided which one to execute.
- One plan describes a *capability* (e.g. "add feature X") and another
  describes the *infrastructure* that feature needs. They overlap at the
  seam and need reconciliation.
- A plan's phases reference work that is separately planned elsewhere.
- An old plan is partially superseded by a newer one and they need to
  be unified rather than left to rot in parallel.

Do NOT use this skill:

- To merge a plan with its own code — that's `/repo-update` or direct editing.
- To refine a single plan — that's `/plan-review`.
- To split a plan into smaller phases — write a new plan.

## Inputs

- Paths to two or more plan files (ask if not provided).
- Optionally, the target path for the merged plan. Default:
  `documentation/plans/<descriptive-name>-master-plan.md`.

## Process

### 1. Read both plans in full

Do not skim. The overlap that matters is rarely in the introduction — it
hides in phase-level details, schemas, contracts, and kill criteria.

### 2. Surface the overlap

For each plan, extract **all five** of the following fields. The output
MUST include every field for every plan — if a field is empty in the
source, write `(none found)` explicitly rather than omitting the line.
Dropping any of the five fields makes Step 2 invalid and Step 4's spine
proposal unsound.

- **Vision / goal** — what problem does it solve?
- **Phase list with one-line summaries**
- **Data contracts** (DB schemas, file formats, APIs)
- **External dependencies** (branches, PRs, other plans, skills)
- **Kill criteria and rollbacks**

Render the extraction using this exact template, once per plan (do NOT
collapse fields, do NOT drop the External dependencies or Kill criteria
lines even if they feel redundant):

```text
#### Plan: <name>
- Vision / goal: <...>
- Phase list: <...>
- Data contracts: <...>
- External dependencies: <...>
- Kill criteria and rollbacks: <...>
```

Then compare: where do the two plans touch the same concept?

Each overlap MUST be classified by exactly one of these four catalog
patterns, prefixed verbatim as `[PATTERN: <name>]` in lowercase:

- `[PATTERN: same-goal-different-fidelity]` — Plan A describes a
  feature abstractly; Plan B describes the infrastructure that
  implements it concretely. (Most common case.)
- `[PATTERN: same-data-different-schema]` — Both plans add storage for
  related information in different formats (SQLite vs JSONL vs JSON).
- `[PATTERN: implicit-prerequisites]` — Plan A's Phase N requires
  infrastructure that Plan B's Phase M builds.
- `[PATTERN: conflicting-invariants]` — Plan A declares "append-only
  X"; Plan B implicitly violates that invariant.

Do not invent new pattern names — if a detected overlap doesn't fit any
of the four, pick the closest match and note the imperfect fit in
parentheses after the bullet. Ad-hoc phrasing without a `[PATTERN: ...]`
tag is a defect.

### 3. Check for self-inconsistency

A plan is self-inconsistent if its own later phases would break its
earlier phases. This is easy to miss when reading linearly. Look for
this pattern: **does plan A's later phase invalidate an assumption its
own earlier phase makes?** When you find one, name BOTH the offending
later phase AND the earlier phase it breaks.

### 4. Propose a spine

One plan usually reads as the *substrate* (infrastructure, foundational)
and the other as the *capability* (features built on top). The substrate
is the spine; the capability plan's phases slot in as work that happens
inside the substrate.

State the proposed spine explicitly, with justification. Be direct: "I
propose Plan B as the spine because it's the substrate; Plan A's phases
become per-substrate work."

Alternatives worth calling out:

- Capability-as-spine (when the infrastructure is lightweight and
  exists mainly to support one capability).
- Neither-as-spine (when both plans are equal partners — then the merged
  plan has two tracks that run in parallel and synchronize at named
  points).

### 5. Ask the hard questions before writing

Do NOT write the merged plan body yet — phase contents, decision graph,
baseline, kill criteria, etc. stay unwritten until the user has answered
the questions below.

BEFORE listing the questions, the first-turn response MUST preview the
structure of the eventual merged plan so the user can see what they're
signing up for. Render this preview inline in the response, verbatim, in
this order:

> Once you've answered the questions below, I will write the merged
> plan to the target path with these fifteen canonical sections in this
> order:
>
> 1. **Source** — names the two archived originals and links to their
>    paths (per Step 6, section 1: this is how readers trace decisions
>    back to the un-merged inputs).
> 2. **Vision** — single unified goal statement.
> 3. **Principles** — union of both plans' principles, deduplicated;
>    conflicts flagged with resolution.
> 4. **Glossary** — union of terms with per-version / per-substrate
>    scoping where invariants changed.
> 5. **How to read this plan** — fields every phase has.
> 6. **Execution mode** — human-led vs autonomous, branching strategy.
> 7. **Track structure** — named tracks (Validation, Infrastructure,
>    Capability, Operational) so phases group without forcing one
>    linear order.
> 8. **Decision graph** — ASCII diagram of gate dependencies.
> 9. **Baseline** — current state as of merge date.
> 10. **Phases** — one section per phase, ordered by track then
>     sequence, each with canonical fields (goal, prerequisites, scope,
>     tests, effort, validation, gate, kill criterion, rollback).
> 11. **Compute target** (if relevant).
> 12. **Time budget** — combined table.
> 13. **What's NOT in this plan** — union of exclusions PLUS
>     explicitly-subsumed phases from the merge.
> 14. **Tracking** — how phases become issues, which milestone.
> 15. **Plan history** — append-only log; first entry documents the
>     merge itself (what was dropped, subsumed, decided).

The preview is structural only — do not populate any section body
yet. Then ask the user:

1. **Spine choice.** Confirm or redirect.
2. **Subsumption decisions.** For each overlap, propose one of:
   - Delete phase from plan X (subsumed by phase Y from plan Z)
   - Merge phases X and Y into a combined phase
   - Keep both, with explicit dependency between them
3. **Invariant resolutions.** If plans have conflicting invariants,
   which one wins, and what's the escape hatch for the losing side?
4. **Data format choices.** When both plans specify storage, which
   format survives? (JSONL vs SQLite vs JSON — size of dataset,
   expected access pattern, tooling.)
5. **Sequencing constraints.** Any phase from plan X that must happen
   before/after a specific phase from plan Y?
6. **Target file name.** Default `<topic>-master-plan.md`; confirm.
7. **Archive vs delete originals.** Default archive. Confirm.

Let the user answer all questions before proceeding.

### 6. Write the merged plan

Structure the output with these sections in this order:

1. **Source** — name the two archived originals, link to their paths.
2. **Vision** — single unified goal statement.
3. **Principles** — union of both plans' principles, deduplicated.
   Flag any principles that conflict and cite the resolution.
4. **Glossary** — union of both plans' terms, with per-version /
   per-substrate scoping noted where invariants changed.
5. **How to read this plan** — fields every phase has.
6. **Execution mode** — human-led vs autonomous, branching strategy.
7. **Track structure** — name the tracks (e.g., Validation,
   Infrastructure, Capability, Operational). Shows the reader how phases
   group without forcing a single linear order.
8. **Decision graph** — ASCII diagram of gate dependencies.
9. **Baseline** — current state as of merge date.
10. **Phases** — one section per phase, ordered by track then sequence.
    Each has the canonical fields (goal, prerequisites, scope, tests,
    effort, validation, gate, kill criterion, rollback).
11. **Compute target** (if relevant).
12. **Time budget** — combined table.
13. **What's NOT in this plan** — union of both plans' exclusions, PLUS
    the explicitly-subsumed phases from the merge ("checkpoint-only
    opponent pools — subsumed by ..."). This is important: future
    readers need to see what was considered and rejected.
14. **Tracking** — how phases become issues, which milestone.
15. **Plan history** — append-only log. First entry documents the
    merge itself: what was dropped, what was subsumed, what decisions
    were made.

### 7. Archive the originals

Move originals to `documentation/archived/` (or the project's archive
convention). Do NOT delete — the merged plan's "Source" section must
link to them, and the plan history entry needs to stay verifiable.

FIRST run `git status` against each input plan path and SHOW the output
in your response so the reader can see which command applies. Then,
per-file: if it appears as tracked in `git status`, use `git mv`; if it
appears as untracked, use plain `mv`. Never skip the `git status` check
or hand-wave it as "both are tracked" — show the check, then choose the
command.

### 8. Update any external references

- `MEMORY.md` entries referencing the old plans — update to the merged
  plan's path.
- GitHub issues / milestones — note in conversation that `/repo-sync`
  may be needed to re-cut issues against the merged plan.
- `CLAUDE.md` or `AGENTS.md` references — update if they name the old plans.

Do not silently rewrite memories or docs — list what needs updating and
confirm with the user before editing non-plan files.

## Output format

After the merge is complete, produce a short summary:

- **Merged plan written to:** `<path>`
- **Originals archived to:** `<path1>`, `<path2>`
- **Phases dropped:** `<phase>` — reason
- **Phases merged:** `<phase A> + <phase B>` → `<new phase>` — reason
- **Invariants changed:** `<old rule>` → `<new rule>` — reason
- **Open follow-ups:** references needing update (memories, issues, docs)

Keep this summary under 200 words. The plan document itself is the
deliverable; the summary is just the handoff.

## Anti-patterns

- **Silent-concatenation merge.** Copying both plans into one file with
  a "Plan A" and "Plan B" section header is not a merge — it's a
  staple. A real merge identifies overlap and makes a choice.
- **Auto-merge without questions.** The whole value is forcing the
  subsumption and sequencing decisions to be explicit. If you skip the
  questions, the output is a larger plan with the same inconsistencies
  as the inputs.
- **Deleting the originals.** Archive, always. The merged plan's
  history log refers to the originals, and readers may need to see the
  un-merged version to understand a decision.
- **Ignoring self-inconsistency.** If Plan A's Phase N breaks its own
  Phase K, note it in the merge rationale. Don't just replicate the
  contradiction.
- **Merging without reading fully.** Overlap hides in phase-level
  schemas and kill criteria, not intros. Skim and you miss the real
  decisions.

## Relation to other skills

- `/plan-review` — review a single plan for gaps. Complementary; run
  before or after `/plan-merge`.
- `/plan-init` — start a new plan from scratch. Use when there's
  nothing to merge yet.
- `/plan-feature` — scope a feature plan inside an existing project.
  Use when one of the "plans" you'd merge is actually just a feature
  inside a larger plan.
- `/repo-sync` — run after the merged plan is written to re-cut GitHub
  issues against the new phase structure.
- `/plan-wrap` — run on the merged plan to confirm a fresh model
  can act on it without prior context.