agentleFS
sponge-b0bsponge-b0b/Polaris/.agents/skills/wiki-lint/SKILL.md

wiki-lint

Skill4 starsChanged 4 months agoApache-2.0View on GitHub

Audit the Living Entity Wiki for structural integrity, citations, source conflicts, drift, stale questions, and classification hygiene.

44 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use wiki-capture, wiki-status and 9 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • jehrhardtSkill

    wiki-capture

    Quickly capture raw thoughts, links, images, or notes to today's Obsidian daily note from anywhere in Pi. Use when the user wants to jot something down for later wiki processing.

    Also in 6 projects that use this

  • nexuschainsSkill

    wiki-status

    Reports the current state of the wiki vault — page counts, category breakdown, hub pages, orphans, stale entries, and a delta showing what has changed since the last ingest. Use this skill when the operator asks "what's the status", "wiki dashboard", "how many pages", "what's stale", "what's been ingested", "show me the delta", or "wiki health overview". Also surfaces structural insights (top hubs, fragmented clusters, bridge pages) when the operator asks "wiki insights", "what's central", or "show me the hubs". Read-only: this skill reports and recommends; it does not modify any files.

    Also in 5 projects that use this

  • nexuschainsSkill

    cross-linker

    Scans the wiki vault and adds missing [[wikilinks]] between pages that are related but not yet connected. Use this skill when the operator says "link my pages", "find missing links", "cross-reference the wiki", "connect my wiki", "add wikilinks", or after any large ingest to weave new pages into the existing knowledge graph. Also trigger when orphaned pages need connecting or when wiki-lint reports fragmented tag clusters. This is a write-heavy skill — it modifies page files to insert links, unlike wiki-lint which only reports.

    Also in 4 projects that use this

  • Ivy-Chen1999Skill

    wiki-setup

    Initialize a new Obsidian wiki vault with the correct structure, special files, and configuration. Use this skill when the user wants to set up a new wiki from scratch, initialize the vault structure, create the .env file, or says things like "set up my wiki", "initialize obsidian", "create a new vault", "get started with the wiki". Also use when the user needs to reconfigure their existing vault or fix a broken setup.

    Also in 5 projects that use this

  • bozhouDevSkill

    wiki-init

    Use when bootstrapping a new personal wiki for any knowledge domain — research, codebase documentation, reading notes, competitive analysis, or any long-term knowledge accumulation project.

    Also in 7 projects that use this

  • Ivy-Chen1999Skill

    wiki-research

    Autonomously research a topic via multi-round web search, synthesize findings, and file structured results into the Obsidian wiki. Use this skill when the user says "/wiki-research [topic]", "research X", "find everything about Y", "do a deep dive on Z", "autonomous research on X", or wants comprehensive, web-sourced knowledge on a topic filed directly into their wiki.

    Also in 4 projects that use this

  • +1 more from nexuschains
  • +3 more from Ivy-Chen1999

The file

Show its rules and text

We split this skill into the rules it gives an agent

