Imported from escogido/knowledge-cairn (system/.agents/skills/documentation-auditor/SKILL.md). Install upstream with npx skills add escogido/knowledge-cairn --skill documentation-auditor. Copyright stays with the author.

Documentation Auditor

Purpose

Perform an out-of-cycle documentation integrity audit.

This skill checks whether AI-context documentation is internally consistent and whether it matches current repository evidence, excluding ../../../ai-context/archive/.

It may inspect code, tests, scripts, schemas, generated artifacts, and relevant evidence to determine which documentation is stale.

Distinction From Finalization

Finalization answers:

What changed during the completed task, and which durable docs must be updated because of that task?

Documentation Audit answers:

Do the docs currently contradict each other or the code/repository evidence, regardless of the current task?

Do not use this skill as a substitute for ordinary task Finalization. Do not automatically run this skill during Finalization.

Read-Only Rules

This skill is read-only.

The skill may propose exact documentation patches, but must not apply changes. If the user asks to apply fixes, the auditor still reports only; applying targeted documentation fixes is a separate invoker action after the audit, with explicit user authorization.

A proposed patch lands only on what the project wrote: its General, Situational, and Operational content, the indexes that grow with it, and its own documentation outside ../../../ai-context/. Never propose one against Cairn's own shipped text, which the project did not write and an upgrade replaces, so a local patch forks it silently:

• ../../../AGENTS.md;
• anything under ../../../ai-context/methodology/ or ../../../.agents/;
• every README.md under ../../../ai-context/, and ../../../ai-context/operational/index.md;
• ../../../ai-context/knowledge-cairn.md.

A discrepancy involving one is still a finding: report it, and where the fix belongs on the project's side, propose it there.

Preferred Git Context

• Check the current branch.
• If running on a non-main branch, restrict conclusions to that branch unless the user explicitly asks for a mainline or cross-branch comparison.

Required Context

Read:

• ../../../AGENTS.md;
• ../../../ai-context/methodology/startup/knowledge-model.md;
• ../../../ai-context/methodology/startup/evidence-hierarchy.md — the evidence order behind the Evidence Priority section below;
• ../../../ai-context/operational/index.md and the Operational files relevant to the audit;
• ../../../ai-context/methodology/frontmatter.md when durable General/Situational docs are in scope — the frontmatter convention behind the frontmatter checks below;
• ../../../ai-context/methodology/authoring.md — the always-current discipline (Maintaining Durable Docs) behind the stale-reference check below, including which docs are outside the scrub;
• ../../../ai-context/methodology/general-knowledge.md, ../../../ai-context/general/index.md, and ../../../ai-context/methodology/startup/general-catalog.md — the subjects on offer and their triggers, without which a subject with no file cannot be told from a gap;
• ../../../ai-context/general/safety.md where the project has one, when the audit covers safety-boundary drift — the rails and grants that check reads against;
• ../../../ai-context/general/evidence.md where the project has one — the project's own departures from the default order, which the Evidence Priority section resolves against;
• ../../../ai-context/methodology/situational-knowledge.md and ../../../ai-context/situational/index.md;
• relevant General files;
• relevant Situational files when referenced by docs under audit;
• code/tests/scripts/schemas relevant to disputed documentation claims.

Do not bulk-load all Situational.

Never audit or inspect ../../../ai-context/archive/ files. Archive preserves completed task records as written at the time. Treat old paths, obsolete names, and older terminology inside Archive entries as intentionally historical unless the user explicitly asks for a separate history-normalization task.

Evidence Priority

First classify the disputed claim — descriptive (what the system currently does) or normative (what it must do) — then resolve it by the evidence order (../../../ai-context/methodology/startup/evidence-hierarchy.md), whose top two rungs answer exactly those two questions. Where the order does not settle it, weigh the remaining evidence:

1. Relevant evidence available in the repo or explicitly authorized by the user.
2. General and selected Situational evidence, considering each file's source_of_truth, age, and scope.

If code and docs disagree, report the disagreement and identify the evidence; for a normative claim, say whether the defect reads as doc drift or non-compliant code. Do not rewrite the docs; at most propose a patch, applied by the invoker as a separate step (Read-Only Rules).

