kb-refresh

name	kb-refresh
description	Re-verify time-sensitive claims in KB notes against live sources and apply visible corrections. Use when the user asks to "refresh the KB", "re-verify notes", "check what's gone stale", or on a schedule. Distinct from /kb-review (structural quality) — this checks whether the facts are still true.
user_invocable	true
arguments	Optional: a note slug to refresh directly, --kb <name>, --limit N (default 5), --dry-run (show queue only)

/kb-refresh

Re-verify claims in notes whose freshness window has lapsed, using live web research. Corrections are always visible — banner + strikethrough, never silent rewrites.

Queue selection: Parse $ARGUMENTS. If a slug is given, refresh that note only. Otherwise run:

python3 .kb/kb-index.py refresh-queue --json [--kb <name>] [--limit N]

Default limit 5. With --dry-run, print the queue with scores and claims, then stop.

Steps

1. Get the queue — Run refresh-queue --json. Each entry has claims_to_check (dated/dollar/percentage claims), days_overdue, window_source, and dependency weight. If empty, report "all notes within freshness windows" and stop.

2. Back up before editing — Run .kb/backup.sh once before touching any note (kbs/ is gitignored; there is no git undo).

3. Read each note fully — claims_to_check is a heuristic sample; read the note and identify ALL time-sensitive claims: dollar figures, dates, "as of" statements, market rankings, company/product status, people in roles, prices, regulatory status. Skip claims that are historical record (an exploit's loss amount doesn't change; a company's current AUM does).

4. Verify with web research — Spawn concurrent research agents (one per note, or one per claim cluster for large notes). Each agent:

   • Searches for the CURRENT state of the claim from primary or credible secondary sources
   • Returns: claim → confirmed (still true) / changed (new value + source) / unverifiable (no current source found)
   • Saves substantive sources as new files in references/ with proper Source-Type: classification (never edit existing reference files)
   • Watch for disambiguation traps (same name, different entity) — verify the entity matches before accepting a "change"

5. Apply corrections — For each note, by verdict:

   • All confirmed: update updated: to today; add a line Re-verified: YYYY-MM-DD under the title if one doesn't exist (or update it). Nothing else changes.
   • Something changed: add a correction banner directly under the title, in the established style:

     > ⚠️ **Partially superseded (YYYY-MM-DD)**: <one-line summary of what changed>. See [[superseding-note]] if one exists.
     

     Strike through the wrong values in place (~~old~~ → new ([source](../../references/file.md))), update updated:, and downgrade epistemic_status if the note's overall reliability dropped (e.g. verified → likely). If the change is large enough to warrant a new note, create it and set deprecated_by: on the old one instead of rewriting.
   • Unverifiable: do not delete the claim. Annotate it (unverified as of YYYY-MM-DD) and set epistemic_status: speculative if the note's core claims are affected. Add the gap to the owning research hub's gaps: frontmatter if one exists.

6. Propagate — If a corrected note has synthesis_dependents in the queue entry, flag those syntheses: run python3 .kb/kb-index.py stale-syntheses and report which need regeneration via /kb-explain.

7. Rebuild and lint — python3 .kb/kb-index.py build --incremental, then lint <slug> for each edited note. Fix any errors.

8. Log — Append a ## [YYYY-MM-DD] refresh | <scope> entry to .kb/log.md: notes checked, verdict counts (confirmed/changed/unverifiable), the specific corrections, and sources saved.

Report format

End with a table: note | verdict | what changed. Lead with the changes (corrections are the news; confirmations are one line). If a correction affects outreach lists, contact registries, or other action-bearing notes, call that out explicitly — the user acts on these.