38 rules. 0 are common, 26 are distinctive, and 12 are very specific to this project.

  • 0

    Common

    Most of the 35 edited versions we read keep these.

  • 26

    Distinctive

    This author's own choices. Worth a look.

  • 12

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Do not classify downstream drift until authoritative-source consistency is understood.

    line 28
  2. Distinctive:

    Do not invent missing rationale or topology.

    line 59
  3. Very specific:

    Use wiki/_schema.md and wiki/_template.md.

    line 65
  4. Very specific:

    Use provenance allowed by wiki/_template.md.

    line 88
  5. Distinctive:

    Do not delete claims merely because a citation is broken or stale.

    line 92
  6. Distinctive:

    Do not select a winner or repair the disputed claim.

    line 121
  7. Very specific:

    Do not report [source-conflict] merely because an accepted ADR still says implementation is pending, not yet realized, or equivalent while …

    line 125
  8. Distinctive:

    only the ADR's descriptive realization/status statement is stale.

    line 132
  9. Distinctive:

    Do not use this rule when implementation contradicts the ADR's actual decision.

    line 145
  10. Distinctive:

    Do not infer realization from weak or merely suggestive evidence.

    line 180
  11. Very specific:

    Do not use [code-drift] for inability to prove a claim.

    line 186
  12. Distinctive:

    When expected implementation cannot be found on the current branch, inspect relevant open GitHub work when useful.

    line 190
  13. Distinctive:

    If an open Spec/ticket explicitly tracks missing realization:

    line 194
  14. Distinctive:

    treat it as pending rather than unexplained.

    line 196
  15. Distinctive:

    do not switch branches;

    line 198
  16. Distinctive:

    Do not fabricate resolution.

    line 237
  17. Very specific:

    If underlying authorities disagree, use [source-conflict].

    line 243
  18. Distinctive:

    If authorities agree and only derived wiki state is stale, use the appropriate drift finding.

    line 245
  19. Distinctive:

    Avoid duplicate findings for the same root cause.

    line 247
  20. Very specific:

    Do not report ignored paths as process or unclassified, and do not infer that an unfamiliar directory is ignored when it is not explicitly …

    line 273
  21. Very specific:

    Use $classify-doc only for existing non-ADR documents inside the Living Entity Wiki document universe.

    line 275
  22. Distinctive:

    Prefer the root cause:

    line 279
  23. Distinctive:

    Do not emit duplicate downstream findings when one finding explains them.

    line 295
  24. Distinctive:

    Do not treat architectural claim changes, source selection, realization/lifecycle transitions, or topology changes as mechanical.

    line 322
  25. Very specific:

    does not edit wiki/log.md.

    line 363
  26. Distinctive:

    does not create a commit.

    line 364
  27. Distinctive:

    Do not log lint runs or issue counts.

    line 372
  28. Distinctive:

    treat GitHub issues as architectural authority.

    line 391
  29. Distinctive:

    treat unmerged work as current implementation.

    line 392
  30. Distinctive:

    Before reporting a clean result, build a working Wiki Audit Coverage inventory from the repository's current canonical registries/sources.

    line 405
  31. Very specific:

    every active wiki/index.md entity row and every entity page.

    line 407
  32. Very specific:

    every inline source: citation on active entity pages.

    line 408
  33. Distinctive:

    every authoritative source referenced by those citations whose lifecycle/eligibility must be checked.

    line 409
  34. Very specific:

    every Strict Invariant/Planned/Open Question/Boundary Rationale claim requiring the applicable audit stage.

    line 410
  35. Distinctive:

    every active entity pair/scope implicated by a possible cross-entity contradiction.

    line 411
  36. Very specific:

    every project-owned docs/ file remaining in the classification universe after validated docs/.wikiignore exclusions are applied.

    line 412
  37. Distinctive:

    Before a clean result require:

    line 426
  38. Distinctive:

    When findings exist, the same coverage discipline still applies: do not stop after the first issue if other independently inspectable audit …

    line 437

“Common” is measured: kept by at least 6 in 10 of the 35 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

Wiki Lint

$wiki-lint independently audits accumulated Living Entity Wiki state.

$wiki-sync maintains one change. $wiki-lint audits the whole.

A clean run reports only. Do not mutate the wiki, append wiki/log.md, or commit unless applying an explicitly allowed mechanical fix.

Audit Order

Run in order:

  1. structural integrity;
  2. citation resolution and eligibility;
  3. authoritative-source consistency;
  4. document/wiki drift;
  5. implementation drift;
  6. Open Questions;
  7. cross-entity contradictions;
  8. document classification.

Do not classify downstream drift until authoritative-source consistency is understood.

1. Structural Integrity

wiki/index.md is the active-entity registry.

Report [structural] for:

  • entity/index mismatches;
  • duplicate Entity IDs or active scopes;
  • invalid Implementation values;
  • invalid/missing Routing Anchors;
  • pending when implementation clearly exists;
  • present when implementation cannot reasonably be found;
  • retired/tombstone pages under wiki/entities/;
  • obsolete metadata/frontmatter;
  • invalid or unsupported docs/.wikiignore syntax;
  • invalid entity-page structure;
  • missing or invalid Boundary Rationale.

Allowed implementation states:

present
pending

A pending entity normally has no implementation Routing Anchor.

Entity pages must follow wiki/_template.md.

Do not invent missing rationale or topology.

2. Citation Resolution and Eligibility

Entity-document relationships exist only through inline source: citations.

Use wiki/_schema.md and wiki/_template.md.

Report:

  • [broken-doc-citation] — cited docs/... path no longer resolves;
  • [invalid-citation] — source type was never valid for that section;
  • [stale-citation] — source was valid but its lifecycle/classification changed.

Core eligibility:

Strict Invariants

  • accepted ADR;
  • docs/current/.

Planned

  • proposed ADR;
  • docs/proposed/;
  • accepted ADR whose realization is still pending.

Rejected Approaches, Open Questions, Boundary Rationale

Use provenance allowed by wiki/_template.md.

A docs/... path matched by docs/.wikiignore is outside the Living Entity Wiki source universe and is not an eligible document citation.

Do not delete claims merely because a citation is broken or stale.

3. Authoritative-Source Consistency

Authority is claim-specific:

  • implementation → what currently exists/behaves;
  • accepted ADR → active architectural decision;
  • docs/current/ → current architectural description;
  • entity pages → derived knowledge, never authority.

