wiki-lint

Lint — Wiki health check

Follow wiki/CONVENTIONS.md for format conventions, frontmatter, and links.

Language

Write the artifact in the user's language. Apply correct grammar and any required diacritics or script-specific characters. If the user's language is unclear, ask before generating output.

Project root

This skill writes artifacts at paths relative to the project root (the repo where the work happens), not the agent's current working directory.

• If invoked from inside the project, use the relative paths shown in this skill.
• If invoked from another directory (e.g., a sibling repo, or when the project lives elsewhere), prepend <project-root>/ to every artifact path.
• When the project root is ambiguous, confirm with the user via the harness question tool before writing.

Prompting

Follow the project-wide convention in CLAUDE.md / AGENTS.md ("Skill Prompting Conventions"). Use the harness's structured-question tool — AskUserQuestion (Claude Code), ask_user_question (Codex), or question (OpenCode) — for the decision points below. Use free-form text only where a path/name/value cannot be enumerated.

Decision point	Why structured	Suggested options
Scope (multi-select)	Affects what is checked	Frontmatter · Links · Drift · Empty subfolders · All
Auto-fix safe issues	Hard-to-undo edits	Report-only · Auto-fix · Ask per issue

Free-form prompts (no structured tool):

• Custom rule descriptions

No-pause mode: if the user has explicitly disabled mid-skill clarification, convert every structured prompt into an entry under Open questions (or equivalent) and proceed without blocking.

Query language alignment

For semantic lint checks, query in the wiki language. Determine it from .wiki-guardrails.yml (query_language or language), then from wiki frontmatter/index if guardrails are absent. Preserve exact names and code identifiers. Reports to the user should remain in the user's language.

Retrieval — prefer QMD when available

Use QMD (local hybrid search) for the semantic checks (orphans, missing cross-refs, contradictions). Setup is one-time per repo — see docs/wiki/qmd-setup.md. For purely structural checks (frontmatter, broken links), grep/glob is fine and faster.

• Use mcp__qmd__query (MCP) or qmd query --json --files (CLI) when looking for semantic neighbors of a page (orphan candidates, contradiction candidates, missing cross-refs).
• Always pass an intent: line to QMD describing what you are looking for.
• Do not run qmd embed / qmd update automatically — flag the need at the end of the lint if the wiki has changed and the index is stale.

Checklist

Go through the items in order. If the user asked for something specific (e.g., "just the links"), focus on that part.

1. Broken cross-refs

• Relative links [text](./path.md) that point to nonexistent pages.
• Fix the link OR create the missing page.

2. Orphan pages

• Wiki pages (except CONVENTIONS.md, index.md, log.md) with no inbound link in wiki/index.md.
• For each orphan candidate, run a QMD query with intent: page describing <topic of orphan> to find which existing pages should link to it.
• If it has valid content → add it to index.md and add cross-refs from semantically-adjacent pages.
• If irrelevant → suggest deletion to the human.

3. Frontmatter

All wiki pages must have:

Field	Required	Validation
title	yes	Present and not empty
audience	yes	One of: business, dev, ops, mixed
sources	yes	Non-empty list
updated	yes	ISO date. Flag if > 90 days
tags	yes	Non-empty list
status	yes	One of: draft, stable, stale

Typed pages exception (kind: decision / kind: rule): ADRs and Rules are governed by the typed-schema (wiki/_schemas/typed-schema.yaml), not this general table. Their status uses the typed enums (proposed | accepted | superseded | deprecated for decisions; active | deprecated for rules), and their frontmatter is validated by wiki-policy-check (validate-schema mode). When a page has kind: decision or kind: rule, do not flag its status against draft|stable|stale, and do not treat the general table's requirements as blocking for it — defer to the typed-schema. (sources/updated are still welcome on typed pages and are now allowed by the typed-schema ≥ v1.1.0.)

4. raw/ ↔ wiki/sources/ consistency

Cross-reference raw/index.md with wiki/sources/:

• Sources without summary — referenced in raw/index.md as ingested but missing <slug>.md.
• Summaries without source — wiki/sources/<slug>.md whose sources: points to a nonexistent file.

5. Audience boundary check

