# Alexnodeland Principled Docs Audit

> Docs Audit — Monorepo-Wide Documentation Audit

- Skill: `tomevault-io/alexnodeland-principled-docs-audit` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/alexnodeland-principled-docs-audit`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/alexnodeland-principled-docs-audit/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/alexnodeland-principled-docs-audit

---


# Docs Audit — Monorepo-Wide Documentation Audit

Audit documentation health across all modules in the monorepo and produce an aggregate compliance report.

## Command

```
/docs-audit [--modules-dir <path>] [--format summary|detailed] [--include-root]
```

## Arguments

| Argument               | Required | Description                                                                  |
| ---------------------- | -------- | ---------------------------------------------------------------------------- |
| `--modules-dir <path>` | No       | Root directory containing modules (default: `packages` or value from config) |
| `--format`             | No       | Output format: `summary` (default) or `detailed`                             |
| `--include-root`       | No       | Also validate the repo-level `docs/` structure                               |

## Workflow

1. **Parse arguments.** Extract options from `$ARGUMENTS`. Use defaults from project configuration where not specified.

2. **Discover modules.** Find all subdirectories under the modules directory that appear to be modules (contain a `docs/` directory, `README.md`, or `CLAUDE.md`).
   - Filter out modules matching `ignoredModules` glob patterns from project config.

3. **Determine module types.** For each discovered module:
   - Read the module's `CLAUDE.md` and look for the `## Module Type` section
   - If not found, use `defaultModuleType` from project config
   - If neither available, report the module as "unknown type" and skip validation

4. **Validate each module.** For each module with a known type, run the structural validation:

   ```bash
   bash <plugin-root>/skills/scaffold/scripts/validate-structure.sh \
     --module-path <module-path> --type <type>
   ```

   Capture the results (present, missing, placeholder counts).

5. **Validate root (if `--include-root`).** Run:

   ```bash
   bash <plugin-root>/skills/scaffold/scripts/validate-structure.sh --root
   ```

6. **Aggregate results.** Compute:
   - Total modules scanned
   - Modules passing vs. failing
   - Compliance rate (percentage)
   - Most common gaps across all modules

7. **Format output.** Based on `--format`:
   - **summary:** High-level statistics, common gaps, list of failing modules
   - **detailed:** Per-module breakdown (same format as `/validate`) plus summary

   See `reference/report-format.md` for the complete output specification.

## Configuration

The audit skill respects project-level configuration from `.claude/settings.json`:

| Setting             | Used For                                                   |
| ------------------- | ---------------------------------------------------------- |
| `modulesDirectory`  | Default modules directory if `--modules-dir` not specified |
| `defaultModuleType` | Fallback module type if `CLAUDE.md` doesn't declare one    |
| `ignoredModules`    | Glob patterns for modules to skip                          |
| `strictMode`        | If true, placeholder-only files are treated as failures    |

## Reference

- `reference/report-format.md` — Complete specification of the audit output format

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/alexnodeland) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->