Aicr Auditing Docs

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.

• 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).

• 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.

• 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.

• 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.

• 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

• 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.

• Synthesize into one prioritized report. Lead with version/enum drift

(highest value), then duplication consolidations, then bloat/gaps.

• 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.