• Pages in wiki/apps/ should not contain business rules (pricing, policies, journeys, monetization). If they do, those rules must move to wiki/business/ and the apps/ page should keep only a cross-ref.
• Run a QMD query like intent: business rule (pricing/policy/monetization/cancellation) against the wiki collection (path-prefixed to apps/) to spot leakage inside the wiki itself.
• For product/code repos that the project keeps as siblings (and that the project's convention says should hold only technical rules), audit them with grep / Read rather than indexing them into QMD. Indexing those repos blurs the "wiki is canonical" boundary by inviting agents to treat product-repo prose as authoritative. Surface any business-rule language found as a candidate for migration into wiki/business/.

6. Missing cross-refs

• For each substantive wiki page, run a QMD query for its title/topic and inspect the top 5-10 hits. Pages that semantically belong together but do not link should be flagged.
• Suggest to the human (do not fix automatically — it may introduce noise).

7. Contradictions

• For each topic that appears on multiple pages, run QMD for a hyde-style query of the canonical statement (e.g. hyde: The cancellation policy is X hours with Y consequence) and compare the top hits.
• If pages contradict each other → flag with a note on the page.

8. Outdated status

• draft that could be stable (complete and validated content).
• stable with updated > 90 days → consider marking as stale.

9. index.md statistics

• Does the page count match reality?
• Are page descriptions up to date?

10. QMD index health (only if QMD is configured)

• Call mcp__qmd__status (or qmd status).
• If needsEmbedding > 0 → tell the owner to run qmd embed.
• If file count in wiki/ differs significantly from totalDocuments for the wiki collection → tell the owner to run qmd update.

Behavior

• Simple fixes (frontmatter, links, updated) → do them automatically.
• Content changes → ask the human first.
• Response to the human: focus on the actionable:
  1. Pending items that need a human decision
  2. Improvement opportunities
  3. Numerical summary (total issues / automatic fixes)
  4. QMD reindex commands the owner needs to run (if any)
• Do not list all automatic fixes in the response — the detail goes into log.md.

Logging

Update wiki/log.md (insert at the top, after the header):

## [YYYY-MM-DD] lint | health check

### Automatic fixes
- ...

### Pending (human decision)
- ...

### Suggestions
- ...

### QMD reindex needed
- qmd update / qmd embed (only if applicable)

Typed-schema validation (opt-in)

When the wiki target follows the typed-schema pattern (ADRs, Rules, Events validated against a central wiki/_schemas/typed-schema.yaml), the lint can optionally include a schema check by invoking the wiki-policy-check skill in validate-schema mode.

Modes

Read lint.includeSchema from the wiki's .wiki-guardrails.yml:

Mode	Behavior	When to use
off (default)	Schema validation skipped entirely. Zero overhead. No mention in report.	Wiki without typed-schema; safe global default to avoid regressions in projects that don't use the pattern.
warning	Run validate-schema; report schema warnings as a structured field; do NOT block (LINT_RESULT: PASS even if there are schema issues).	Initial rollout — surfaces drift without breaking the ETL or block ingest.
block	Run validate-schema; fail the lint (LINT_RESULT: FAIL) if there are any schema errors, duplicate IDs, or orphan refs.	After 1-2 sprints of stable warning mode + ≥80% of projects have ≥1 valid ADR/Rule — see promotion criteria below.

Activation

1. Check if <wiki-path>/_schemas/typed-schema.yaml exists.
2. Read .wiki-guardrails.yml → lint.includeSchema (default off if missing).
3. If mode != off, invoke:

   bun ~/.claude/skills/wiki-policy-check/scripts/validate-schema.ts \
     --wiki-path <wiki-path> \
     --format json
   

4. Parse the JSON output:
   • summary.invalid + summary.duplicate_ids + summary.orphan_refs → total schema issues.
   • Each validations.decisions[i].errors, validations.rules[i].errors, validations.events[i].errors → individual issues.

Lint report integration

Add to the lint report (in wiki/log.md if running automated, or in the conversation response):

## [YYYY-MM-DD] lint | health check

### Schema validation (mode: warning|block)
- schema-warnings: <N>   (or schema-errors if mode=block)
- valid: <ADRs>+<Rules>+<events>
- invalid: <N> (with file+field+message details for each)
- duplicate_ids: <N>
- orphan_refs: <N>

### Automatic fixes
- ...

When mode is off, omit this entire section.

Promotion criteria (warning → block)

Promote a wiki from warning to block when all are true:

1. ≥3 projects in the wiki have ≥1 valid ADR or Rule (proves the pattern landed).
2. 2 consecutive sprints with warning mode + zero blocking schema errors retroactively (proves the schema fits real data).
3. Owner explicitly confirms (one-line PR comment or commit message acknowledging the promotion).

Document the promotion in the wiki's wiki/log.md and bump the schema's version field if any schema constraint was relaxed for the promotion (rare).

Boundaries

• This is opt-in per-wiki (via .wiki-guardrails.yml), not global. Wikis without the typed-schema pattern see zero behavior change.
• The skill wiki-policy-check --mode validate-schema is the authoritative source for what's valid. This skill (wiki-lint) just orchestrates the call and integrates output.
• Mode block should never be the global default — wikis without typed-schema.yaml would error.

References

• wiki-policy-check §Mode 2 — script-driven validator (epic #4 Story 02 do wiki-service).
• ADR-0009 typed-schema (no knowledge-center repo) — schema spec + 13 locked decisions.
• Epic #4 Story 05 (wiki-lint-integration-gradual) — esta integração.