--- name: ckb-lint description: Health-check the wiki/ — conformance, freshness, confidence decay, retention sweep, supersession detection, orphan detection, graph consistency, index/log consistency, and error-book entries — auto-fixing what it safely can and reporting the rest, then reminding the user to review and sync to origin. Also runs the same checks against each connector-backed libs//'s own generated index (see ckb-index-external), plus a source.yaml validity check, without ever touching a git-copy lib or a connector's source.yaml itself. Use when the user says "Lint", "health-check the wiki", "check the wiki", or asks for a periodic/scheduled wiki health check. This is the maintenance workflow routed by CLAUDE.md/AGENTS.md, distinct from `ckb-ingest` (which adds new content) and `ckb-sync-changes` (a pure git-level operation with no wiki synthesis at all). --- # Lint skill ## Purpose Health-check the local, mutable `wiki/` for structural rot: missing or malformed frontmatter, stale pages, decayed confidence, orphaned or archivable content, broken graph edges, and index/log drift. This is maintenance, not growth — it never adds new knowledge the way `ckb-ingest` does; it only checks and repairs the shape of what's already there. Implemented as a skill (rather than living inline in `CLAUDE.md`/`AGENTS.md`) so the full checklist only loads into context when actually invoked — on demand, or on a schedule if the user has set one up. The **detection** half of this checklist is mechanical — a fixed set of frontmatter, date, link, graph, and index/log rules over a tree that keeps growing — so it runs as a read-only Python script rather than as per-page model reasoning (Step 0 below). What the script cannot decide is what this skill is actually for: which findings to auto-fix, which to leave for the user, whether two pages genuinely supersede one another, and whether a cluster of findings is a systemic pattern worth an error-book entry. Read the script's report, then do that work. This skill only ever writes within `wiki/` (including moves into `wiki/archived/`) and, for any connector-backed `libs//` (one with a `source.yaml` — see `CLAUDE.md`/`AGENTS.md` directory contract) where this user has local `access: write` (see `ckb-index-external`), within that connector's own agent-owned generated index (`index.md`/`entities/`/`graph/`/`log.md`). For a connector-backed `libs//` where this user is read-only (the default), findings against that index are reported only, never auto-fixed — the same access gate `ckb-index-external` applies to rebuilding applies here too. It never touches `linked/`, a git-copy `libs//`, or a connector's `source.yaml`/`source.local.yaml` — those stay immutable or user-owned — and it never touches this repo's own git remote; pushing the resulting changes is a separate, explicit step (see the final step below). ## Trigger phrases Use this skill when the user says: - "Lint" - "health-check the wiki" / "check the wiki" - "run the periodic/scheduled wiki check" Do **not** use this skill for "Ingest" / "Sync the wiki" (that's `ckb-ingest` — turning raw material into new wiki pages) or for "sync changes" / "sync with git" (that's `ckb-sync-changes` — reconciling this repo's own commit history with `origin`, no wiki content involved). ## How to run this skill Work through each check in order. A malformed page breaks every later check's ability to reason about it, so conformance comes first. Checks 1-9 below are written against `wiki/`, but the same checks also run a second time against each connector-backed `libs//`'s own generated index — scoped entirely to that one connector's `index.md`/`entities/`/ `graph/`/`log.md`. Auto-fixes there only happen where this user has local `access: write` for that source (see `ckb-index-external`); everywhere read-only, findings are reported but not applied. Findings and fixes there are logged in that connector's own `log.md`, never in `wiki/log.md`. A git-copy `libs//` (no `source.yaml`) and any `source.yaml`/ `source.local.yaml` are never touched by any of these checks. ### 0 — Run the checker script From the repository root: ```bash python3 "/scripts/lint_report.py" ``` Resolve `` to this skill's own directory. Flags: `--scope wiki|libs|all` (default `all`) to limit which trees are checked; `--today YYYY-MM-DD` to pin the date for reproducible runs; `--json` for a machine-readable report. Exit code is `0` when nothing was found and `1` when there are findings — read the report either way. The script is strictly read-only: it writes nothing, moves nothing, and runs no `git` commands. It covers the mechanical detection in checks 1, 2, 3, 4, 6, 7, 8, and 10 below — plus the structural half of check 5 (decision records) — across `wiki/` and every connector-backed `libs//` (reporting each one's `access:` level so you know where a fix is even permitted). Check 9, the semantic half of check 5, and every auto-fix-vs-report decision, are yours. The numbered checks below stay as the reference for *what each finding means and what to do about it* — you don't need to re-derive the detection by hand. Do read the pages the script flags: a finding is a pointer to a page that needs a decision, not the decision itself. ### 1 — Conformance check The script flags every non-reserved `.md` file under `wiki/` (i.e. excluding `index.md` and `log.md`) whose frontmatter is unparseable, absent, or missing a non-empty `type`. Treat flagged pages as unreliable input for the checks below rather than guessing at their intended type/content, and fix the frontmatter before acting on any later finding about the same page. ### 2 — Freshness check The script reports every page whose `last_updated` exceeds its `freshness_window_days`, and by how much. Suggest the user confirm or update the content — don't silently rewrite stale content yourself. ### 3 — Confidence decay The script reports pages already below 0.3 `confidence` (and any unparseable value). Decaying `confidence` on pages not reinforced by a new source since the last check is a write and a judgment call, so it stays yours — the script only surfaces where the floor has been crossed. ### 4 — Retention sweep The script reports `retention: low` pages older than 2x their `freshness_window_days` as archive candidates. Move them into `wiki/archived/` — never delete, always move — and log each move (see Rule B in `CLAUDE.md`/`AGENTS.md`) with a note explaining why. Check each candidate against recent use before moving it (see Edge cases). ### 5 — Supersession and decision records The script checks the *structure* of every `type: decision` page: a status from the vocabulary, a `decided_on` date where the status implies one, a `decided_by` (`unknown` counts — an omitted field doesn't), `affects` targets and supersession links that resolve, supersession set on **both** sides, `status: superseded`/`reversed` matched by a `superseded_by`, unique four-digit decision numbers, and any `review_on` date that has passed. Fix those directly — they're mechanical. A `review_on` that has come due is not a defect, though: report it so the user can decide whether to revisit, and never change a decision's substance yourself (`ckb-decide` → decisions are append-only). The *semantic* half stays yours: when two pages appear to cover the same entity or the same choice, check for contradictions. If one is clearly newer/better corroborated, add `supersedes` / `superseded_by` links between them. Preserve the older page rather than deleting it, but mark it stale. For two decisions, that judgment is exactly what the script can't make — it can tell you a link is one-sided, not that a link should exist. ### 6 — Orphan detection The script reports pages with no inbound links (`[[wikilinks]]` or `[markdown](path.md)` references from anywhere else in the tree). For each one, either add backlinks from relevant pages where an obvious connection exists, or move the orphan to `wiki/archived/` with a log note if no natural backlink does — that choice is the judgment the script leaves you. ### 7 — Graph consistency The script reports every edge in `wiki/graph/edges.json` whose `from`/`to` does not resolve to an existing page (plus malformed edges and invalid JSON). Remove or fix them; note what was removed rather than silently dropping entries. ### 8 — Index/log consistency The script reports subdirectories holding pages but no `index.md`, index files that don't list a page sitting next to them, and any change recorded in both a subdirectory `log.md` and the root `wiki/log.md` (per the Recursive Index & Log Convention). Fix missing index entries and duplicate log entries directly — these are the safest auto-fixes on the list. ### 9 — Error Book entry Record any systemic issue found above (a repeated broken pattern, a recurring format mismatch, the same kind of orphan appearing again) in `wiki/error-book.md` with its root cause, the fix applied, and the derived constraint that should prevent recurrence. A one-off, isolated issue doesn't need an Error Book entry — this is for patterns, not incidents. ### 10 — External source config check The script validates each `libs//source.yaml` (non-empty `connector` and `location`; non-empty `store` and `location` inside any `index:` block; a positive integer `refresh_interval_days`) and flags a `libs//` that ambiguously holds both real content files and a `source.yaml`. All of this is **report only** — `source.yaml` is never edited by any skill, and the ambiguous-content case is a configuration conflict for the user to resolve, not something to guess at. It also reports any connector-backed source whose generated index is overdue — newest `last_updated` in `libs//` older than its `refresh_interval_days` (default 30) — with how overdue it is, since a source two days past a 7-day interval is a different situation from one six months past a 30-day one. Relay that the same way whether or not this user has write access: a read-only user can't fix it, but knowing which source to chase the admin about is the actionable part. Never re-index here; that's `ckb-index-external`'s job, and suggesting it is as far as this check goes. Don't flag a missing `libs//source.local.yaml` as an issue — its absence is the correct, read-only default (see `ckb-index-external`), not a gap to report or fix. The script follows the same rule: it reads that file only to label each connector `access: read-only` / `access: write` in its report. ### 11 — Installed module checks If `ckb.yaml` lists installed modules, run whatever extra checks those modules define, and skip this step entirely when the file is absent or empty. Modules are optional by design: their absence is never a finding. For the `software` module specifically: - **Stale code maps** — a `type: repository` page whose `commit` is behind the current `HEAD` of its `src/` clone. Report how far behind; suggest `ckb-code-map`. A missing clone is **not** a finding — `src/` is gitignored and expected to be empty on a fresh checkout. - **Spec drift** — the four checks `ckb-spec` defines: root specs with empty `implemented_by`, repo-level specs implementing a missing or archived parent, one-sided `implements`/`implemented_by` links, and root specs older than the mapped commit of every repo implementing them. - **Remote-less repos** — a mapped repository page with no `resource:`, meaning a gitignored clone that exists nowhere else. All report-only. Never auto-fix any of these: each is a statement about intent, and only the user knows which side is correct. ### Auto-fix vs. report Auto-fix what can be done safely and mechanically: broken links, missing backlinks, stale flags, missing index entries, duplicate log entries, dangling graph edges. Report anything that needs a judgment call (supersession decisions, low-confidence content, ambiguous orphans) rather than guessing on the user's behalf. ### Final step — Remind to review and sync This is always the last step, every time this skill makes any change at all to `wiki/`. Close with a short reminder — do not sync or push anything yourself here: > "Lint complete — see `wiki/log.md` for what changed (auto-fixed: ...; > flagged for your review: ...). Please review the changes, and once > you're happy with them, say 'sync changes' to commit and push them to > `origin`." If any connector-backed `libs//` was also touched, mention it separately (its own `log.md`, not `wiki/log.md`) rather than folding it into the same sentence. If the lint pass made no changes at all (clean bill of health, nothing to fix or flag), skip this reminder — there's nothing to review or sync. ## Edge cases - **Wiki is empty or near-empty** — report that there's little to lint yet; don't fabricate findings to look thorough. A `total findings: 0` report is a valid outcome; say so plainly rather than hunting for something to say. - **A page's frontmatter is unparseable** (not just missing `type`, but invalid YAML) — the script reports it under conformance and skips it in the later checks rather than reasoning from a half-parsed page. Surface it prominently and fix the frontmatter first; a page can't be judged stale, orphaned, or archivable until it parses. - **Retention sweep would archive a page that's clearly still in active use** (e.g. linked from a very recent `workload/` entry) — flag it for the user to confirm rather than auto-archiving; recency of use can override a stale `last_updated`/`retention` combination. - **Supersession is ambiguous** (two pages disagree and neither is clearly newer/better corroborated) — report the conflict rather than guessing which one wins. - **Repeated run with nothing changed since the last lint** — produces the same report each time (pass `--today` to pin the date if you need a byte-identical one); don't invent variation just to seem active. - **The script errors out or isn't runnable** (no Python 3, unreadable tree) — say so and fall back to working the numbered checks by hand rather than reporting a clean bill of health you didn't actually verify. --- *Licensed under the Apache License, Version 2.0 — see [LICENSE](../../../LICENSE) at the repository root, or .*