# Audit

> acta:audit

- Skill: `erenisci/audit` (Agent Skill)
- Install (CLI): `npx skillmds@latest add erenisci/audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/erenisci/audit/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: erenisci (https://skillmd.com/u/erenisci)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/erenisci/audit

---


# acta:audit

The **trust check.** Acta's whole value is a trustworthy engineering memory — this verifies the docs haven't drifted
from reality. **Read-only by default:** it reports; it fixes only mechanical things when asked (`--fix`), and it
**never fabricates content or guesses**.

Shared resources at `${CLAUDE_PLUGIN_ROOT}/acta/`: `doc-catalog.md` (the contract), `disciplines.md`, `project-types.md`,
`principles.md`.

## Language
Write findings and any persisted items in the project's documentation language (registry `language:`, default English); talk to the user in the language they use. See `${CLAUDE_PLUGIN_ROOT}/acta/principles.md`.

## Pre-condition

Read `.claude/acta.md` (registry) and `${CLAUDE_PLUGIN_ROOT}/acta/doc-catalog.md`. If there is no registry, this project isn't
set up with Acta yet → suggest `/acta:build` (greenfield) or `/acta:adopt` (existing code). Don't guess a doc set without them.

## Checks

Run these read-only checks and collect findings. Rank each **🔴 broken · 🟡 drift/stale · 🔵 hygiene**.

1. **Brain & index integrity** — `CLAUDE.md` has the `<!-- acta:index:start/end -->` block and its links resolve;
   `docs/README.md` lists exactly the docs on disk (no missing, no orphan); registry rows match the filesystem.
2. **Broken links** — every relative link inside `docs/**` (and the brain) points to an existing file.
3. **Doc ↔ code drift** — compare docs against the code and flag mismatches:
   - stack in `arch-overview` / registry vs `package.json` / `pyproject.toml` / `go.mod` / etc.
   - endpoints in `api.md` vs routes; env-var **names** in `env-vars.md` vs `.env.example` (the committed template only —
     never open a real `.env`/`.env.local`; compare names, never values); `project-structure` tree vs the
     actual top-level folders; tables in `database-design` vs schema/migrations.
   - "doc says X, code says Y" → report both sides.
4. **Stale / empty** — docs still mostly `TBD`; `updated:` far behind recent code changes; scaffolds never filled.
5. **Contradictions** — best-effort scan for conflicting statements across docs (e.g. PRD "no backend" vs
   architecture "REST API"). Flag them; **never resolve by guessing.**
6. **Conventions** — filename casing (root meta UPPERCASE, `docs/**` lowercase kebab-case); docs living outside the
   catalog's paths; disciplines/packs in the registry vs what's actually on disk. **Do not flag** the skill-owned
   areas `docs/design/`, `docs/business/`, `docs/legal/` as orphans — they are valid (see the catalog's "Skill-owned
   areas" note); `docs/design/previews/` holds `acta:preview --save` screenshots (assets, not docs) — valid too.
7. **Anti-bloat** — `in-place` docs that have grown append-only (e.g. `PROGRESS.md` accumulating dated log lines
   instead of a snapshot); oversized docs that should be consolidated per their growth policy.
8. **Design consistency** (only if `docs/design/` exists) — the code's real styling vs the design doc-base:
   - rogue colors / spacing / fonts / type used in code but not in `tokens.md` (and its granular docs — `color.md`,
     `typography.md`, `spacing-layout.md`, `motion.md` — where present); a drifted styling **approach** vs `design-system.md`.
   - components or variants/states in code missing from `components.md`.
   - **DDR integrity** (full tier): `docs/design/decisions/README.md` index matches the files on disk; no DDR points
     to a superseding DDR that doesn't exist.
   - a broken or missing **`{{DESIGN_LINKS}}`** block in the brain (design docs exist but the "Design & brand" bullet
     is absent or its links don't resolve).
   Flag them → the fixer is `/acta:track` (design sync).
9. **Business consistency** (only if `docs/business/` exists) — a price / plan / tier in the code or config (e.g. a
   Stripe price, a plans table) that disagrees with `pricing.md`; a monetization model in code not reflected in
   `business-model.md`. Flag the drift → the fixer is `/acta:business`. (Read-only; never rewrite pricing.)
10. **Legal consistency** (only if `docs/legal/` exists) — legal-relevant reality in the code not reflected in the
    briefs: cookies / analytics / trackers with no `consent.md` entry; a data field or vendor / sub-processor absent
    from `data-processing.md`; a market/region served that the briefs' regimes don't cover; open **"⚠️ needs lawyer
    re-review"** items. Flag them → the fixer is `/acta:track` (legal sync). (Never write binding legal text or give legal advice.)

## Output

Print a concise report — **do not create a bloated audit file**:

```
Acta audit — <project>
🔴 Broken (N)      : <one line each>
🟡 Drift/stale (N) : <one line each>
🔵 Hygiene (N)     : <one line each>
Clean              : <areas with no findings>
→ Fix: run /acta:track to re-sync current-state docs; <specific doc> needs <the manual bit only a human can supply>.
```

If everything passes, say so plainly. **By default the audit writes nothing** — the report is printed; no file is
created and no file grows.

## Not losing findings (opt-in, never bloats)

Because the report is ephemeral, offer two ways to keep the findings — the user chooses; **nothing is written without
consent:**

1. **Just re-run `/acta:audit`** next session — it's cheap and reflects the *current* reality, so a real issue is never
   missed (nothing to forget). This is the default.
2. **Record open items into the living memory** (only if the user wants persistence): one concise line per unresolved
   finding into an **existing** doc — never a separate audit file:
   - blocking / do-next → `docs/progress.md` **Blocked** / **Next Up**
   - deferred quality or debt → `docs/project/tech-debt.md` (`TD-N`)
   - a doc's own unknown → that doc's **Open Questions**

   These are **bounded, self-cleaning** docs (a snapshot / an open-debt list) linked from the `CLAUDE.md` brain:
   `acta:track` removes each item once it's fixed, so they track the *current* open set and **shrink as you resolve
   them — never grow without bound.** Anti-bloat: one line per item, dedupe, no audit files.

## Fixing — only with `--fix`, only the safe mechanical set

- Regenerate the `CLAUDE.md` brain block, `docs/README.md` index, and `.claude/acta.md` registry from the current
  filesystem (idempotent, marker-scoped).
- Remove or correct broken internal links.
- Refresh `updated:` dates only on docs you actually changed.
- **NEVER** fabricate content, resolve a contradiction, or fill a `TBD` — those are always reported for the human or
  for `/acta:track`, never invented.

## Rules

- Read-only by default; `--fix` performs only the mechanical set above.
- Never fabricate; unknown / contradiction / gap → **report**, don't invent.
- Idempotent. Content in the project's documentation language. Operate by `${CLAUDE_PLUGIN_ROOT}/acta/principles.md`.