aicr-auditing-docs

name

aicr-auditing-docs

description

Use when reviewing AICR's Markdown documentation for duplication, drift, bloat, and gaps — to keep docs high-value as the project evolves. Triggers on "audit the docs", "review documentation", "docs cleanup", "/aicr-auditing-docs", or any request to find redundant/stale/missing docs across README, docs/, demos/, and the root governance files. Produces a prioritized findings report (research, not edits) grouped by the five audit dimensions, anchored to the project's canonical sources of truth.

Auditing AICR Documentation

Overview

AICR's docs are mature and already well-structured: a persona split under docs/ (user / integrator / contributor), a docs hub with glossary (docs/README.md), ADRs in docs/design/, and a strong root README.md. The recurring risk is not missing structure — it is duplication and drift as features land. This skill is a repeatable audit, not a rewrite: default to a findings report; only edit when explicitly asked.

When to Use

• Periodic doc health check, or before a release.
• After a large feature merges (new CLI flag, API endpoint, component, recipe field).
• When the same explanation appears in multiple files and you suspect drift.
• Not for: writing a single new doc (just write it, following the style rules below), or generated content (docs/conformance/, docs/user/container-images.md).

The Map (what to audit, and how it's owned)

Area	Canonical owner	Notes
Project pitch, features, supported envs	root README.md	Quick Start may duplicate docs/user/installation.md — acceptable for README only.
User how-to / reference	docs/user/	cli-reference.md owns flags; task narrative belongs in task docs (validation.md, agent-deployment.md).
Integration / embedding	docs/integrator/	Resolver internals belong in contributor/, not here.
Project internals	docs/contributor/	Architecture overview = contributor/index.md.
Demos / runbooks	demos/	GitHub-only (not in fern/docs.yml nav). Terse names hurt discovery.
Governance	CONTRIBUTING.md, DEVELOPMENT.md, RELEASING.md, SECURITY.md	Each owns one concern; cross-link instead of repeating.
Agent rules	.claude/CLAUDE.md (canonical) → AGENTS.md (CI-synced mirror — never flag)	.github/copilot-instructions.md should be a pointer, not a copy.

Sources of Truth (drift hotspots — check these first)

Drift between examples and these authoritative sources is the highest-value class of finding:

• Component/chart/image versions → docs/user/container-images.md (the BOM, regenerated by make bom-docs). Inline version examples elsewhere (cli-reference.md, api-reference.md, data-flow.md) should be marked illustrative and point here — never hand-pinned to a stale tag.
• Tool versions (golangci-lint, Go, Ko) → .settings.yaml. Never hardcode in prose or sample workflow YAML.
• Criteria/enum values (service, accelerator, os, intent, platform, error codes) → the Go type (e.g. pkg/recipe/criteria.go). Enums are enumerated in many files; see the enum-audit checklist in CLAUDE.md → Documentation updates.
• API shape → api/aicr/v1/server.yaml (OpenAPI). The component lists and response samples in api-reference.md drift from the registry — diff them.

The Five Audit Dimensions

Run every file through these. Group findings by dimension, prioritized.

1. Duplication — same steps/tables/concepts in >1 file. Pick the canonical owner (table above), trim the rest to a cross-link. Known repeat offenders: agent/snapshot deployment, recipe-evidence walkthrough, constraint paths/operators table, make-target block, DCO/signing rules, the six demos/cuj*-{eks,gke}.md files (~80% shared).
2. Overlap / misplacement — content in the wrong persona tree (e.g., resolver internals in integrator/, agent deployment in integrator/ when it's a user concern), or a topic split awkwardly across files.
3. Bloat — verbose sections that lose no value when cut: embedded SBOM/JSON dumps, repeated export TAG= blocks, stub code that contradicts the architecture ("AICR is not a controller"), generic K8s boilerplate that isn't AICR-specific, walls of text needing structure.
4. Gaps (Diátaxis) — is each of tutorial / how-to / reference / explanation present for the persona? Known holes: no end-to-end tutorial (install→recipe→bundle→deploy→validate), no aicr bundle how-to.
5. Staleness / style violations — TODOs, "(Future)" content shown as usable, contradictory version numbers, leftover template placeholders (__AICR (AICR)__), and violations of the repo's own doc-style rules below.

Repo Doc-Style Rules (enforce during audit)

These are defined in CLAUDE.md → Documentation Style; flag violations:

• Auto-anchors, no manual TOCs — GitHub/Fern generate anchors. Manual ## Table of Contents blocks (present in CONTRIBUTING.md, DEVELOPMENT.md) are violations.
• Promote **Bold Label:** to a heading sparingly — only a named topic with ≥ ~8 lines beneath it.
• Anchor hygiene — when renaming/removing a heading, grep <file>.md#<old-slug> repo-wide and fix inbound links. Broken anchors fail CI via lychee on any docs/** PR (.github/workflows/fern-docs-ci.yaml) — but not make qualify.

How to Run It

1. Parallelize by area to protect context: dispatch one research agent per tree — (a) docs/ persona trees, (b) root + agent docs, (c) demos/. Give each the five dimensions and the sources-of-truth list; ask for a concise (<600 word) report with file paths and concrete recommendations.
2. Synthesize into one prioritized report. Lead with version/enum drift (highest value), then duplication consolidations, then bloat/gaps.
3. Report, don't rewrite by default. If asked to fix: one focused PR per theme (e.g., "de-dup agent deployment", "trim SECURITY.md"), keep diffs reviewable, and after any change run make qualify (and note lychee is separate). Touching docs/** requires the lychee anchor check.

Common Mistakes

• Flagging the AGENTS.md ↔ CLAUDE.md mirror as duplication — it's intentional and CI-enforced.
• Recommending a TOC "for navigation" — violates the auto-anchor rule.
• Hand-fixing a version in an example — fix the pattern (mark illustrative, link to container-images.md) so it can't re-drift.
• Editing generated files (container-images.md, docs/conformance/) directly instead of their generators.
• Auditing one file in isolation — duplication only shows up across files; read the tree.