Report [source-conflict] only when applicable authorities normatively disagree about architecture or when competing authoritative claims about current behavior cannot be reconciled without judgment.

Examples:

  • incompatible architectural invariants;
  • conflicting canonical owners/paths;
  • incompatible boundary or dependency rules;
  • one authority requires behavior another forbids;
  • authoritative current-state descriptions materially disagree and no deterministic lifecycle update explains the difference.

For each [source-conflict], include:

  • entity/claim;
  • conflicting sources;
  • what each says;
  • implementation evidence;
  • why the disagreement matters.

Do not select a winner or repair the disputed claim.

Realization-Status Rule

Do not report [source-conflict] merely because an accepted ADR still says implementation is pending, not yet realized, or equivalent while current implementation clearly realizes its accepted normative decision.

When:

  1. the ADR remains accepted;
  2. its normative decision agrees with the implementation;
  3. implementation evidence clearly realizes that decision; and
  4. only the ADR's descriptive realization/status statement is stale;

then classify the condition as deterministic [doc-drift], not [source-conflict].

Report:

  • the accepted decision;
  • evidence that implementation realizes it;
  • the stale realization/status statement;
  • required owner: $to-adr-doc.

The derived wiki may already reflect the realized invariant without creating a source conflict when its claim agrees with both the ADR's normative decision and current implementation.

Do not use this rule when implementation contradicts the ADR's actual decision.

4. Document and Wiki Drift

Report [doc-drift] when meaning or lifecycle state has become stale while underlying architectural authority remains unambiguous.

Examples:

  • entity claim no longer reflects its valid source;
  • accepted ADR realization status remains pending after clear realization;
  • current documentation describes an obsolete state while authority and implementation agree on the replacement.

For entity claims sourced from docs/current/:

  • confirm the source remains current;
  • ensure no [source-conflict];
  • compare the claim with current source meaning.

For Planned entries sourced from proposed material:

  • compare against the current proposal;
  • report drift when it changed, disappeared, or was substantively rewritten.

Accepted Implementation-Pending Decisions

For accepted ADR-backed Planned entries:

  1. confirm the ADR remains accepted;
  2. determine whether realization is still pending;
  3. inspect strong implementation evidence;
  4. if clearly realized:

    • stale ADR realization statement → [doc-drift], owner $to-adr-doc;
    • stale wiki Planned/Implementation: pending state → [doc-drift] or [structural] as applicable.

Do not infer realization from weak or merely suggestive evidence.

5. Implementation Drift

Report [code-drift] when implementation materially contradicts an active architectural invariant whose authorities otherwise agree.

Do not use [code-drift] for inability to prove a claim.

Active Implementation Work

When expected implementation cannot be found on the current branch, inspect relevant open GitHub work when useful.

Issues are workflow-status evidence only, never architectural authority or implementation proof.

If an open Spec/ticket explicitly tracks missing realization:

  • treat it as pending rather than unexplained;
  • inspect its declared work branch read-only when useful;
  • do not switch branches;
  • unmerged implementation remains in progress, not current implementation.

Closed issues are not implementation proof.

Evidence

For mechanically observable invariants, use:

  • source;
  • tests;
  • executable architecture checks;
  • $codegraph;
  • $codebase-memory-mcp;
  • configuration.

For intent-level invariants, report [code-drift] only when contradictory evidence exists.

Otherwise report:

no contrary implementation evidence found

not verified.

6. Open Questions

Report [stale-question] when an Open Question deserves deliberate review because of age, changed context, or apparent later resolution.

Approximately 60 days is a heuristic, not an expiry rule.

A stale question may be:

  • resolved;
  • confirmed open;
  • converted into another durable section;
  • removed because it is no longer meaningful.

Do not fabricate resolution.

7. Cross-Entity Contradictions

Scan active entity claims for material contradictions.

If underlying authorities disagree, use [source-conflict].

If authorities agree and only derived wiki state is stale, use the appropriate drift finding.

Avoid duplicate findings for the same root cause.

8. Document Classification

Validate docs/.wikiignore against the exclusion grammar in wiki/_schema.md before using it to construct the classification universe. Invalid syntax is [structural]; do not treat an invalid line as permission to omit a path.

Construct the document-classification universe as:

all project-owned files under docs/
- docs/.wikiignore
- paths explicitly matched by valid docs/.wikiignore entries
= files subject to Living Entity Wiki classification

For every file remaining in that universe, derive classification from:

  • docs/adr/ plus ADR status;
  • docs/current/;
  • docs/proposed/;
  • docs/research/;
  • docs/reference/;
  • docs/process/.

Report [unclassified-doc] for any remaining project-owned file whose classification cannot be derived from those rules.

