Skip to content
Skills Library
Programming · Review & audit

docs-audit

/docs-audit

Audit docs/DECISIONS.md and docs/CODE_MAP.md against the code at a release's Record step, before the owner approves the release, or whenever the owner asks. Includes the mechanical checker the Lead also runs before handing in Record.

Repository
agent-built ↗
Licence
MIT
Last repository change
09.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
1
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 09.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: check_docs.py

What it does and when to use it

Audit docs/DECISIONS.md and docs/CODE_MAP.md against the code at a release's Record step, before the owner approves the release, or whenever the owner asks. Includes the mechanical checker the Lead also runs before handing in Record.

Original author description

Audit docs/DECISIONS.md and docs/CODE_MAP.md against the code at a release's Record step, before the owner approves the release, or whenever the owner asks. Includes the mechanical checker the Lead also runs before handing in Record.

How it works

  1. 1. Mechanical check (the Lead runs this too)
  2. 2. Line-by-line review (PM)
  3. 3. Report to the owner
Original SKILL.md headings · 54 lines, 535 words
SKILL.md preview
---
name: docs-audit
description: Audit docs/DECISIONS.md and docs/CODE_MAP.md against the code at a release's Record step, before the owner approves the release, or whenever the owner asks. Includes the mechanical checker the Lead also runs before handing in Record.
---

# Docs audit

Makes `docs/DECISIONS.md` and `docs/CODE_MAP.md` exactly match the code, so the owner approves a release on accurate docs. Rules: `CLAUDE.md` "Documentation hygiene" and `docs/RELEASE_PROCESS.md`, Record step.

## 1. Mechanical check (the Lead runs this too)

```bash
python3 .claude/skills/docs-audit/check_docs.py
```

It checks every repo path and code name cited in both docs, decision ID bookkeeping (no duplicates or unexplained gaps; retired and reserved IDs listed), that every code `(D-###)` tag names an active decision, and the ledger's "next free IDs" line. Set your folders and ID prefix in its CONFIG block first.

Any FAIL is fixed before going further. WARN lines are judged: a name cited beside the wrong file gets the right file; an untagged decision gets a tag if code implements it; an "(in progress)" entry must not belong to the version being released.

The Lead runs it before handing in Record and fixes its own misses. The PM runs it again on the release commit.

## 2. Line-by-line review (PM)

Run it on the **final** release candidate's commit. Any code change after an earlier audit means auditing again.

Scope: every line of both docs that changed since the previous release tag, and every code file that changed.

```bash
git diff <previous-release-tag>..HEAD -- docs/DECISIONS.md docs/CODE_MAP.md
git diff --stat <previous-release-tag>..HEAD -- <your source folders>
```

**Coverage first:** for each changed code file, name its `CODE_MAP.md` subsystem and the decisions it implements, then confirm that section (Flow, Must hold, Debug from) and those decisions changed to match, or note why no doc change is needed. The checker can't see missing content, so a clean checker is never the whole audit.

For each changed decision:
- the Rule matches what the code does (cite file:line); quoted messages match the code exactly;
- Code names every implementing place, and that code carries the tag;
- Since is this version; no "(in progress)" left for it; replaced IDs are under Retired IDs;
- nothing remains from a direction that was dropped during the version;
- no working notes, history, evidence or open questions; nothing repeated from another entry.

For each changed code-map section: Flow steps match the code, Must hold lines are true, Debug from points at real messages or error codes.

Every line must earn its place: delete what an agent wouldn't need.

**Glossary:** check `docs/GLOSSARY.md` against what the owner said during the version (terms added, renamed or used differently). Bring any needed change to the owner first; edit the glossary only after they approve.

## 3. Report to the owner

Clear and very concise; the depth stays with the PM. List only:
- what changed in the docs this release, one line per decision or code-map section;
- any glossary term to add or correct, with the proposed wording, for approval;
- anything needing the owner: a rule the code doesn't match, or an "(in progress)" entry that isn't shipping. One line each, with the choice: change the decision, finish the code, or remove the entry and return the item to the ledger.

Say "audit clean" when nothing needs the owner.

Decisions change only with the owner's approval. Mechanical corrections (a moved file, a renamed function, a missing tag) don't need it, but list them.
Files in this package (2)
  • SKILL.md 4 KB
  • check_docs.py 8 KB

Versions

RepositoryScoreLicence
This page · Copypaster3000/agent-built100MIT
mastra-ai/mastra100Apache-2.0
colonyops/hive100MIT
stark-ai-de/agent-skills100Apache-2.0
hiroppy/tmux-agent-sidebar100MIT
mihaimyh/agentic-audit-suite100MIT

Database snapshot: 13.11.2026 · package version 0e3e8623c5ac (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100audit-docs
    Audit README.md and docs/ for accuracy. Runs every documented code example, checks links, anchors, and prose rules, and verifies the CLI examples against the built gem. Use when documentation changes, before a release, or when the user asks to check the docs, verify code…
  • 100docs-update
    Audit project documentation against the current state of the codebase and produce a revision plan. Reads README and all docs, launches parallel Explore agents to verify claims, diffs documentation vs reality, and applies approved fixes. Use when user says "quality-docs-update",…
  • 95validate-docs
    Validate and update the public user docs in `site/` (Mintlify) against the code — map every user-facing change since a ref to the pages it touches, fix the pages, then run the docs test, the Mintlify build and link checks and the anonymization scan. Also adds a release's…
  • 90sync-docs-release
    Use when the user wants to sync docs and then cut a release in one shot. Combines sync-docs (which lands its edits through its own docs PR) → optional merge of that PR → create-release in sequence. Triggers on phrases like "sync docs and release", "sync and cut a release",…
  • 95using-juliacheck
    Use when you want to run JuliaCheck.jl, a JuliaSyntax-based rule checker, against Julia source files, choose rules or output formats, or add static code checks to a workflow
  • 100writing-docs
    Write, audit or update a project's docs from its source code. User docs (quickstart, install, configuration, a page per feature) and maintainer docs (architecture, data model, invariants), as plain Markdown or for a docs framework such as Starlight or MkDocs. Use for "write the…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.