Documentation Role Rule

The rule — current implementation detail is code-owned, with a cache (source_of_truth: code, ../../../ai-context/methodology/frontmatter.md) its declared exception — is ../../../ai-context/methodology/startup/knowledge-model.md's.

During an audit, prefer the source tree, tests, scripts, schemas, generated artifacts, and observed runtime behavior for precise facts about what exists and how it currently works. Audit a cache only for what its declaration does not license — a reason stranded in it, which the next refresh silently deletes; a claim the tree contradicts and that no refresh would fix; or a code declared on a doc that is really carrying reasons.

Audit Breadth

Default to the narrowest audit that can answer the user's request.

If the user names specific files, docs, areas, claims, or discrepancies, audit that bounded area plus directly linked docs and evidence.

If the user asks generally (audit documentation, check documentation integrity) with no qualifier, run a broad top-level AI-context audit from ../../../AGENTS.md, the Operational manifest and relevant resident files, the General index, and the skill and lifecycle docs directly referenced by a claim in that set. Expand into Situational, source evidence, code, tests, scripts, or schemas only where an apparent discrepancy requires verification.

Do not traverse all Situational, source code, tests, scripts, or schemas by default. Do not traverse ../../../ai-context/archive/ at all.

Documentation File Reference Rule

The convention (defined in ../../../ai-context/methodology/authoring.md, carried in ../../../ai-context/methodology/startup/previews.md, Documentation Conventions) binds the Cairn-owned tree only — a Markdown link in the project's own documentation is not a finding, because that formatting is the project's.

Within that tree, the path text is relative to the directory of the document that contains the reference. Do not use absolute local filesystem paths or repo-root-relative paths unless a document explicitly defines that convention.

Directory references end with /; file references do not.

A bare filename is a same-directory reference and must resolve there, like any other relative path.

Audit Checks

Focus on substantive discrepancies. Do not nitpick wording. These are discrepancy categories to check within the chosen audit breadth, not a mandate to inspect every repository surface on every invocation.

Check for:

• contradictions between Operational, General, Situational, ../../../AGENTS.md, and skills;
• the router (../../../AGENTS.md) carrying anything beyond routing — a statement that is neither a load directive, a dispatch key or condition, nor the skills trigger table; knowledge, conventions, and previews belong to the files it routes to;
• ../../../CLAUDE.md being anything other than the single @AGENTS.md import line;
• a conditionally loaded file living under ../../../ai-context/methodology/startup/, the closed class the router bulk-loads in full;
• a preview in ../../../ai-context/methodology/startup/previews.md diverging from the rule its declared owner states;
• stale lifecycle rules;
• stale task/finalization/review instructions;
• outdated source-of-truth claims;
• docs that contradict code, tests, scripts, schemas, or generated artifacts;
• docs that present detailed code-owned inventory, exact current behavior, or implementation mechanics as durable truth when repository evidence directly owns the fact — excepting a cache, which declares that mirroring (the Documentation Role Rule above);
• missing or stale README/index entries after file creation, deletion, rename, or repurposing;
• duplicated General split across files with divergent meaning;
• a catalog subject filed under a foreign name — an index row whose Purpose restates a catalog subject's Purpose while its file is not the catalog's File: fixed-path references read that subject as unstated while its content sits loaded under another name;
• resolved issues still described as open;
• stale references to changed or retired knowledge left in live docs — no "this used to be" narrative, no pointer to a superseded rule, invariant, or decision; ../../../ai-context/methodology/authoring.md (Maintaining Durable Docs) owns the discipline and which docs are outside the scrub;
• invented-empty General or Situational sections — an unreached template heading or stub, a None/TBD/not decided marker, or prose narrating that a section is thin instead of omitting it; the fixed Confirmed empty. body is the allowed marker for a user-confirmed empty section, and a bare heading with no body is itself a finding (defined in ../../../ai-context/methodology/authoring.md, No Invented Empty Sections);
• obsolete references to removed skills, agents, files, templates, or workflow phases;
• durable docs (General or Situational) missing required type or source_of_truth frontmatter, an unknown type value, a source_of_truth outside the values ../../../ai-context/methodology/frontmatter.md defines, a Situational or General doc missing description, a Situational doc missing load_when, or load_when that enumerates task types instead of a loading condition, defined in that same file;
• committed documentation references that break the Documentation File Reference Rule above — links rather than inline-code paths, absolute or repo-root-relative paths, wrong relative paths, or a directory reference missing its trailing /;
• safety-boundary drift — a rail in ../../../ai-context/general/safety.md that the repository has outgrown: a boundary drawn around something that no longer exists, or a grant whose stated condition no longer holds; Do not treat intentionally omitted directories as discrepancies. Do not treat a catalog subject with no file as a discrepancy: General holds only what the project has stated, so an uninstantiated subject is a valid steady state, not a gap — ../../../ai-context/methodology/general-knowledge.md owns that rule, and a row in ../../../ai-context/methodology/startup/general-catalog.md is an offer, never a debt. The same holds for an omitted General or Situational section and for one whose body is the fixed Confirmed empty. marker: both are valid steady states under ../../../ai-context/methodology/authoring.md, never integrity findings. Filled content that contradicts the code is still fair game — except in a cache, where the tree moving first is an ordinary cache miss and the lifecycle's refresh from code is the whole remedy.

