/kb-reconcile

name: kb-reconcile
description: Use when a finished thing — a source, a result, code, or the record — is about to be trusted or consumed; the gate fires before the work leans on it. The project's knowledge base (knowledge-base/ - the accreted record of decisions, contracts, reviews, timeline) needs auditing against its sources and itself before its conclusions get used. Flags contradictions, partial-update drift, stale statuses, expired verdicts, map-staleness, broken provenance, and unsourced numbers; it writes the exact check for anything it cannot verify from files on hand. Detects: "audit the whole knowledge base", "reconcile the knowledge base", "audit our notes/KB before the board", "is the KB still accurate/consistent", "did anything drift", "is what we wrote down still true". Within this family: ONE code object against the contract is review-my-query; unvalidated source premises are audit-my-assumptions. Read-only and advisory: never runs code, never edits the KB - it emits a graded reconcile.md.
allowed-tools: Read, Write

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.

The signature output

A graded reconcile report: for each audited claim, its status (reconciled / drifted / unverified / contradicted), the `file:line` evidence, and a suggested action. The point is the Blocking drift — a claim a decision rides on that its own cited source does not support — plus the explicit list of numbers no source on hand can verify.

The honesty spine (non-negotiable)

• A claim is `verified` ONLY via a paste-back run, labeled by source and restated verbatim. Reading bytes is never verification.
• No "consistent / clean / reconciles" without showing what you checked THIS run. Every audited claim ends reconciled / drifted / unverified / `[needs decision]` / N-A-with-reason. A silent skip is a failure.

Bright lines (inherits groundwork's read-only)

• **Never execute, connect, or profile data.** Write the check; the user runs it and pastes back. ("Let me just run it" -> stop.)
• **Never edit the audited files.** The only file you write is `reconc