# Audit Docs

> >

- **Type:** Skill
- **Install:** `agentstack add skill-talont-org-autoskillit-audit-docs`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [TalonT-Org](https://agentstack.voostack.com/s/talont-org)
- **Installs:** 0
- **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [TalonT-Org](https://github.com/TalonT-Org)
- **Source:** https://github.com/TalonT-Org/AutoSkillit/tree/main/src/autoskillit/skills_extended/audit-docs

## Install

```sh
agentstack add skill-talont-org-autoskillit-audit-docs
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# Documentation Audit Skill

Audit all documentation sources for drift, staleness, and inconsistency against actual codebase behavior.

## When to Use

- User says "audit docs", "check documentation", "docs audit", "documentation review", "docs drift", "stale docs"

## Critical Constraints

**NEVER:**
- Modify any source files
- Update an existing report — always generate a new one
- Compare doc-to-doc without first grounding claims in actual code behavior
- Run subagents in the background (`run_in_background: true` is prohibited)

**ALWAYS:**
- Ground every cross-reference finding in what the code actually does (not what other docs say)
- Use subagents for parallel exploration
- Write report to `{{AUTOSKILLIT_TEMP}}/audit-docs/docs_audit_{YYYY-MM-DD_HHMMSS}.md`
- Provide file:line references for every finding
- Categorize findings by severity (CRITICAL, HIGH, MEDIUM, LOW)
- Produce a usable report even when one or more subagents fail

---

## Documentation Sources

Enumerate and audit all of the following:

- **`CLAUDE.md`** — project instructions, architecture tree, file path references, tool/skill counts, layer descriptions
- **`docs/architecture/**/*.md`** — component names, module paths, layer assignments
- **`docs/requirements/**/*.md`** and **`docs/specs/**/*.md`** — API surface, behavioral contracts
- **All `README.md` files** at any depth in the repository
- **Module/class/function docstrings** in Python files under `src/`
- **Recipe YAML `description`, `summary`, and `note` fields** in `.autoskillit/recipes/` and `src/autoskillit/recipes/`

---

## Inconsistency Categories

Flag findings in these categories (maps to REQ-SKILL-004):

- **Stale claims** — doc asserts X, actual code behavior is Y
- **Orphaned references** — doc mentions a file, module, tool, class, or skill that no longer exists
- **Missing docs** — new subsystem or module with no mention in CLAUDE.md tree or arch docs
- **Path/name drift** — hyphen-vs-underscore mismatches, renamed symbols, old module paths
- **Count mismatches** — CLAUDE.md states N tools/skills/hooks but actual count differs
- **Inter-doc contradictions** — CLAUDE.md says A, arch doc says B about the same entity

---

## Audit Workflow

1. **Pre-flight**: Verify `{{AUTOSKILLIT_TEMP}}/audit-docs/` directory exists; create it if not.

2. **Familiarization wave** — spawn 6 parallel subagents, one per subsystem group. Each subagent reports: actual module/component names, exported symbols, behavioral summary (2–5 sentences per module). If any subagent fails, record the gap and continue.

   | Agent | Subsystems | Focus |
   |---|---|---|
   | Agent 1 | `core/`, `config/` | What these modules actually expose and do |
   | Agent 2 | `execution/`, `workspace/` | Runtime orchestration and workspace lifecycle |
   | Agent 3 | `recipe/`, `migration/` | Recipe schema, rules, validation, migration engine |
   | Agent 4 | `server/` | MCP tool surface, gating, lifespan, factory |
   | Agent 5 | `cli/`, `hooks/` | CLI commands, hook scripts, what each does |
   | Agent 6 | `skills/`, `skills_extended/` | Bundled skills, categories, tiers |

3. **Doc inventory** — enumerate all documentation sources (list files found under each source category above).

4. **Cross-reference wave** — spawn 4 parallel subagents, each checking one doc domain against the familiarization findings:

   | Agent | Domain | What to check |
   |---|---|---|
   | Agent A | `CLAUDE.md` | Architecture tree accuracy, file path references, tool/skill counts, layer descriptions |
   | Agent B | `docs/architecture/**` | Component names, module paths, layer assignments |
   | Agent C | `docs/requirements/**` and `docs/specs/**` | API surface, behavioral contracts |
   | Agent D | Recipe YAML descriptions + docstrings | Step descriptions, ingredient names, parameter docs |

5. **Consolidate** — merge findings from all 4 agents, deduplicate by file:line, assign severity.

6. **Self-validation pass** — for every CRITICAL or HIGH finding, re-read the cited file line to confirm the claim; downgrade or remove if not confirmed.

7. **Write report** to `{{AUTOSKILLIT_TEMP}}/audit-docs/docs_audit_{YYYY-MM-DD_HHMMSS}.md` (relative to the current working directory) using the format below.

8. **Output summary** — print finding counts by severity to terminal.

---

## Report Format

```
# Documentation Audit Report — {YYYY-MM-DD HH:MM}

## Summary
| Severity | Count |
|----------|-------|
| CRITICAL | N     |
| HIGH     | N     |
| MEDIUM   | N     |
| LOW      | N     |

## Findings

### CRITICAL

#### [DOC-001] {Title}
- **File:** `path/to/doc.md:42`
- **Claim:** "..."
- **Actual:** "..."
- **Fix:** ...

...

## Coverage Gaps
{If any familiarization subagent failed, list affected subsystems here}
```

---

## Exclusions

Do NOT flag:
- Test files (`tests/`)
- Generated files (`{{AUTOSKILLIT_TEMP}}/`, `uv.lock`, `*.pyc`)
- Comment-only files or changelog entries
- External tool output or CI logs
- Doc-to-doc wording differences that don't contradict each other factually

---

## Severity Guidelines

**CRITICAL:**
- Orphaned references to deleted modules/tools
- CLAUDE.md architecture tree listing a path that doesn't exist

**HIGH:**
- Stale behavioral claim that would mislead an implementer
- Count mismatch (e.g., CLAUDE.md says N skills, actual is M)

**MEDIUM:**
- Path/name drift (hyphen vs underscore, module moved)
- Missing doc for a significant new subsystem

**LOW:**
- Minor wording drift
- Docstring describes a parameter that was renamed

## Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [TalonT-Org](https://github.com/TalonT-Org)
- **Source:** [TalonT-Org/AutoSkillit](https://github.com/TalonT-Org/AutoSkillit)
- **License:** MIT

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-talont-org-autoskillit-audit-docs
- Seller: https://agentstack.voostack.com/s/talont-org
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.