Do not report ignored paths as process or unclassified, and do not infer that an unfamiliar directory is ignored when it is not explicitly matched by docs/.wikiignore.

Use $classify-doc only for existing non-ADR documents inside the Living Entity Wiki document universe.

Finding Priority

Prefer the root cause:

[source-conflict]
    ↓
[broken-doc-citation]
    ↓
[stale-citation] / [invalid-citation]
    ↓
[doc-drift]
    ↓
[code-drift]

Exception: stale realization metadata that satisfies the Realization-Status Rule is [doc-drift], not [source-conflict].

Do not emit duplicate downstream findings when one finding explains them.

Resolution Rules

$wiki-lint reports judgment-bearing findings. It does not decide architecture.

Never automatically resolve:

  • genuine [source-conflict];
  • [code-drift];
  • semantic [doc-drift];
  • ambiguous citation findings;
  • stale questions;
  • cross-entity semantic contradictions;
  • topology or Boundary Rationale.

Mechanical Fixes

Apply a fix only when exactly one correction is unambiguous and no architectural judgment is required.

Examples:

  • stale link after known rename;
  • formatting damage;
  • duplicate registry row;
  • Routing Anchor changed only by established path rename.

Do not treat architectural claim changes, source selection, realization/lifecycle transitions, or topology changes as mechanical.

For stale accepted-ADR realization status, report $to-adr-doc as owner rather than editing the ADR directly.

Reporting

Use:

[source-conflict]
[code-drift]
[doc-drift]
[stale-citation]
[invalid-citation]
[broken-doc-citation]
[unclassified-doc]
[stale-question]
[structural]

Each finding includes:

  • entity/claim;
  • evidence/sources;
  • relevant implementation evidence;
  • relevant open work when applicable;
  • why it matters;
  • required next action/owner.

End with counts by finding type.

Clean result:

Wiki lint: 0 issues found

Logging and Commits

A report-only or clean run:

  • does not edit wiki/log.md;
  • does not create a commit.

For an allowed mechanical fix:

  • append one semantic wiki/log.md entry;
  • land fix and log atomically;
  • defer commit ownership to the calling workflow when one exists.

Do not log lint runs or issue counts.

Related Skills

  • $wiki-sync — per-change synchronization;
  • $to-adr-doc — ADR lifecycle and realization-status updates;
  • $to-doc — new non-ADR documents;
  • $classify-doc — existing non-ADR classification;
  • $wiki-synthesize — higher-inference synthesis.

Out of Scope

$wiki-lint does not:

  • bootstrap the wiki;
  • decide entity boundaries;
  • settle genuine source conflicts;
  • rewrite architectural decisions;
  • directly update ADR realization/lifecycle state;
  • treat GitHub issues as architectural authority;
  • treat unmerged work as current implementation;
  • infer intent-level compliance from absence of evidence;
  • maintain obsolete entity metadata;
  • classify docs/.wikiignore-excluded documentation as Living Entity Wiki source material;
  • log clean runs;
  • perform cross-entity synthesis.

Its job is to determine whether the Living Entity Wiki can be trusted, distinguish genuine authority conflicts from ordinary lifecycle drift, and route correction to the proper owner.

Transition-Bound Wiki Audit Coverage

Wiki lint: 0 issues found is an exhaustive claim and requires a materialized audit universe. Zero findings among the surfaces that happened to be inspected is not a clean audit.

Before reporting a clean result, build a working Wiki Audit Coverage inventory from the repository's current canonical registries/sources. At minimum account for the candidate universes relevant to the eight audit stages:

  • every active wiki/index.md entity row and every entity page;
  • every inline source: citation on active entity pages;
  • every authoritative source referenced by those citations whose lifecycle/eligibility must be checked;
  • every Strict Invariant/Planned/Open Question/Boundary Rationale claim requiring the applicable audit stage;
  • every active entity pair/scope implicated by a possible cross-entity contradiction;
  • every project-owned docs/ file remaining in the classification universe after validated docs/.wikiignore exclusions are applied.

Each candidate receives a working disposition:

Candidate: WA-<n>
Audit stage: <1..8>
Surface/claim: <exact identity>
Disposition: <checked | finding:<type/id> | not-applicable>
Evidence/reason: <direct evidence or exact N/A reason>

Candidates may be generated by more than one stage when genuinely necessary; deduplicate identical stage+claim obligations rather than silently dropping them.

Before a clean result require:

Audit candidates: <n>
Coverage rows: <n>
Missing/unclassified candidates: 0
Unchecked candidates: 0
Not-applicable rows without reason: 0
Findings: 0

When findings exist, the same coverage discipline still applies: do not stop after the first issue if other independently inspectable audit stages remain. A concise finding report is still allowed; the full working coverage table need not be persisted.

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.