| name | curating-knowledge |
| description | Add or curate an entry in ObjectCore's factory knowledge base (a lesson, pattern, gotcha, or decision) stored under knowledge/. Use when a durable, reusable engineering lesson emerges, a design decision is made, or the knowledge base needs pruning. |
Curating Knowledge
ObjectCore's factory knowledge base is the growing memory the build + eval loop
reads on the way in and writes on the way out. It lives at knowledge/:
one frontmatter'd file per entry under knowledge/entries/<id>.md, plus a
generated knowledge/INDEX.md. The engine is @objectcore/knowledge (the
KnowledgeStore port + FileKnowledgeStore). Entries now have a lifecycle
(update / supersede / deprecate / verify), so the KB is no longer append-only:
fix, replace, or retire an entry instead of piling near-duplicates on top of it.
When to write an entry
Capture something durable and reusable — a lesson that will still matter next
month and that isn't already obvious from the code or git history:
- lesson — something learned the hard way ("merging to main auto-publishes").
- pattern — a recurring design choice to repeat ("storage is a port").
- gotcha — a sharp edge that bites ("subagents can't declare hooks").
- decision — a chosen direction + why ("build our own KB, not auto-memory").
Do NOT store transient task state, secrets, or anything the repo already records
(code structure, past diffs, CLAUDE.md). If unsure, prefer one crisp entry over
several vague ones.
Steps
- Search first. Before writing, look for an existing entry:
bun run kb:search "<topic keywords>"
(deterministic lexical retrieval over the corpus). If a near-duplicate exists,
UPDATE or SUPERSEDE it (see the lifecycle below) instead of adding a new one —
and note kb:add now refuses a near-duplicate, printing the match it hit;
pass --force only when the overlap is genuinely coincidental.
- Write the entry. Either run the engine:
bun run kb:add --json '{"type":"gotcha","title":"...","tags":["a","b"],"source":"<url|path>","body":"..."}'
(or --json @file.json), which appends knowledge/entries/<id>.md and
regenerates the index — or hand-author the file in the same frontmatter form
(id, type, title, tags, source?, created) and then run bun run kb:index.
- Keep the body tight — a few sentences: what the lesson is, why it matters,
and how to apply it. Link the source (a doc URL, commit, file path, or plan).
- Regenerate + gate.
bun run kb:index then bun run kb:check (also part of
bun run check): it asserts INDEX.md byte-matches a fresh render, runs the
offline retrieval evals, checks lifecycle integrity (supersede targets, cycles,
links), and enforces the 200-line / 25KB budget.
Curating existing entries (the lifecycle)
Entries are no longer append-only — fix, replace, retire, or re-confirm them with
bun run kb:curate (one mode per invocation; --json accepts inline or @file):
- Update a mistake or add detail:
bun run kb:curate --update <id> --json '<patch>'.
- Supersede a lesson a newer one replaces:
bun run kb:curate --supersede <old-id> --json '<new entry>'. The old entry
drops out of INDEX.md (and reclaims budget) but stays on disk and in git
history — bounded forgetting, not deletion.
- Deprecate a no-longer-true lesson:
bun run kb:curate --deprecate <id> --reason "<why>".
- Verify an entry you re-confirmed is still true:
bun run kb:curate --verify <id> [<id>...] (stamps verifiedAt).
Curation runbook (periodic)
bun run kb:stats ranks prune candidates worst-first (stale, then
never-cited, then oldest anchor) — the entry point for a curation pass.bun run kb:verify classifies each active entry fresh / stale / unverifiable
from its source paths + git history. Both read git dates, so they are
local-only curation tooling — deliberately NOT part of bun run check
(CI clones are shallow, so git-dated staleness would be wrong in the gate).- Budget overflow is still the rot signal, but now bounds active entries
only — supersede/deprecate genuinely reclaims room, so keep curating (merge
near-duplicates, tighten titles); the index split alone doesn't prevent rot.
Citations + ROI
When a stored lesson actually helps (a fix, a diagnosis, a review):
- Record it:
bun run kb:cite <id> --source "<ref>" — appends to
metrics/kb-usage.jsonl, which feeds the never-cited signal in kb:stats.
- After a lesson-driven fix lands, link it to gate health:
bun run eval:record --note "lesson:<id>" (surfaced back by kb:stats).
Rules
- Never hand-edit
knowledge/INDEX.md — it is a build artifact, like
marketplace.json. Edit entries (or kb:curate), then kb:index.
- One fact per entry, kebab-case
id, a real source.
How this feeds the self-improving loop
This skill (and /remember) is the manual write path today. The same
KnowledgeStore is what the loop automates: kb-writer's SessionStart hook
surfaces the INDEX and its Stop hook nudges capturing a durable lesson, and the
self-reflection subagent turns failing activation/output evals into entries here
— searching first, writing with origin: reflection, and superseding a wrong prior
lesson rather than duplicating it — closing the Reflexion loop on this substrate.
