| name | knowledge-curator |
| description | The maintenance program for this scaffold's live knowledge gradient — where captures go (zz-log → zz-research → 02-stack → 01-kernel), the promotion gates between stages (evidence-gating, second-user test, supersession rules), decay review, and retrieval-friendly writing (description-as-semantic-key, one concept per file). Use when capturing insights, promoting notes between stages, deciding where knowledge lives, or reviewing stale docs. |
Knowledge Curator — the live gradient's maintenance program
This skill is procedural memory: the rules the agent executes to keep the knowledge base healthy. It is content, not a trigger — the triggers are the Stop-hook (check-zzlog.sh), CLAUDE.md's Hard Rules, and the user asking for capture/promotion/review.
The live gradient
Temperature falls as the directory number falls. Promotion = moving down in number, up in distillation.
| Stage | Location | What lives here | Cadence |
|---|
| HOT | agent-context/zz-log/<date>.md | Session worklogs — what happened, why it mattered, receipts | Every significant session (Stop-hook enforced) |
| WARM | agent-context/zz-research/<date>-<topic>.md | "Trail of crumbs" — tool sweeps, deferred evals, orientation notes. Explicitly NOT commitments | When a thread outlives one session |
| COOL | 02-stack/ (patterns + section docs) | Distilled, reusable recipes and decision frameworks tied to this stack | On promotion (gated — see below) |
| CANON | 01-kernel/ | Tool-agnostic principles that survive a harness swap | Rarely; highest gate |
| FROZEN | _archive/<YYYY-MM>/ | Retired implementations and superseded docs — preserved, out of the live namespace | On decay review |
The site mirrors (site/, public repos) are views generated from these stages, not stages themselves.
The underlying theory (Bergman & Whittaker's navigation-over-search, Noguchi's push-left, Zettelkasten fleeting-vs-permanent) lives in 01-kernel/principles/02-temperature-gradient.md. The numbered-zones knowledge-base/ tree that previously instantiated this gradient is retired (template projects may still use it — the zone model remains valid for greenfield scaffolds); THIS repo's instantiation is the pipeline above.
Write policy (promotion gates)
A knowledge base needs a write policy, not just a read gradient — inaccurate writes become recurrent errors an agent will confidently repeat.
- zz-log → zz-research: promote when a thread spans sessions or needs topic-findability. No evidence gate — crumbs are allowed to be wrong.
- zz-research → 02-stack (the big gate): requires evidence — at least one of:
- the recipe was executed and verified in this environment (command output, test pass), or
- the second-user test: the pattern got used a second time, unchanged, or
- primary-source citations for every load-bearing claim.
New promotions start
status: research.
research → stable (within 02-stack): the doc survived contact with reality — reused without needing correction.- 02-stack → 01-kernel: only if tool-agnostic — would this survive swapping Claude Code for another harness, or Tailscale for another mesh? If it names specific tools as load-bearing, it stays stack-tier.
- Supersession, never silent duplication: a doc that replaces another must link it, and the superseded doc gets
status: parked + a pointer forward. Two live docs claiming the same ground is a bug.
- Decay review: any
status: research doc untouched ~90 days gets one of: re-verify (bump), parked (still plausible, not active), or _archive/ (dead). Stale confidence is worse than an honest gap.
Retrieval duties (make knowledge findable by machines)
description: frontmatter is the semantic key — it's what embeddings index and what agents match on. Write it keyword-rich, specific, self-contained (the existing zz-research descriptions are the house style).- One concept per file; H2/H3 sections self-contained enough to be retrieved alone.
- Update the directory's
index.md when adding a doc — index-first navigation is the primary retrieval path; semantic search (cks-sem, ck MCP) is the deep tier.
- Frontmatter
status: must use the site enum: draft | research | aligning | planning | active | observed | log | stable | parked (pre-commit enforced).
- Tier-2-clean by default (CLAUDE.md Hard Rule): placeholder hostnames/paths; tier-3 specifics go to gitignored paths (
03-work/homelab/, research/personal-workflow/).
Capture heuristics (what's worth writing at all)
Capture when: rationale isn't obvious from the diff; a failure cost >30 min and has a reusable diagnosis; a decision forecloses alternatives; an external tool/fact was verified the hard way. Skip: typos, lint, sync regenerations, anything fully re-derivable in under a minute.
Anti-patterns
- Promoting to
stable without evidence ("it looks right") — calcifies hallucinations into canon.
- Blanket-trusting old docs — check
date:/status: before citing a research doc as fact.
- Creating a new note when an existing one should be updated (supersession rule).
- Padding always-loaded files (CLAUDE.md) with content that belongs in a gradient stage — the always-loaded layer is a map, not a warehouse.