Non-Goals

Do not:

• create or finalize task briefs;
• run production or out-of-boundary writes;
• rewrite docs for style or elegance only;
• expand docs with code inventory or implementation mechanics that are more accurately obtained from current repository evidence, a cache excepted (the Documentation Role Rule above);
• broaden project scope;
• promote task-local evidence into General unless it has clearly become stable cross-task knowledge.

Output In Read-Only Audit Mode

Severity states the cost of trusting the stale side of the discrepancy: blocker — acting on it would fire a damaging or unsafe operation, or corrupt durable knowledge; material — it changes a decision, a command, or where an agent reads or writes, without blocker-level harm; minor — clarity or convention drift with no behavioral effect.

Use this report shape:

# Documentation Audit

## Executive Assessment

Briefly state whether the documentation is materially consistent, partially stale, or materially inconsistent.

## Always-Loaded Size

Exact character totals (`wc -c`, never estimation), one line each: the router `AGENTS.md`, the startup set `ai-context/methodology/startup/`, and the General tier over the files `ai-context/general/index.md` lists — the last against its budget in `ai-context/methodology/general-knowledge.md`.

## Discrepancies

For each discrepancy:

### <Discrepancy Title>

- Severity: blocker / material / minor
- Files involved:
- Claim in docs:
- Repository/code evidence:
- Source of truth:
- Why it matters:
- Recommended fix:
- Patchability: mechanical / requires user decision

## Code-Backed Findings

List findings where code/tests/scripts/schemas clarified stale or ambiguous docs.

## User Decisions Needed

List only decisions where the fix depends on workflow, architecture, source-of-truth policy, or product scope.

## Mechanical Fixes Available

List fixes that can be safely applied if the user authorizes documentation patching.

## Non-Issues

List important apparent discrepancies that are intentionally not issues.

## Suggested Next Prompt

End with the shortest useful next prompt, for example:

- `apply the mechanical documentation fixes from the audit`
- `decide between the two General options for <topic>`
- `run a narrower audit of <area>`

Patch-Proposal Handoff

If the user explicitly asks for fixes that can be applied:

• propose only targeted documentation patches supported by audit evidence;
• do not patch code or documentation as part of the skill;
• do not make architecture/product decisions without user approval.

Methodology Feedback Handoff

When the audit surfaces a discrepancy or ambiguity worth later methodology attention — for example a framework documentation failure, a rule with no enforcement point, or drift the system silently permits — note it as a methodology-feedback observation. The auditor is read-only and does not write the feedback log; the invoker must surface these to the user, then classify and append them to ../../../ai-context/methodology-feedback.log.md following ../../../ai-context/methodology/methodology-feedback.md — its Compliant-Agent Test and entry format. Do not judge whether the observation is recurring, systemic, or a documentation fix — that is decided later, by the user reviewing the log.