Skip to content

Reconcile ​

Reconcile drains a reconcile: any ledger of partial work, a file whose items are about work that already exists and has fallen out of line with something settled. RECONCILE.md and BUGS.md are the same species under this reading, and the module treats them as one, resolving both off a shared registry rather than two hand-written commands that would slowly drift apart. It is the deliberate sibling of capture – capture writes an entry into a log, reconcile reads the items back out and closes them – and what it does that a plain sweep does not is verify: an item is a snapshot of what was true the day it was written, and the tree has moved since. A pass never sweeps off the bullets in a section, it re-derives the real remainder off the tree today, reports it, and only then closes the item on Finn's go.

What Counts as a Reconcile ​

Four tests separate a reconcile from an ordinary idea backlog: the item is about work that already exists, it has an enumerable remainder, that remainder can be re-derived off the tree, and the item leaves the file the moment the remainder hits zero. A maybe or an open question fails all four and belongs in a capture backlog instead, never here.

Six ledgers are registered today. reconcile drains RECONCILE.md, bugs drains BUGS.md, and pending is a family row covering all four frameworks/*/PENDING.md files at once, since they are not written at the same heading depth and a single fixed level would misread some of them as holding no items at all. The remaining three – mod-doc, wiki, and migrations – are read-only: they are listed here but drained by their own commands (/mod-doc, /wiki, harness migrate), which is what makes a bare /reconcile the one screen showing everything outstanding across the estate, not just this module's own share of it.

In Practice ​

See what's outstanding, without touching anything. Run the command bare and it lists every registered ledger with its open count, then recommends one:

/reconcile

Work one ledger. RECONCILE.md is the default reconcile, bugs is BUGS.md:

/reconcile bugs

lists the open bugs, numbered, and says which is worth a pass.

Work one named item. Adding a number pulls that item, verifies its remainder off the tree, and reports it:

/reconcile bugs 2

The sweep itself waits for Finn to say go, unless --sweep was passed alongside the name, in which case the confirm is skipped.

Run the cheap regular pass. check verifies every item's remainder and writes nothing:

/reconcile check

This is how an item that finished by accident – something else already did the work – gets found without reading the whole ledger by hand.

Log a new item without leaving the session. /capture recon writes straight into RECONCILE.md through the recon capture mode:

/capture recon installer's config-reconcile engine now needs the same records skip swap-refs.nu carries

The recon mode overrides capture's usual one-line-per-part rule on purpose – its guidance calls this one out as a genuine writeup, because an item that reads "installer needs a restructure" is exactly what the mode exists to stop. It wants what changed, what landed this session, what did not, and how to finish it, never a guessed remainder count – that gets re-derived at drain time.

Read a ledger without the skill. The engine underneath works stand-alone:

nu .claude/reconcile/reconcile.nu list
nu .claude/reconcile/reconcile.nu items bugs
nu .claude/reconcile/reconcile.nu show bugs 2
nu .claude/reconcile/reconcile.nu close bugs 2 --dry

An example outcome. A bugs item that turns out to already be fixed costs one check pass and a close, never a file touched on faith. A pass that finds three real files left gets exactly three files swept and the item closed, with the archiver's pre-edit stamp standing as the record rather than a done-marker left sitting in the ledger.

Closing an Item ​

Two ledgers close differently, and the difference is carried entirely as data rather than as code. reconcile's policy is delete: the item's heading and body are cut out and nothing else happens. bugs's policy is move: the same cut happens, but the body is then appended to BUGS-fixed.md. A readonly row (mod-doc, wiki, migrations) cannot be closed here at all – its close field carries no policy because nothing here can write it, only its own drain command can.

The cut itself stays inside the engine because an item's identity here is a line, scoped to the open window a close re-derives on every call, while harness/scripts/splice-section.nu anchors on a header name plus --nth across the whole file – two different numbering schemes that must never be passed to each other. The append half is handed off deliberately: insert-lines.nu needs no anchor at all, it just appends, keeps the file's trailing blanks tidy, and stamps its own archive copy, so the move policy gets a clean writer for the one operation that genuinely has nothing line-scoped about it.

Where the open items actually sit is also data: under names the parent heading they fall beneath (blank means top level), and level says what heading depth one item is written at, with 0 telling the engine to work it out as the shallowest heading below the title, which is what lets the pending family row cover four files that are not all written at the same depth.

Key Files ​

reconcile.nu ​

The engine – one subcommand per step: list (every registered reconcile with its open count), items (numbered open items of one), show (one item's text), path (resolve the file without reading it), close (apply the row's policy, archive-stamped first), and wrapper (print a dedicated slash command for one reconcile). It resolves the harness root the same three ways capture.nu does, because an installed copy sits inside a project's .claude/ and cannot walk up to find the harness on disk.

reconciles.nuon ​

The registry, two tiers. The harness ships a global list at harness/store/reconciles.nuon; a project's own .claude/reconciles.nuon (seeded empty from modules/reconcile/reconciles.nuon at install time) can reuse a global name to override that row, or add a new one. Every field – scope, dest, family, under, level, close, done, verify, guard, wrapper, readonly, drain – is documented inline at the top of the file.

SKILL.md ​

The procedure – six steps: list without reading the ledger whole, classify the item, re-derive the remainder off the tree, report and stop, sweep only what step three enumerated, then close it through the engine. It draws the boundary too: this is not /modify reconcile (reconciling a banked extern module against upstream), not the installer's own config-reconcile engine, not /apply (draining a capture log), and it never writes a new item into a ledger, only drains ones already there – that half belongs to /capture recon.

commands/reconcile.md ​

The /reconcile entry – passes $ARGUMENTS straight through: empty for the list-and-recommend screen, a name for one ledger, a name and a number for one item, check for a verify-only pass, and --sweep to skip the go-ahead confirm once Finn has already said yes.

references/sections.md ​

The classification guide – the five-verdict table (runnable, blocked, not a remainder, already done, procedure), the tells that mark a line as blocked or excluded in Finn's own words rather than a field, and the rule that records (plan/, tests/TESTS.md, BUGS-fixed.md, retired/) are never a remainder because sweeping them would make the history lie.

references/verify.md ​

The re-derivation guide – one recipe per item shape: a rename or path sweep goes through swap-refs.nu rather than grep, batched and with a records skip list bound up front, since its own defaults don't cover the harness's own records; a convention every file of a kind now owes is checked against the reader that already enumerates that population; a moved module source is compared only once both the source and installed paths are proven to exist. Zero is treated as a real, and the best, answer, since it turns the whole pass into a delete.

references/close.md ​

The closing guide – the three ways a pass ends (delete the item outright, rewrite it to narrow the remainder, or leave it untouched), the sync-point checklist a sweep over module files can owe, and the standing rule that a pass never closes a second item just because it was already in the file, one job per pass so a pass stays reviewable.

Connects to ​

  • Paired with capture – /capture recon is the write half of this module, logging a new item into RECONCILE.md through the recon mode in capture-modes.nuon, which is what makes reconcile a full loop rather than just a drain.
  • Drains RECONCILE.md, BUGS.md, and the four frameworks/*/PENDING.md files, whose shapes frameworks/CONTEXTS.md owns.
  • Lists but never closes .claude/mod-doc/pending.json, .claude/wiki/pending.nuon, and installer/src/migrations.ts, each drained by its own command (/mod-doc, /wiki, harness migrate).
  • Hands its move close to insert-lines.nu for the append, and routes a rename or path sweep through swap-refs.nu with a records skip list of its own.
  • Follows the reconciliation-triggers rule in frameworks/MODULE.md – a deferred trigger gets written into a ledger rather than swept on the spot, and reconcile is what later drains it, on Finn's go, never automatically.
  • Is a local module, installed through harness local rather than the project picker, since it is harness-only for now.
  • Logs a real verified run to harness/tests/TESTS.md, dated, newest at the bottom, rather than writing a done-marker into a ledger itself.
  • The condensed, end-user version of this page is the module's own USAGE.md, at harness/modules/reconcile/USAGE.md – that one is the thin command, config, and gotcha reference, this page is the fuller depth of the same module.