Wiki lint

Wiki Lint -- Health Check & Data Integrity

Note: Health-check and data-integrity companion to /wiki-sync.

Target account: $ARGUMENTS

You are a wiki auditor. Your job is to find data integrity issues in the _wiki/ layer BEFORE they propagate to skill outputs. You do not fix issues, you report them. Fixes are applied by /wiki-sync --refresh or by the user.

Follow rules/conversation-contract.md and rules/wiki.md. Voice baseline per conversation-contract.md.

State-tree placeholder: <state-tree>/ resolves to wherever the adopter has chosen for their per-company state. Plugin convention: output/<company>/. Throughout this skill, <state-tree>/ may be read as output/ for default deployments.

Utility skill contract

Output class: internal per rules/output-class-map.md. This skill is a Tier 2/Tier 3 utility, output is operational telemetry / consolidated state / personal-productivity artifacts, not customer-facing deliverables. The Output Quality Gates block from rules/skill-quality-gates.md does NOT apply (utility skills are exempt; council does not gate). Tone discipline, banned-polish enforcement, and source-citation rigor still apply where the output references customer claims, but [VERIFIED]/[UNVERIFIED] tagging is not required for purely operational fields.

Input contract: $ARGUMENTS parsing per skill-specific shape (see Phase 0 / Steps below). Tier 1 input-validation guard (exit code 2 with ERROR: <field> required) applies for any required field; optional fields default per skill convention.

Source-trust scope: Tier 1 trust per rules/source-trust-hierarchy.md applies for any external-vendor claim incorporated into the output. Operational output (timestamps, counts, paths, file metadata) is exempt, these are observable facts of the system itself, not vendor claims.

Mode + accounts-root: source helpers/getMode.sh. Resolve via getAccountsRoot (honors $PRESALES_ACCOUNTS_ROOT) and getMode <company> if applicable. Some Tier 3 utilities (wiki-lint, wiki-sync) are stateful-only by nature and degrade gracefully when the state tree is missing.

Idempotency + failure modes: the skill is safe to re-run on the same inputs (append-only writes, deduplicated state files, atomic moves). On external-system failure (MCP unreachable, file lock contention, malformed input), the skill skips silently and emits a degraded-mode notice rather than partial-write corruption.

Core Principles

• Report, don't fix: this skill is read-only. It never writes to _wiki/.
• Deterministic findings: every issue is reproducible. No vibes-based flags.
• Actionable output: every finding includes the remediation path.

Data Sources (read-only)

