---
name: merge-plan
path: [.git, .jj]
description: "Use when planning or performing a pull, sync, merge, or rebase with upstream, especially in dirty repositories with conflicts, submodules, or worktrees."
---

# Merge Plan

Synchronize local work with upstream safely.

## Contract

- A request to make a plan authorizes inspection only.
- A request to pull, sync, merge, or rebase authorizes safe, reversible local execution.
- Fetch only the required upstream state. Never push.
- Preserve all local work. Unknown disposition blocks execution.
- Decide obvious mechanics and conflict outcomes autonomously.
- When intent, history, or a lossless path is unclear, ask one blocker at a time with evidence, consequences, and a recommendation; continue after the answer.
- Use generic concepts in reasoning and reports. Use native terminology only for exact evidence or actions.

Read [nested repository risks](references/nested-repositories.md) when submodules, nested repositories, or linked workspaces are present.

## Workflow

1. **Resolve intent**
   - Distinguish the configured tracking upstream from an integration target.
   - Explicit target wins. A plain pull uses the configured tracking upstream.
   - Derive integration strategy from explicit intent, repository policy, then effective configuration. Ask if still ambiguous.

2. **Inspect before changing**
   - Discover the repository, related workspaces, and recursive submodules.
   - Read instructions for every affected scope.
   - Inspect active operations, conflicts, locks, workspace collisions, local work, recovery points, local history, and divergence.
   - Refresh only the required target state.

3. **Design the integration**
   - Partition dirty work into logical chunks: intent first, dependency cohesion second, conflict isolation third.
   - Prefer coherent checkpoint commits. Recommend a temporary snapshot only when work cannot sensibly be committed.
   - Compare local and incoming intent. Forecast overlapping paths and semantic conflicts.
   - Order repositories and chunks by dependency.
   - Plan recovery, verification, and recovery-point cleanup.

4. **Resolve blockers**
   - Resolve evident choices without interruption.
   - Ask only when plausible outcomes differ semantically or no lossless route is clear.
   - Tests validate a resolution; they do not decide intent.

5. **Act when authorized**
   - Create the planned recovery points and dirty-work snapshots.
   - Apply checkpoint chunks and integrate in dependency order.
   - Resolve obvious conflicts, verify them, and continue.
   - Stop only for a blocker or unsafe state. Never push.

6. **Verify and finish**
   - Run structural checks, targeted checks for each resolution, then repository-prescribed checks.
   - Repair clear integration mistakes. Report unrelated or pre-existing failures without expanding scope.
   - Keep rollback references until every repository matches the plan, local work is accounted for, verification passes, and the result is acknowledged.
   - Before cleanup, check final state once more.

## Output

Stay terse. Expand only blockers and predicted conflicts.

1. Verdict
2. Blockers, when present
3. Repository graph
4. Dirty-work chunks
5. Conflict forecast
6. Ordered actions
7. Verification and rollback

A plan is complete when action requires following it, not redesigning intent, preservation, ordering, resolution, verification, or rollback.