/reconcile

name: reconcile
user-invocable: true
argument-hint: "[--dry-run]"
tags: [learning, rules, intelligence, meta]
model: sonnet
model-preference: sonnet
model-preference-codex: gpt-5.4-mini
model-preference-cursor: claude-sonnet-4-6
args-schema:
  - flag: --dry-run
    description: "Print proposals without writing anything or rendering the approval AUQ"
description: >
  Use this skill when the user wants to reconcile learnings into rules, run /reconcile, propose
  rules from learnings, turn learnings into .claude/rules/ entries, or review what rules would be
  generated from current session learnings. On-demand version of session-end Phase 3.6.8.

> **Platform Note:** State files use the platform's native directory: `.claude/` (Claude Code), `.codex/` (Codex CLI), or `.cursor/` (Cursor IDE). Shared metrics live in `.orchestrator/metrics/`. See `skills/_shared/platform-tools.md`.

Reconcile Skill

Invocation

The user invoked `/reconcile` with arguments: **$ARGUMENTS** — parsed in Phase 1.3 below.

• `/reconcile` — full approval flow: engine → AUQ → write approved rules.
• `/reconcile --dry-run` — print proposals and rejections without writing anything or rendering the AUQ prompt.

**Engine seams used:** `runReconcile` (engine.mjs) · `writeApprovedRules` (writer.mjs) · `reconcile` config block · `.claude/rules/` write target.

On-demand version of the session-end Phase 3.6.8 reconciliation flow. Turns eligible learnings from `.orchestrator/metrics/learnings.jsonl` into proposed `.claude/rules/<slug>.md` entries, presenting each batch of 4 to the coordinator via AUQ multiSelect for operator approval before any file is written. Advisory-only — rules are NEVER auto-applied.

Posture Contract (load-bearing — read before executing)

• **Advisory-only.** No rule is ever written without explicit operator approval via AUQ.

The AUQ multiSelect is the mandatory gate; there is no bypass.

• **Never-always-on invariant.** The reconcile engine's emitter (`emitter.mjs`) throws

on any eligible learning that would produce an `alwaysApply: true` rule — the engine structurally cannot emit always-on rules. This invariant is enforced upstream, not by this skill.

• **Engine never writes `.claude/rules/`.** `runReconcile` computes proposals and records

them in the idempotency sidecar only. The only module that writes `.claude/rules/` is `writer.mjs`, and only AFTER the operator approves proposals via AUQ.

• **The candidate store belongs to `mergeCandidates` — nothing else writes it.**

`.orchestrator/runtime/reconcile-candidates.jsonl` is a mutable work-queue whose only sanctioned writer is `mergeCandidates` (`scripts/lib/reconcile/idempotency.mjs`); it is not a scratch pad, and no report, analysis run, or agent may append to it by hand. A hand-written record there corrupts downstream readers — the session-start reconcile nudge banner derives "last run" from `created_at`, so a foreign-shaped record makes a non-empty store report *no reconcile run on record*. Candidate analyses and dry-run reports write their findings to `docs/reconcile/<date>-<topic>.md`, never into the store. (Since 2026-07-31 a read-side shape guard drops records lacking `learning_key`/`created_at` and `mergeCandidates` reports the count as `skipped` — that guard is a backstop, not a licence.)

• **Verdicts outlive the checkout in an append-only ledger** (#1710).

`.orchestrator/metrics/reconcile-verdicts.jsonl` resolves against the MAIN checkout (`resolveEventsLedgerRoot`) and sits beside `learnings.jsonl`, so it shares that file's tracking (vault: tracked, needs `merge=union`; this repo: host-local). Verdict lines come from `mergeCandidates`, once per terminal DECISION (`rejected`, `expired-swept`), and from `markCandidateProcessed` when a decision is stamped over a kept `written` / `already-on-disk` record (the merge keeps that record, so it cannot mirror the decision); the branch-scoped `written` / `already-on-disk` / outcome-less records stay out, because the tracked rule file's provenance marker already witnesses them across trees. After a non-dry merge the engine appends one run line with the learnings count it loaded; run recency comes from run lines only. A learning is terminal when the sidecar OR the ledger OR a `.claude/rules/` provenance marker says so. Code never rewrites the ledger; the only sanctioned hand edit is a deliberate re-open of a declined learning, and it must cover EVERY checkout: remove the learning's verdict lines from the ledger in the main checkout AND its record from the sidecar of the main checkout and of every linked worktree — otherwise the next merge in a worktree whose sidecar still holds the terminal `rejected` record appends it to the ledger again (backfill). Ceiling: a `/reconcile` in a linked worktree of the vault appends to the main checkout's tracked ledger — an uncommitted change there, committed by the vault's replica sync.

• **Same pipeline as session-end Phase 3.6.8.** This skill uses the identical engine and

writer seams as the automatic session-end reconciliation phase — operator experience is consistent, and any fixes to the engine benefit both paths.

• **`reconcile.enabled` gates the AUTOMATIC session-end phase only.** `/reconcile` is an

on-demand command and runs regardless of `reconcile.enabled`. It still honours `rule-expiry-days` and `confidence-floor` from the `reconcile` config block.

---

Phase 0: Bootstrap Gate

Read `skills/_shared/bootstrap-gate.md` and execute the gate check. If the gate is CLOSED, invoke `skills/bootstrap/SKILL.md` and wait for completion before proceeding. If the gate is OPEN, continue to Phase 1.

<HARD-GATE> Do NOT proceed past Phase 0 if GATE_CLOSED. There is no bypass. Refer to `skills/_shared/bootstrap-gate.md` for the full HARD-GATE constraints. </HARD-GATE>

---

Phase 1: Config & Argument Loading

1.1 Read Session Config

Read and parse Session Config per `skills/