| name | knowie-judge |
| description | Cross-check the knowledge base for coherence and alignment, detect rot, and tidy — proposing, never committing on its own |
| user-invocable | true |
| argument-hint | [scope: a file, a pair, or an event; empty = full check] |
Knowie Judge
Check the knowledge base is coherent, aligned with the code, and free of rot — then tidy. Diagnose and operate in one pass, but propose; never commit on your own (see core: division of labor).
1. Read with evidence
Scan each core file's Key Extensions table for topics the scope hits (or, if empty, derive from recent commits). For every sub-file the table points to: either read it and attach a verbatim quote + line, or say why you skip it. Never silently skip — the quote is the proof, not your word.
2. Reconcile
- Within each file (structure): principles — root present, each derived cites its chain? · vision — milestones have verifiable criteria? · experience — lessons distilled (four-part), not raw events? · any file — a bullet crammed with several claims → propose splitting (readability is per-bullet structure, not line count).
- Across perspectives: does the same concept's projection in principles / vision / experience agree, or contradict?
- Against ground truth (code): are the principles actually followed? milestones actually done? the lessons' pitfalls still real? Attach evidence; don't guess.
- Mark 🟢 aligned / 🟡 tension (quote it) / 🔴 conflict (quote + proposed fix).
3. Detect rot — mechanically, not from memory
- Orphans: any sub-file no Key Extensions table points to.
- Dead links: any pointer to a file that's gone or renamed.
- Conceptual dead references: dead links, one level up — a named criterion / lesson / concept cited as established ("see X", "echoes X", "the X principle") that has no file or heading defining it. grep the citations against the actual concept/lesson titles; a name relied on but never captured is the failure mode where a vivid discussion was mistaken for a stored one (capture's reliance trigger backstopped here). Flag it → it should be captured.
- Stale: entries referencing deleted code, finished milestones, resolved problems.
- Backlinks (derive, don't require
[[ ]]): the same scan inverted — grep '](path' gives a node's inbound links. Surface them on request, and flag a materialized back-edge that's asymmetric (A links B, but an intended B→A is missing). Links are plain [](path); the graph is derived, not stored (see principle 8).
- Derivation blast-radius: every derived principle cites its parent. When a principle is challenged or revised, grep those citations to list every dependent (and theirs, transitively) — surface the full impact set so a wrong root's downstream (derived principles / vision / experience) gets updated together, not silently left stale. Trace it; don't recall it from memory.
- Draft↔vision sync (both directions): every vision item that links a draft as its design-context → that draft must carry a promotion marker (promoted / in-flight-rationale) — a promoted draft with no marker reads as still-open when it's already committed. Reverse: a draft claiming it's in vision → vision must actually have it. grep both directions; mismatches are stale.
- Subdir READMEs present: every knowledge subdirectory (concepts / episodes / history / draft) must have a
README.md (it orients a third party who's never heard of knowie). ls */README.md; a missing one is a gap.
- Undocumented decisions: a notable change (a skill or subdir added/removed, a feature killed, a principle revised, a convention set) should leave a
history/ transition — and its durable idea may belong in a concept, its scene in an episode. Scan recent commits / the current structure against history/; a decision with no causal record is a hole. (Reflow §4 only fires on finished roadmap items — decisions made outside that flow slip through; this catches them.)
Run these with grep/ls — by eye, both humans and AIs miss them.
4. Reflow what was learned — dispatch, don't collapse
A finished roadmap item reflows into several places (don't dump all into one):
- lesson (distilled) →
experience; its full scene, if recall-worthy → episodes (link the lesson to it, and link the episode out to its how-artifacts — spec / PR / commit — don't copy them; pin a commit for a regenerable spec).
- decision-transition →
history; then retire the roadmap item (redeem-and-retire) and its source design draft — the draft's brainstorming scene, if recall-worthy, also reflows to episodes. Only now is the draft let go (it was the in-flight rationale until done).
- challenges a principle? → flag a proposal to amend root/derived principles, don't bury it in experience.
- a recurring new thing? → a concept.
5. Tidy — batch, each layer its own way
concepts/: converge upward — find the parent-concept (pruning-power test); watch the count flatten.experience/: two-way — merge similar lessons up; split full scenes down to episodes; clear stale.vision/: redeem-and-retire (done roadmap items reflow out, then leave); wishes not committed → back to draft/.draft/: by review-signal, push each topic one step along its chain — experience→consolidate, design→roadmap, problem→find-answer; long-untouched → let go (decay). Recency + frequency, not age. (The human-initiated version of this consolidate is /knowie-consolidate.) Exception: a draft linked from an active roadmap item is in-flight design rationale — never reap it; it retires only when its roadmap item completes (§4).episodes/: keep only the recall-worthy; let the rest fade.skills/: detection backstop — a recurring operation (across episodes / history / git) with no skill → flag a skill candidate (same recurrence-scan as draft's review-signal; capture records, human confirms). A stale/unused skill → flag for retirement: it still executes (higher stakes than stale knowledge — a stale skill acts, a stale doc just misleads), so don't let it rot loadable.
- Re-ensure projections (reversible → just do it): each skill in
knowledge/skills/ (the source) should be projected — per-skill symlink — into the present tools' skill dirs (.claude/skills/, .agents/skills/). Heal missing/broken ones (a fresh clone has the source but not the projections; a newly-present tool has none yet); copy-fallback where symlinks fail (Windows). Idempotent — already-correct is a no-op.
6. Stay within the line
Moving files (reversible) is yours. But commit, amend root principles, anoint parent-concepts → propose only; wait for the human.
Output — evidence, not theater
To the user: a health report (🟢🟡🔴 with quotes) + a prioritized action list + "want me to fix any of these?". Show what you actually read (quotes) and what rot you found (orphans / dead links) — not verbose internal logs.
