---
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`, `RELEASE.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.