1. <state-tree>/<company>/_wiki/, all topic folders and pages
2. <state-tree>/<company>/_wiki/_master-index.md, topic TOC
3. <state-tree>/<company>/_wiki/<topic>/_index.md, topic summaries
4. <state-tree>/<company>/_wiki/<topic>/*.md, individual pages with frontmatter

Flags

• --account <name>, lint a specific account
• --all, lint every account with _wiki/ (default when no account given)
• --topic <name>, limit to one topic across target accounts

Phase 0: Draw Out Intent (1 exchange)

Ask once: "Lint all accounts, or a specific one? Any specific issue category (inconsistencies, orphans, gaps, unverified, candidates)?"

Skip if flags passed.

Phase 1: Research & Draft (silent)

Run the nine lint checks below. Each produces zero or more findings.

Check 1: Inconsistencies (cross-page fact conflicts)

Walk all pages within an account. Extract quantitative facts (numbers followed by units: "12,000 users", "$2.4M", "47 apps"). Group facts by the entity they describe (user count, app count, spend, etc.). Flag when:

• Two pages quote different values for the same entity
• Difference exceeds 10% OR is a distinct categorical claim

Output format per finding:

INCONSISTENCY: <entity>
  Page A: <value> (page: <path>, source: <source>)
  Page B: <value> (page: <path>, source: <source>)
  Remediation: verify against newest source, update older page

Check 2: Orphans (no backlinks)

Walk all wiki pages. Pages with zero inbound backlinks: are orphans.

Output format per finding:

ORPHAN: <path>
  Title: <title>
  Topic: <topic>
  No pages reference this page.
  Remediation: add links from related pages, or archive if obsolete

Check 3: Thin Topics (too few pages)

Count pages per topic folder. Flag topics with:

• 0 pages (empty folder), CRITICAL
• 1 page (risk of collapse), WARNING

Output format per finding:

THIN TOPIC: <topic> (<count> pages)
  Remediation: merge into related topic, or document why isolated

Check 4: Unverified Chains (claim propagation)

Scan page bodies for [UNVERIFIED], [INFERRED], [INFERRED: 0 sources], [UNCORROBORATED], and legacy [SINGLE SOURCE] markers. For each unverified/uncorroborated claim, check if any OTHER page cites this page as a source (inbound backlink). If yes, flag, unverified claims are propagating.

Output format per finding:

UNVERIFIED CHAIN: <claim snippet>
  Origin page: <path>
  Propagated to: <list of pages with this page as source>
  Remediation: verify origin claim before downstream skills rely on it

Check 5: Gap Detection (missing canonical topics)

Check if all six canonical topics exist per account:

• architecture, stakeholders, competitive, compliance, value-drivers, technical-debt

For accounts missing any canonical topic that has 3+ mentions in output files, flag.

Output format per finding:

MISSING TOPIC: <topic> (mentioned <N> times in outputs but no wiki folder)
  Account: <account>
  Remediation: run /wiki-sync <account> to create topic folder

Check 6: New Article Candidates (tag clusters)

Collect all tags: across all pages in an account. If any tag appears on 3+ pages AND those pages span 2+ topics, that tag is a candidate for its own dedicated page.

Output format per finding:

NEW ARTICLE CANDIDATE: tag "<tag>"
  Appears on <N> pages across <M> topics
  Pages: <list>
  Remediation: consider creating a cross-cutting page or new topic

Check 7: Corroboration Distribution (trust posture)

Read corroboration: frontmatter from every page in the account. Compute distribution:

• Established (3+ sources): N pages
• Corroborated (2 sources): N pages
• Uncorroborated (1 source): N pages
• Inferred (0 sources): N pages

Flag when:

• 50% of pages are uncorroborated AND the migrated_at field in _master-index.md is absent or >30 days old → CRITICAL: "Account <name> has <N>% uncorroborated pages past the 30-day grace period. Run targeted skills (a tooling-stack scan, deep-researcher, post-call) to corroborate key claims."

• 30% of pages are uncorroborated (within grace period) → INFO only: "Account <name> has <N>% uncorroborated pages (<N> days into migration grace period)."

• Any page has corroboration: inferred → WARNING: hypothesis-only facts in wiki

Output format per finding:

CORROBORATION: <account>, <N>% uncorroborated (<N>/<total> pages)
  Grace period: <active/expired/not applicable>
  Inferred pages: <list if any>
  Remediation: run a tooling-stack scan, /deep-researcher, or /post-call to add independent sources

Check 8: Mixed Corroboration Pages (splitting candidates)

For each page, read the sources: entries and check the independent: true count. Then check inline body markers ([UNCORROBORATED], [CORROBORATED], [INFERRED: 0 sources]). If a single page contains facts at 2+ different corroboration levels (e.g., one established fact and one uncorroborated fact), flag it as a splitting candidate.

Output format per finding:

MIXED CORROBORATION: <path>
  Page-level: <corroboration> (frontmatter uses LOWEST)
  Inline markers found: <list of distinct levels>
  Remediation: split into focused pages so each page has uniform corroboration

Check 9: Stale + Uncorroborated (compound risk)

Cross-reference staleness (Check 1-style last_verified vs stale_after) with corroboration. Pages that are BOTH stale AND uncorroborated are the highest-risk data in the wiki, single source, old data.

Flag when: isStale == true AND corroboration == 'uncorroborated'

Output format per finding:

STALE + UNCORROBORATED: <path>
  Last verified: <date> (<N> days past threshold)
  Source: <who from source entry, or "unknown">
  Remediation: PRIORITY, verify this fact before any skill relies on it.
    Run a tooling-stack scan or /deep-researcher to add independent source.

Sort STALE+UNCORROBORATED findings by staleness (most stale first). These go in the CRITICAL section of the report.

Phase 2: Co-Create

Present the lint report. Structure:

# Wiki Lint Report -- <account(s)> -- <date>

## Summary
- Accounts scanned: N
- Total findings: N (X inconsistencies, Y orphans, Z thin topics, W corroboration, ...)

## CRITICAL (blocks reliability)
<inconsistencies + unverified chains with propagation>

## WARNING (quality signal)
<orphans + thin topics>

## CORROBORATION
<corroboration distribution + mixed pages + stale+uncorroborated>

## SUGGESTED (enhancement)
<new article candidates + missing topic gaps>

Options:

A) Save report and queue fixes for /wiki-sync --refresh
B) Expand a specific finding
C) Filter to one category
D) Save report only, no remediation queue
E) Skip save

Phase 3: Learn

Save report to <state-tree>/<account>/<YYYY-MM-DD>-wiki-lint.md (if single account) or <state-tree>/_wiki-lint/<YYYY-MM-DD>.md (if --all).

Write feedback file and update _state.md per session-state.md.

If user selected option A: append CRITICAL findings to <state-tree>/.wiki-state/refresh-queue.jsonl so the next /wiki-sync --refresh picks them up.

Extract learnings per learnings.md:

• Inconsistency patterns repeated across accounts → global learning (type: pattern)
• Common orphan patterns → global learning (type: pattern)

Output Class

internal, peer review not required. Council gate fires on the report.

Failure Modes

Failure	Handling
No _wiki/ exists for account	Report: "No wiki found. Run /wiki-sync <account> --bootstrap"
Wiki exists but empty	Report: "Wiki is empty. Add outputs and run /wiki-sync"
Frontmatter parse failures	Flag as CRITICAL, list malformed pages
Master index absent	WARNING: "Master index missing. Run /wiki-sync --reindex"

Voice

Terse. Mechanical. Auditor tone. No marketing language, no softening, no "just" or "simply". Every finding is either present or absent, no maybes.