kb-reconcile

kb-reconcile

The colleague who re-checks the record before you lean on it: reconciles the knowledge base against its sources and itself, tells you what has drifted, what can't be verified, and what to do about each — and never quietly rewrites your notes.

When to use

Fire when there is a knowledge-base/ (or equivalent accreted notes) and the question is "is the record still true / consistent" before its conclusions are used — a board readout, a handoff, a funding call, or a periodic audit. Triggers: "reconcile the KB", "audit our notes before the board", "is the KB still accurate", "did anything drift", "check the KB against the data/contract". Do NOT fire to review ONE piece of code against the contract (review-my-query), to diagnose why ONE number came out wrong (triage-my-number), or to orient on an unfamiliar estate (groundwork). This audits the WHOLE record's integrity. This vs. its neighbors: fire to audit your whole accreted knowledge base against its sources and itself. A single source or analysis you're about to build on or present → audit-my-assumptions. One wrong number → triage-my-number.

The trap this exists to beat

Handed a knowledge base and a question, a capable assistant reads it and ANSWERS — and it trusts what it reads. So when a later edit closed an item the contract still marks open, or a number is stale, or a claim has no source, it carries that forward as a confident result. (Proven: under board pressure, a cold reader propagated a planted "reconciliation closed / 108% board-ready" while the contract it cited still said [needs decision].) The discipline it skips is switching OUT of answer-mode into ADVERSARIAL AUDIT-mode: assume each claim is wrong until it reconciles against its source and the rest of the record, and refuse to bless a number it cannot verify. This skill forces that switch.

The loop

1. Scope + rank by stake. Read the KB. Rank claims by what rides on them (a live decision/readout = load-bearing). Audit load-bearing first; offer the exhaustive pass after.
2. Internal reconcile. Cross-check every material claim against its cited source IN the KB and against the other files. Flag contradictions, partial-update drift, a decision a later artifact violates, qualifier erosion, status rot, broken provenance, unsourced claims. Cite file:line + the verbatim quote for each (no quote, no finding).
3. Source reconcile (read-only). For claims citing code/definitions present in the repo, check the claim against the actual text. Unknown structure is a question or a flagged assumption, never a silent guess.
4. Mark unverifiable + write the check. For every quantitative claim with no checkable source on hand, do NOT bless it: mark it unverified and write the exact query/script for the user to run against source and paste back.
5. Reconcile the paste-back. On a pasted run result, compare to the KB claim. The run wins: verified (restate verbatim, labeled by source) or contradicted (KB stale/wrong -> suggested fix). Never call anything verified without a pasted run.
6. Triage + grade. Classify each drift (partial-update / staleness / expired-verdict / map-staleness / term-drift / garbage-in / contradiction / derivation-error / unsourced) and grade Blocking (a wrong or contradicted claim a decision rides on) / Latent / Advisory. Each finding carries a suggested reconciliation action (which file, what change) as a decision-brief: recommendation + default, or [needs decision] where you cannot adjudicate (e.g. an internal contradiction with no precedence).
7. Emit + recommend. Write reconcile.md (template in references/reconcile.md) — the only file you create. List the escalations there as recommended actions: the open-questions.md entry per Blocking drift, the timeline.md line to append, the cross-refs. Do NOT edit the audited files; the report recommends, the user applies. Then stop.