| name | refresh-kb |
| description | Rebuild or update the OKF knowledge bundle under docs/kb — the concept-doc map of Synto's internals (each fact a path:line link) used for navigation. Reach for this whenever the kb has drifted from the code, or someone asks to "refresh the kb", "update the knowledge base", or "get the kb in sync" — e.g. after a feature lands, a subsystem is refactored, files move, a new concept needs seeding, or path:line references go stale. This is specifically the docs/kb concept map; it is NOT for editing .claude/playbook, writing READMEs, re-importing the OKF SPEC.md from upstream, or changing code or tests. |
| user_invocable | true |
refresh-kb
The docs/kb/ bundle is an OKF knowledge map of Synto's
internals — the where/what layer (where code lives, the non-obvious invariants),
distinct from .claude/playbook/ which owns the why/how-to-evaluate. This skill
keeps that map honest as the code moves.
Core principle — it's a map, not prose. Every fact points at code with a
path:line link and stays terse. Docs that explain instead of point rot into stale
walls; docs that point stay cheap to verify and cheap to trust. When in doubt, link
and trim rather than narrate.
When to run, and how much
Decide scope first — most refreshes are targeted, not full rebuilds:
- Targeted (default) — a feature landed or a subsystem changed. Touch only the
affected concept(s) + any index listing that references them. Don't rewrite the bundle.
- Full — the bundle is being seeded, or many areas drifted at once. Rebuild every
concept from current source.
- Drift-sweep — paths/line numbers feel stale but the structure is fine. Re-verify
path:line references and fix the drift; touch nothing else.
If the scope isn't obvious from the request, ask which of these it is before spawning work.
The contract you must obey
The bundle is self-describing — its rules live inside it. Read these first, every run:
docs/kb/conventions.md — the type registry (fixed set of types + the rule for
when a new one is allowed) and the per-type frontmatter contract. This is the
source of truth; honor it over anything in this skill if they ever disagree.docs/kb/index.md — the current shape, so you update rather than duplicate.
Non-negotiables that fall out of the contract:
- Types are a fixed vocabulary. Reuse an existing
type. Add a new one only when
a kind of concept recurs ≥3× — otherwise you get sprawl no one can navigate. If a
new type is justified, register it in conventions.md in the same change.
- Every concept (non-
index.md) has frontmatter with a registry type plus its
per-type required keys. index.md files carry no frontmatter (OKF §6).
- Links are bundle-relative (
/subsystems/templating.md) — stable under moves.
resource and inline path:line are repo-root-relative (root = repo top).
- Body skeleton for Project/Subsystem concepts: Responsibility · Key files ·
Entry points · Invariants · Related. Keep each line a pointer.
Gather accurate facts before writing
Never write a concept from memory — line numbers and structure drift, and a confidently
wrong map is worse than none. Get current facts from the actual tree:
- Scope explorers to areas and run them in parallel — e.g. one for projects +
architecture, one for the templating pipeline, one for quoting/matching/decorations +
examples. Ask each for dense
path:line-backed facts (responsibility, key files,
entry points, invariants, dependencies), not prose.
- Ignore
.claude/workspaces/ — those are throwaway jj workspace copies of src/
and will pollute results. Only src/, test/, and examples/ at the repo root count.
- For a targeted refresh you usually need just one explorer (or none, if you already
have the facts in this session).
Write / update concepts
For each concept in scope:
- Match the body skeleton above; lead with a one-line Responsibility.
- Back every claim with a
path:line link. Cross-link related concepts so the map is
traversable, not a pile of pages.
- After editing concepts, update the listings: the relevant domain
index.md and
the root index.md if you added/removed/renamed a concept. Index entries should carry
the concept's one-line description so progressive disclosure actually discloses.
Verify, then commit
- Conformance check — every non-
index .md in docs/kb has a registry type;
index.md files have none. A quick grep for ^type: across the bundle catches both
a missing type and an accidental one in an index. (The imported SPEC.md is itself a
Reference concept with frontmatter — keep it that way so the bundle passes OKF §9.)
- Sanity-check a few
path:line links you wrote actually point where you claim.
- Commit with jj (this repo is jj-native): one focused commit, e.g.
docs(kb): refresh <area> — <what changed>. Don't push unless asked.
Maintenance truths
- Paths are stable; line numbers are the soft part. A drift-sweep that only fixes
line numbers is a legitimate, cheap refresh — schedule it when concepts feel off.
- The kb is navigation, the playbook is judgment. If you're tempted to write why a
thing is good or how to review it, that belongs in
.claude/playbook/, not here.
