Reconcile Backlog-Sweep Plan

You are a plan-state reconciler. Your job is to walk a backlog-sweep plan's state.json and plan.md, query GitHub for every initiative whose PR is already open, apply merged / deferred status transitions to both files, and ship the reconciliation as a PR on a short-lived branch.

This skill does not pick new work and does not execute initiatives. It is a bookkeeping pass that runs between PR waves.

Server discovery

This skill edits repository files and shells out to gh + git. Roslyn MCP `server_info` / `server_catalog` are unrelated — no workspace loading, no analyzer calls. If you think you need Roslyn MCP, you are in the wrong skill.

Input

$ARGUMENTS optionally names the plan directory (relative to repo root, e.g. ai_docs/plans/20260417T120000Z_backlog-sweep). If omitted, enumerate ai_docs/plans/*_backlog-sweep/, classify each as terminal vs non-terminal (terminal = completed: true AND every initiative status in {merged, obsolete, deferred} — the canonical terminal set per ~/.claude/prompts/backlog-sweep-plan.md § State machine), and select the oldest non-terminal plan (FIFO drain). This mirrors :execute Step 0b / :status — do NOT default to newest-by-name, which strands older non-terminal plans whose in-review PRs never get reconciled.

Preconditions (HARD GATES — refuse if any fail)

1. `state.json` exists at {plan-dir}/state.json. If missing, refuse: "No state.json at {path}. Is this a backlog-sweep plan directory?".
2. `plan.md` exists at {plan-dir}/plan.md. If missing, refuse.
3. `schemaVersion ∈ {2, 3, 4}` in state.json (2 = legacy /backlog-sweep:plan; 3 = legacy /backlog-sweep:prepare-extended; 4 = /backlog-sweep:prepare status-SSOT, the current default — all three valid per the canonical field contract, which states every consumer including this skill MUST accept all three). v4 plans are reconciled by delegating to the blessed writer script (the Step 1.2 v4 fast path); 2/3 plans use the manual path below. If the value is outside {2,3,4} (or missing), refuse: "Plan uses schemaVersion {n}; this skill supports 2, 3, and 4. Re-run /backlog-sweep:plan or :prepare to regenerate.".
4. `gh` CLI is on PATH (gh --version exits 0). If not, refuse: "gh CLI not available — cannot query PR state. Install gh or run Step 1b manually.".
5. `git` CLI is on PATH (git --version exits 0). If not, refuse.
6. Working tree is clean (git status --porcelain is empty) OR the only dirty paths are the two files this skill will edit (state.json + plan.md). If dirtier, refuse: "Working tree has unrelated changes — commit or stash before reconciling.".
7. `main` is the default branch and up to date with origin/main. Run git fetch origin main first; then verify main exists locally (or create it tracking origin/main).

Workflow

Step 1 — Locate plan and snapshot current state

1. Resolve the plan directory per Input above.
2. Read {plan-dir}/state.json into memory. Validate schemaVersion ∈ {2, 3, 4}.

• v4 fast path: if schemaVersion == 4 AND ~/.claude/scripts/bsweep-state.mjs exists, delegate the whole reconcile to node ~/.claude/scripts/bsweep-state.mjs reconcile --plan {plan-dir} (one batched gh pr list, the in-review MERGED→merged / CLOSED→deferred transitions, plan.md status-table regen), then proceed to Step 4 (create the short-lived branch), Step 6 (commit the script's edits), Step 7 (push + open PR), and Step 8 (merge) — skipping the manual candidate-query/preview Steps 2–3 and the hand-edit Step 5, which the script subsumes. The manual per-initiative steps below are the fallback when the script is absent (e.g. an external plugin consumer) or the plan is pre-v4.

1. Read {plan-dir}/plan.md into memory.
2. Build the reconciliation candidate list: every initiative whose status is in-review or in-progress AND whose prUrl is non-null. Skip pending, merged, obsolete, deferred, and paused-usage-limit (the last is a mid-flight recovery state with no mergeable PR — resume it via /backlog-sweep:execute initiative=<id>, don't reconcile it here).
3. If the candidate list is empty, report "Nothing to reconcile — no in-review/in-progress initiatives with a PR URL." and exit without creating a branch or PR.

Step 2 — Query GitHub for each candidate

For each candidate, run:

gh pr view <prUrl> --json number,state,mergedAt,mergeCommit,closedAt

Parse the JSON. Tolerate a single-retry on transient gh failure (network / rate limit). If gh pr view fails twice, record the initiative id + error in a failure list; do NOT flip its status; continue with the rest.

Compute the intended transition per the rules from ~/.claude/prompts/backlog-sweep-execute.md § Step 2 (in-review reconcile) and the canonical field contract in ~/.claude/prompts/backlog-sweep-plan.md § Canonical state.json field contract:

Record every transition you plan to make in a structured diff report (initiative id, old status → new status, PR number, merged/closed timestamp). Do not apply yet.

Step 3 — Dry-run preview

Print the full transition plan to the user:

Reconciliation plan for {plan-dir}:
  {initiative-id-1}: in-review → merged (PR #{n}, merged {ISO})
  {initiative-id-2}: in-progress → deferred (PR #{n} closed without merge)
  {initiative-id-3}: in-review → (no change, PR still OPEN)
  ...
Skipped / errored:
  {initiative-id-X}: gh pr view failed — {error}
Total transitions: {k} of {candidate-count} candidates.

If k == 0 after filtering no-change + errored rows, report "No status transitions needed — every queried PR is still OPEN." and exit without creating a branch or PR.

Step 4 — Create a short-lived branch

main is branch-protected in this repo; commits must land via PR. Pick a branch name:

chore/reconcile-{plan-timestamp}-{YYYYMMDDHHMMSS}

where {plan-timestamp} is the 20260417T120000Z-style prefix of the plan directory name and {YYYYMMDDHHMMSS} is UTC now. Example: chore/reconcile-20260417T120000Z-20260417163015.

git switch -c {branch-name} main

Step 5 — Apply edits to state.json and plan.md

For each in-flight transition:

1. Update state.json:

• Set initiatives[i].status to the new value.
• For merged: set mergedAt to the GitHub-reported ISO string (not "now"). Confirm prUrl is non-null — it must be (the Step 1.4 candidate filter requires it; per the canonical required-when-merged contract a merged record MUST carry both prUrl and mergedAt). If prUrl is somehow null, fetch it via gh pr view <n> --json url and set it before writing.
• For deferred: append the "PR #<n> closed without merge — manual triage required" note to notes (separator " | " if notes already non-empty).
• Leave other fields (branch, worktreePath, rowsClosedCount, …) untouched — but NEVER null out prUrl on a merged record.

1. Update plan.md's Status row for this initiative (legacy 2/3 plans only — v4 plans have NO per-stanza Status row; the Step 1.2 v4 fast path already regenerated the generated status table via the script). The initiative's stanza in plan.md is a markdown table under its ### {order}. \{initiative-id}\ — {title} heading (canonical shape: ~/.claude/prompts/backlog-sweep-plan.md Step 8), with a | Status | {value} | row. Rewrite ONLY that row's value cell:

• merged → | Status | merged (PR #{n}, {YYYY-MM-DD from mergedAt}) |
• deferred → | Status | deferred (PR #{n} closed; see notes) |
• Do not touch any other table row (Order / Correctness class / Schedule hint / Estimated context / CHANGELOG category).

Write both files back. Keep JSON formatting stable (2-space indent, trailing newline if the original had one).

Step 6 — Commit

Stage the two files explicitly (never git add . or git add -A):

git add {plan-dir}/state.json {plan-dir}/plan.md

Commit with a descriptive message citing the transitions. Template:

chore(plan): reconcile {plan-timestamp} state — {merged-count} merged, {deferred-count} deferred

In-review reconciliation for backlog-sweep plan {plan-timestamp}.

Transitions:
  - {id}: in-review → merged (PR #{n})
  - {id}: in-progress → deferred (PR #{n} closed)
  ...

Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]>

Use a HEREDOC for the -m payload so multi-line formatting survives.

Step 7 — Push and open PR

git push -u origin {branch-name}
gh pr create --title "chore(plan): reconcile {plan-timestamp} state" \
             --body "$(cat <<'EOF'
## Summary
- In-review reconciliation for `ai_docs/plans/{plan-dir}/`.
- {merged-count} initiatives transitioned to `merged`, {deferred-count} to `deferred`.
- Source of truth: `gh pr view` per PR at reconciliation time.

## Transitions
{bulleted list of id: old → new (PR #n, timestamp)}

## Test plan
- [x] `state.json` `schemaVersion` unchanged (2, 3, or 4)
- [x] Only status / mergedAt / notes fields changed per initiative
- [x] `plan.md` Status rows mirror state.json
- [x] No unrelated files modified
EOF
)"

Step 8 — Merge

Default: squash-merge with branch deletion.

gh pr merge <num> --squash --delete-branch

If the merge is rejected (most likely: branch needs rebase onto newer main because another PR landed during the window):

1. git fetch origin main
2. git rebase origin/main
3. Resolve any conflicts in state.json / plan.md — prefer last-writer-wins on the same initiative row, keep both when rows differ.
4. git push --force-with-lease (NOT plain --force).
5. Retry gh pr merge <num> --squash --delete-branch.

Step 9 — Report

Emit a final structured summary:

Reconciliation complete.
  Plan: {plan-dir}
  Branch: {branch-name} (deleted)
  PR: {url} (merged as <sha>)
  Transitions applied:
    merged: {k}
    deferred: {j}
  Skipped (still OPEN): {o}
  Errored (gh pr view failed): {e} — {ids}
  Post-reconciliation status buckets: {pending-count} pending, {in-review-count} in-review, {merged-count} merged, {obsolete-count} obsolete, {deferred-count} deferred.

If all initiatives are now terminal (merged / obsolete / deferred), additionally note: "Plan fully shipped — run /backlog-sweep:execute Step 2 completion (marks completed: true + adds Refs entry) or prompt the user." — do NOT do that completion step yourself; that is the executor's job.

Worktree teardown discipline (Windows). After this skill completes, the orchestrator typically removes worktrees for merged initiatives via git worktree remove --force .worktrees/<id>. On Windows, VBCSCompiler.exe and MSBuild.exe build-server processes hold file-system locks on the worktree's bin/obj directories — git worktree remove will fail with Permission denied until those locks are released. The fix: call workspace_close(workspaceId: <id>, drainProcesses: true) for each loaded workspace BEFORE calling git worktree remove. The drainProcesses: true flag runs dotnet build-server shutdown after session disposal, which releases all out-of-process build-server locks. This step is a no-op when no build-server is running, so it is always safe to prepend.

Refusal cases (explicit)

• Plan directory missing / wrong shape → refuse per Preconditions 1-2.
• `schemaVersion ∉ {2, 3, 4}` → refuse per Precondition 3 with re-plan instruction. (v4 is supported via the Step 1.2 script delegation; only values outside {2,3,4} are refused.)
• `gh` / `git` missing → refuse per Preconditions 4-5.
• Dirty working tree with unrelated paths → refuse per Precondition 6.
• `main` diverged in a way that requires manual merge during Step 8 rebase and the rebase surfaces conflicts outside state.json / plan.md → stop and hand off to the user; do not force-push away another contributor's edits.
• `gh pr view` fails for >50% of candidates → stop before Step 4; report the failure rate and suggest re-running after the transient issue resolves.

Example output

Input: /reconcile-backlog-sweep-plan ai_docs/plans/20260417T120000Z_backlog-sweep

Reconciliation plan for ai_docs/plans/20260417T120000Z_backlog-sweep:
  mcp-connection-session-resilience: in-review → merged (PR #218, merged 2026-04-17T13:05:19Z)
  mcp-server-surface-catalog-parity-generator: in-review → merged (PR #220, merged 2026-04-17T13:50:00Z)
  observation-rows-obsoletion-sweep: in-review → merged (PR #221, merged 2026-04-17T15:35:00Z)
Total transitions: 3 of 3 candidates.

Proceeding to Step 4 (branch) → Step 8 (merge).

Branch: chore/reconcile-20260417T120000Z-20260417163015
Commit: a1b2c3d chore(plan): reconcile 20260417T120000Z state — 3 merged, 0 deferred
PR #223 opened, merged as f9e8d7c6.

Reconciliation complete.
  Post-reconciliation status buckets: 34 pending, 0 in-review, 3 merged, 0 obsolete, 0 deferred.

Why not commit directly on main

The executor prompt historically said "commit both edits on main". This repo has main branch protection enabled (see repo settings + recent PR history showing every merge goes through PR review). A direct push to main will be rejected at the server with remote rejected … protected branch hook declined. The short-lived branch + squash-merge pattern preserves the executor's intent (reconciliation lands on main) while respecting the branch-protection gate. When squash-merge lands, the commit message on main is identical to a direct commit would have been.

Distinct from related skills

• `/ship`: ships the working branch's PR-scope changes. This skill runs on main after /ship-style PRs have merged, to mirror GitHub-observed state back into the plan files. Do not confuse: /ship runs per initiative; /reconcile-backlog-sweep-plan runs between initiative waves.
• `~/.claude/prompts/backlog-sweep-execute.md` Step 2 (in-review reconcile): the prompt logic this skill automates. If the user says "run the in-review reconcile" (legacy name: "Step 1b") they want this skill.
• `:execute` Step 2 completion (mark `completed: true`, add Refs row): deliberately NOT automated here — that edit also touches ai_docs/backlog.md's Refs table, which is an executor concern, not a reconciliation concern.