Reconcile Remediation Plan

You are a plan-state reconciler. Your job is to walk a remediation 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. The installed name /reconcile-backlog-sweep-plan is retained only for compatibility.

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-remediate). The _backlog-sweep directory suffix is a historical compatibility label. If omitted, enumerate the union of ai_docs/plans/*_backlog-remediate/ and legacy ai_docs/plans/*_backlog-sweep/ directories. Classify every candidate under one terminal rule (terminal = completed: true AND every initiative status in {merged, obsolete, deferred} — the canonical terminal set in ~/.claude/prompts/backlog-remediate-rules.md), then select the oldest non-terminal plan across the combined set (FIFO drain). This mirrors /backlog-remediate plan selection — do NOT prefer one suffix or default to newest-by-name, either of which can strand an older non-terminal plan 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 remediation plan directory?".
2. `plan.md` exists at {plan-dir}/plan.md. If missing, refuse.
3. `schemaVersion ∈ {2, 3, 4}` in state.json (2 and 3 are legacy schemas produced by the retired /backlog-sweep:plan and /backlog-sweep:prepare routes; 4 is the current default — all three remain valid per the canonical field contract). 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-remediate 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-remediate 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 in-review reconciliation and canonical state contract in ~/.claude/prompts/backlog-remediate.md and ~/.claude/prompts/backlog-remediate-rules.md:

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 (legacy shape retained by ~/.claude/prompts/backlog-remediate-rules.md), 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 remediation 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-remediate 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 cleanup handoff

• Normal initiative worktrees: delegate teardown to canonical /ship --land=<pr> after verifying the PR is merged. Reconciliation never removes worktrees itself.
• Refuse dirty worktrees: preserve modified, untracked, and ignored residue. Report the exact retained path and reason for operator review; do not force removal or discard files to obtain a clean result.
• Windows locks: close only the matching Roslyn workspace before shipping cleanup. Use workspace_close(workspaceId: <id>, drainProcesses: true) when that session owns the build processes; do not terminate unrelated sessions or assume a process-wide build-server shutdown is harmless.
• A cleanup failure remains incomplete. Preserve SHIP_STATUS=landed-cleanup-failed after a confirmed merge until canonical shipping proves cleanup succeeded.

Disposable audit exception. An audit may explicitly create a throwaway worktree whose mutations are authorized to be discarded under that audit's own lifecycle policy. That exception belongs to the audit workflow; it never applies to normal initiative worktrees or authorizes this reconciler to remove them.

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

Compatibility-name example using the historical directory suffix: /reconcile-backlog-sweep-plan ai_docs/plans/20260417T120000Z_backlog-sweep

Remediation-plan reconciliation 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; the compatibility-named /reconcile-backlog-sweep-plan runs between initiative waves.
• `/backlog-remediate` 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.
• `/backlog-remediate` 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.