| name | deep-lint |
| description | The heavy, infrequent (~monthly) maintenance pass for the wiki — a superset of `lint`. Use on /deep-lint, "monthly maintenance", "deep clean the wiki", "audit confidence", or "check my sources are up to date". Does everything `lint` does (dead links, orphans, unindexed pages, conflicts) PLUS reconciling query-time `flagged:` freshness flags, confidence coverage & correctness (changed + flagged + a sampled cold tail — never a full-vault LLM re-read), staleness scoring, capped freshness probes against the original ONLINE sources, the IDEAS.md Monitor review (its sole standing delegation), and a qmd refresh if enabled. Token-bounded by design; run ~monthly or when flags accumulate. Applies fixes only after confirming large or uncertain changes.
|
| user-invocable | true |
deep-lint — monthly deep maintenance
Goal
Keep the whole knowledge base correct, calibrated, and current in one bundled pass. Everything
expensive that routine /lint deliberately skips lives here, so /lint can stay cheap and frequent.
When to run
About once a month, or before a milestone (a big query session, an export, enabling qmd). It reads
pages and may fetch from the network, so it is heavy — do not run it after every ingest. Routine
integrity is /lint's job; deep-lint is the periodic deep clean.
Triggers
/deep-lint · "monthly maintenance" · "deep clean / deep audit the wiki" · "are my sources still current?"
Pipeline (read/scan first; confirm before large changes)
1 — Structural pass (everything lint does)
Run the full lint pipeline: index consistency, link health (dead links, orphans — maps//index/log
exempt), unresolved ## Conflicts / Open Questions, and the gap scan. Fix the cheap, unambiguous issues
(register unindexed pages, etc.) after the report.
- Customisation sanity (deep-lint only): if
wiki/user/Customisation.md exists, verify its frontmatter
parses, style: and role: each name a section defined in the file, every overrides line names a
conversational feature (style / formatting), and it stays within its ~120-line cap. Flag any drift for the
owner; never rewrite their preferences.
- Attic guard (existence-only):
attic/ and attic/MANIFEST.md exist, and the path:attic/ colour
group is present (apply-palette.py --check covers it). NEVER open attic contents — the attic is
explicit-instruction-only (CLAUDE.md §2.1); this check reads nothing inside it.
- Hard-wrap check: flag wiki pages with suspected mid-sentence hard wraps (a prose line ending in a
lowercase word or comma while the next line begins lowercase) — prose is one line per paragraph
(CLAUDE.md §1 line discipline; Obsidian renders single newlines as breaks). Skip non-rendered text:
frontmatter, code blocks, tables, and HTML-comment interiors. Fix on confirmation.
- Rendering & narrative sweep (two cheap greps): flag (a) raw
<tag> tokens in rendered wiki prose
outside backticks/comments — Obsidian parses them as HTML (CLAUDE.md §1); (b) correction-narrative
phrases in wiki/developments/ (e.g. "owner revision", "no longer", "earlier wording", "was removed") —
development docs read forward-facing (CLAUDE.md §12). Fix on confirmation.
2 — Flag-ledger reconciliation (Tier 2 → Tier 3)
Collect the query-time freshness flags accumulated since the last run — one cheap global grep:
grep -rn "^flagged:" wiki --include='*.md' (glob quoted — unquoted it breaks under zsh; verify
the probe against a known positive before trusting an empty result, per CLAUDE.md §11). For each flagged page: re-read it, resolve the
suspicion (update the page · re-grade its confidence · re-ingest its source via §3.1 tools ·
or clear a false alarm), remove the flagged: line, and list the resolution in the report.
The ledger is the run's first LLM-read priority — these pages were suspected by an agent that had
actually read them.
3 — Confidence coverage & correctness (per CLAUDE.md §4.6)
- Coverage: every non-
map page must carry a valid confidence. Cheap check:
grep -rL "^confidence:" wiki --include='*.md' then drop map/index/log. Assign any missing ones.
- Correctness: re-assess pages changed since the last deep-lint (compare
updated), any the
structural pass flagged, plus a random sample of the cold tail (~10–20 pages with updated
older than 90 days) — statistical coverage of pages no query ever visits, instead of an exhaustive
re-read. State the sampled fraction in the report ("sampled 15 of 240 cold pages") — a bound
never goes unstated. Prefer reading only frontmatter + the summary unless a fuller read is needed.
Keep one consistent standard; on a tie pick the lower tier.
- Apply the same rule everywhere: peer-reviewed/expert/verified →
authoritative; preprint/owner/
official-doc → high; reputable secondary → medium; promo/social/listing/transcript → low;
agent-speculative → very-low. Compiled pages cap at high.
4 — Staleness
Flag authoritative/high pages whose updated is old or that a newer page supersedes; down-weight or
add a ## Conflicts / Open Questions note, and route high-stakes stale claims to the human. Use updated
- supersession; do not silently rewrite.
- Archive candidates (suggest-only): flag pages that look retired — superseded and not cited by any
live work, or long-stale at low confidence — as suggestions for the attic (CLAUDE.md §2.1). NEVER
move anything yourself: archiving happens only on the user's explicit instruction.
5 — Freshness against online sources (cheap signals first)
For pages whose sources:/source_url point at an external URL, check whether the upstream materially
changed, cheapest signal first, and re-ingest only when it did:
- Cheap probes:
gh api repos/<o>/<r> (latest release / pushed_at / default-branch commit) for repos;
curl -sI <url> (Last-Modified / ETag) for pages; a version string in the page.
- Skip the immutable: published papers / PDFs / DOIs rarely change — don't re-fetch them.
- On a real change → re-ingest through the normal pipeline (defuddle /
curl / markitdown per §3.1).
Never WebFetch for re-ingest (it returns a summary, not the source). Merge updates into the existing
pages (don't duplicate), refresh that page's confidence and updated, and note the change.
- Bound and prioritise: cap fetches per run, ordering candidates by confidence × age ×
inbound-link degree (hub pages first — a stale hub misleads more queries than a stale leaf), and
state anything skipped, so "checked" never overstates coverage.
6 — Monitor review (the IDEAS.md delegation — Monitor section ONLY)
A /deep-lint invocation carries the owner's standing delegation to open only the ## 📡 Monitor
section of IDEAS.md — TODO, Ideas and Archive stay untouchable under the normal
explicit-instruction-only contract. For each Monitor caution: gather current vault evidence
(counts, log history, flag volume — real numbers, not impressions) and report a status:
promotion-ripe (propose a new TODO №, cross-referenced — the owner's word moves it) ·
dormant (evidence unchanged) · evidence-changed (summarise what moved). Writes to IDEAS.md
happen only after this run's normal confirmation, land as appended "(agent)" annotations (the
owner's wording is content-immutable), and every IDEAS.md write is reported in the reply's change
table (mirroring CLAUDE.md §12 system-file reporting) and listed in this run's log entry.
7 — qmd refresh (only if qmd is installed and enabled)
If qmd is in use, run qmd update && qmd embed so the search index reflects the month's changes
(see [[qmd-opt-in-design]]). Skip silently if qmd is absent.
8 — Registries & report
Update index.md for any pages added/renamed. Append one deep-lint entry to log.md (via shell).
Produce a report: structural fixes, confidence changes (with before→after), stale flags, sources
refreshed/skipped, qmd status.
Report format
## 🧹 Deep-Lint Report — YYYY-MM-DD
### Flags
- N `flagged:` pages reconciled (fixed · re-graded · re-ingested · cleared) — probe control-verified
### Structural
- N dead links · N orphans · N unindexed · N unresolved conflicts (fixed: …)
### Confidence
- N pages missing a level (assigned) · N re-tiered (e.g. [[X]] high→authoritative) · cold tail: sampled k of N (list any re-tiered)
### Staleness
- N stale high/authoritative claims flagged: [[..]] · N attic candidates suggested (user decides)
### Freshness
- N sources changed upstream & re-ingested: [[..]] · N checked, unchanged · N skipped (immutable/capped — stated)
### Monitor (IDEAS delegation)
- per caution: №n — promotion-ripe / dormant / evidence-changed (+ the evidence)
### qmd
- updated + embedded (or: not enabled)
Hard constraints
- Heavy and infrequent. Not part of routine ops;
/lint handles the frequent cheap pass.
- Human in the loop for large or uncertain changes (mass re-tiering, many re-ingests, conflict
resolutions) — report and confirm before applying.
- Re-ingest via the §3.1 capture tools (defuddle / curl / markitdown), never WebFetch.
- Token discipline: cheap signals before any fetch; scope LLM re-reads to ledger + changed +
sampled pages (never the whole vault); bound network work per run; never dump whole-file contents
to "check" them. Every bound and sample is stated in the report — no silent caps (CLAUDE.md §11).
- IDEAS.md boundary: the delegation covers the Monitor section ONLY, report-first; any IDEAS write
is confirmed, "(agent)"-marked, in the reply's change table, and in the log entry. TODO/Ideas/Archive
are never touched by this skill.
- Append
## [YYYY-MM-DD] deep-lint | <summary> to wiki/log.md (shell append, never Read+Edit).
- Report in British/UK English.
