| name | okf-lint |
| description | Semantic linter for OKF knowledge bundles — finds what a mechanical validator can't see (contradictions, index/log drift, duplicate concepts, taxonomy inconsistencies, stale content) and writes a severity-ranked report without modifying the bundle. Use whenever the user wants a knowledge bundle or docs directory audited, linted, or sanity-checked. |
OKF Lint
Reviews an existing OKF knowledge bundle for semantic problems: docs that
contradict each other, indexes that drifted from reality, concepts that
duplicate each other, taxonomy chaos, and content weirdness. It is the
companion to okf-docs: that skill writes and structurally validates
bundles; this one reads them with a critical eye.
Structural conformance (frontmatter parses, type present, reserved
filenames, log date format) is okf-docs' job via its validate_okf.py.
Don't re-litigate those rules here — but if the bundle is so structurally
broken that semantic review is pointless, say so in the report and stop.
This skill never edits the bundle. The deliverable is a report; the user
decides what to fix.
Why a model-driven linter
The valuable findings — two docs disagreeing about a join key, a "Playbook"
that contains no steps, two concepts that are really the same table — cannot
be detected by pattern matching. They require actually reading the corpus
and holding it in mind. The bundled script exists only to make the
mechanical part cheap and deterministic; the reading is the job.
Workflow
1. Locate the bundle root. Usually a knowledge/ or docs/ directory
whose files carry OKF frontmatter. If the user pointed at a specific
directory, use it. If several candidates exist, ask once. Check for a
.okfignore at the root; ignored files are out of scope for the lint pass
(the inventory script already skips them) — don't report findings on them,
though you may still read them as evidence.
2. Run the inventory script:
python scripts/okf_inventory.py <bundle-root>
It prints a digest: file census with frontmatter, index-vs-directory drift,
tag/type censuses with near-duplicate suspects, duplicate resource URIs,
timestamp anomalies, log-order and log-target problems, placeholder hits,
empty sections, and orphan candidates. Everything it prints is a lead, not
a finding. Leads must be verified by reading before they enter the report;
a TODO inside a fenced code example is not a placeholder leftover.
3. Read the bundle. This is the heart of the pass. Read every concept
doc (for large bundles see "Big bundles" below), building a mental model of
the domain as you go, and look for:
- Contradictions — the same fact stated differently in two places: join
keys, column types, SLAs, rate limits, owners, definitions of a metric,
whether something is included or excluded. Cross-check schema tables that
describe the same asset. This is the highest-value finding class.
- Overlap / duplication — two concepts that describe the same thing
(same
resource, near-identical titles, or bodies covering the same
ground). Bundles rot fastest through parallel docs that then diverge.
- Drift — index bullet descriptions that no longer match the concept's
frontmatter or content;
log.md claiming changes the files don't show
(or silent about files that clearly changed); timestamp older than the
doc's latest log mention; future timestamps.
- Taxonomy hygiene — tags and
type values that are near-duplicates
(sales/Sales, Playbook/playbook/Runbook), or so inconsistent
that filtering by them would fail.
- Content weirdness — template leftovers and placeholders, empty
sections, descriptions that merely restate the title, bodies that don't
match their
type (a Playbook with no steps, a Table with no schema),
suspiciously thin or duplicated passages.
- Relationship claims — prose in doc A asserting something about doc B
("joined on X", "part of dataset Y") that doc B doesn't support.
4. Write the report as <YYYY-MM-DD>-lint-<bundle-slug>.md, the naming
the review family uses (../_shared/review-interfaces.md, "The report",
which also owns the same-day -2 suffix). Where it lands depends on where
the bundle is:
- Bundle under
docs/ (docs/planning/, docs/epics/, or docs/
itself) — the report joins the reviews at
docs/reviews/<YYYY-MM-DD>-lint-<bundle-slug>.md, so one directory holds
every report the repo has produced and a reader sorting it by name sees
the lint pass in the same timeline as the reviews.
- Bundle anywhere else (
knowledge/, a data directory) — the report
stays next to the bundle root, never inside it: a report inside the
bundle would itself be a non-conformant concept.
- Bundle root is the project root — there is no "next to", so write
reviews/<YYYY-MM-DD>-lint-<bundle-slug>.md under that root.
Whenever the report lands inside a bundle's own tree — the last case, or a
docs/ that is itself a bundle root — add reviews/ to that bundle's
.okfignore, creating the file if it is missing. This is the one write to
the bundle tree the skill is allowed, and without it the next
validate_okf.py run fails on a report that was never meant to be a
concept. Ignore one directory rather than a filename pattern: a pattern
with no / matches any path segment, so reviews/ covers the whole
directory wherever it sits and keeps covering it as reports accumulate.
5. Close the run per ../_shared/feedback-interfaces.md — the reflex for what
this run taught about this skill, as opposed to about the bundle. Read it; it is
silent unless something clears both its filters, which most runs is nothing.
Report structure
Use this template:
# OKF Lint Report — <bundle path>
Date: <YYYY-MM-DD> · Files read: <n>/<total> · Verdict: <one line>
## Summary
<2-4 sentences: overall health, the one or two things most worth fixing.>
## Findings
### High — contradictions & misleading content
#### H1. <short title>
- **Where:** `file.md:line` ↔ `other.md:line`
- **Evidence:** quoted lines from each side
- **Why it matters:** <one sentence>
- **Suggested fix:** <one sentence>
### Medium — drift & duplication
#### M1. ...
### Low — hygiene
#### L1. ...
## Checked and clean
<Bullet list of check categories that came back clean,
' >
Severity guide: High = a reader following the docs would be actively
misled (contradictions, wrong relationships, duplicate concepts that have
diverged). Medium = the bundle's self-description is out of sync (index
drift, stale timestamps/log, non-diverged duplication, taxonomy splits that
break filtering). Low = cosmetic hygiene (placeholders, empty sections,
weak descriptions).
False-positive discipline
Every finding must carry quoted evidence — for contradictions, quotes from
both sides. If you can't quote it, don't report it. Domain docs often
contain apparent tensions that are actually correct (a raw table and a
filtered view legitimately report different row semantics); read enough
context to rule that out before flagging.
A clean bundle gets a short, confident report. Finding count is not a
quality metric — do not pad Low findings to look thorough, and do not
promote hygiene nits to Medium to make the report feel weighty.
Big bundles
Above roughly 40 concept files, full reading may not be practical. Read
fully: everything the inventory digest flagged, plus every directory
involved in cross-links between flagged files. Sample the rest (at least
one doc per directory, preferring the largest). State explicitly in the
report header which parts were read fully vs sampled — an unread area must
never silently pass as clean.
