/reconcile

name: reconcile
user-invocable: true
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

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.)

• **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/_shared/config-reading.md`. Store result as `$CONFIG`.

1.2 Extract Reconcile Config

Extract the `reconcile` block from `$CONFIG`:

# rule-expiry-days defaults to EMPTY (not a number) so the engine falls back to
# its per-type TTL (deriveExpiresAt, default 60d). A numeric override forces flat
# N-day expiry — matching the `null` default of the reconcile: config resolver.
RULE_EXPIRY_DAYS=$(echo "$CONFIG" | jq -r '.reconcile["rule-expiry-days"] // empty')
CONFIDENCE_FLOOR=$(echo "$CONFIG" | jq -r '.reconcile["confidence-floor"] // 0.5')
RECONCILE_MODE=$(echo "$CONFIG"   | jq -r '.reconcile.mode // "warn"')
MIN_RULE_DAYS=$(echo "$CONFIG"    | jq -r '.reconcile["min-rule-days"] // 7')
MIN_INSIGHT_CHARS=$(echo "$CONFIG" | jq -r '.reconcile["min-insight-chars"] // 24')
MAX_PROPOSALS_PER_RUN=$(echo "$CONFIG" | jq -r '.reconcile["max-proposals-per-run"] // 10')

When `RULE_EXPIRY_DAYS` is empty, pass `ruleExpiryDays: undefined` to `runReconcile` so the engine uses its per-type TTL. Defaults when the `reconcile` block is absent or a field is missing:

• `rule-expiry-days`: empty → per-type TTL (`deriveExpiresAt`, default 60d). Preserves FA2 behaviour; matches the `null` resolver default.
• `confidence-floor`: 0.5
• `mode`: warn (enum `off` | `warn`)
• `min-rule-days`: 7 — floor window (days) applied to a proposed rule's `expires-at` so a

near-dead or already-elapsed natural expiry never produces a born-dead rule (issue #741.1).

• `min-insight-chars`: 24 — opt-in minimum insight length gating the eligibility

placeholder-insight check (issue #741.2).

• `max-proposals-per-run`: 10 — volume brake (issue #900 D); the engine sorts eligible

learnings by confidence DESC and proposes at most this many per run.

Note: `reconcile.enabled` is intentionally NOT checked — this on-demand command always runs.

1.3 Parse Arguments

Check `$ARGUMENTS` for `--dry-run`:

DRY_RUN=false
if echo "$ARGUMENTS" | grep -q -- '--dry-run'; then
  DRY_RUN=true
fi

---

Phase 2: Run the Reconciliation Engine

2.1 Resolve Plugin Root

Resolve `$PLUGIN_ROOT` per `skill