claude/skills/reconcile/SKILL.md

name

description

reconcile

Use when you need the REAL open-work state of a project and the TODO or memory registries may be stale — "is the queue empty?", "what's left open?", "qu'est-ce qui reste", before /close, after a break, or when a checkbox/status looks doubtful. Confronts declared status (TODO checkboxes, registry statuses) against real git/fs state and surfaces the gaps. NOT memory curation (that is /prune-memory).

/reconcile — declared vs real

Overview

The open-work queue lies whenever a [x]/[ ] checkbox, a registry status, or an ## Index row has drifted from what git/fs actually show. /reconcile answers "what is really left?" by verifying, never by believing a declarative source.

Founding principle — recursive coherence: never use a declarative source as an oracle (not the Index, not a checkbox, not a status claim, not a path name). Truth = registry BODY (## ID — headings), git, fs. The skill practices what it preaches — lib/tests/run-reconcile.sh T1 reds if the engine ever reads the Index.

When to use

• "Is the queue empty / what's left to do?" — the naive answer (grep '[ ]') is a mirror of the TODO and inherits all its lies.
• A checkbox or status looks doubtful; work suspected stale after merges/pushes.
• Before /close, or re-orienting after a break.

Not for: curating/compressing registries → /prune-memory. The skill never edits registry content (read-only here).

How it runs

REQUIRED ENGINE: lib/reconcile.sh does the mechanical truth-probing. A capable agent CAN reconcile by hand — but burns ~50k tokens, depends on the question being phrased well, and still hits traps (compound status, a disclaimer instead of a check). The engine is deterministic, cheap, repeatable. Source it, then:

1. Enumerate registry entries from BODY headings (reconcile_enumerate_ids, never the Index).
2. Per declared item, run the matching oracle (reconcile_oracle_*, reconcile_blk_current_status = last block wins) and apply reconcile_verdict.
3. Classify into the four categories.
4. Gate the write-back (below).

Output — four categories

1. Actionable now — open AND real state confirms not done.
2. Blocked (external) — reconcile_blk_open: current status upstream/open, not our code.
3. Deferred — lexically-marked follow-ups + [~] items (conditional triggers).
4. TODO↔real gap — declared ≠ verdict (open-but-done, done-but-open, partial-but-done).

Plus contradiction candidates — reconcile_contradiction_candidates: accepted-BDR ⇄ open-chantier overlap, surfaced for human review.

The gate (mandatory)

Before applying (A/B): follow $HOME/.claude/lib/gitflow-aiguillage.md — TYPE chore. On main/develop the write-back branches to chore/<name> off develop first, so a reconciled TODO never lands direct on a protected base; on a working branch it applies in place. Never gitflow finish (human-gated).

Reconciling the TODO edits a tracked file → never silent. Show the proposed diff, then ask: A apply all · B select a subset · C touch nothing. Registries stay READ-ONLY (append-only; curation is /prune-memory).

Honest limits (do not over-read the guarantee)

• Deferral detection is lexical — catches MARKED deferrals, misses unmarked ("à reprendre quand X"). Deterministic on the detectable; surface the ambiguous for human review, never assert.
• Contradictions are candidates (token overlap), not verdicts — a human confirms.
• Cross-repo items (oracle in another repo) → "not verifiable here", never flagged stale.
• Cross-reference verdicts ("[~] done because chantier X below is complete") are SURFACED, not auto-resolved.

Common mistakes

• Grepping [ ] and reporting it as open → reproduces the lie. Run the oracle.
• Reading the ## Index for status → inherits its drift (T1 forbids it).
• Writing a disclaimer ("à vérifier si déjà fait") instead of verifying → the engine verifies, it never hedges-and-advances.

Validation

bash lib/tests/run-reconcile.sh → 20/20, shellcheck clean. Oracle of record = the 2026-06-29 inventory (7 gaps + 3 blocked + 5 deferred + 1 contradiction), fixtures frozen under neutral names in lib/tests/fixtures/.