tomevault-io Audit Docs-Delegation Command
Audit skills and memory files for docs-management delegation compliance.
Initialization
Before auditing, initialize the environment:
- Get the current UTC date for audit timestamps.
- Capture the project root path for subagent communication.
- Ensure the temp directory (
.claude/temp/) exists. - Clean up any stale audit files if the user confirms.
The ecosystem-health skill provides authoritative validation guidance (auto-loaded when this command runs).
What Gets Audited
- Hardcoded Claude Code data: Hook event types, YAML frontmatter fields, settings keys
- Volatile information: GitHub issue references, model names with versions, token limits
- Delegation patterns: Verification notes, MANDATORY sections, skill references
- Exempt patterns: Configuration files, educational content, self-specification
Command Arguments
| Argument | Description |
|---|---|
| (none) | Smart mode: audit modified, never-audited, or stale (>90 days) files |
--force |
Audit ALL files regardless of status |
--plugin-only |
Only audit local plugin skills |
--project-only |
Only audit project files (.claude/skills/, .claude/memory/) |
skill-name |
Audit specific skill(s) by name |
Step 1: Discover Audit Targets
Search for files that may contain Claude Code references:
Skills:
plugins/*/skills/*/SKILL.md(local plugins).claude/skills/*/SKILL.md(project skills)
Memory Files:
.claude/memory/*.md(project memory)plugins/*/skills/*/references/*.md(skill references)
Audit Framework Files:
plugins/*/skills/*/references/audit-framework.md(audit validation rules)plugins/*/skills/*/references/*-criteria.md(validation criteria files)
Exclusions (auto-exempt):
hooks.jsonfiles (configuration specification)hooks/*.py,hooks/*.sh(hook implementations)canonical/directories (scraped documentation cache)plugins/tac/lessons/(educational content)
Build a list of discovered files with their scope (plugin, project) and full path.
Step 2: Parse Arguments
Check for --force, --plugin-only, --project-only flags or specific skill names.
Build the audit queue based on discovered files and arguments:
- Smart mode: Filter to modified, never-audited, or stale (>90 days) files
- Force mode: Include all discovered files
- Scoped modes: Filter to matching scope only
Step 3: Present Audit Plan
Display audit mode (SMART or FORCE), targets discovered, and list each with scope and last modified date.
## Audit Plan
**Mode**: SMART
**Files discovered**: 15
1. [plugin:claude-ecosystem] skills/hook-management/SKILL.md
2. [plugin:claude-ecosystem] skills/skill-development/SKILL.md
3. [project] .claude/memory/workflows.md
...
**Will audit**: 8 files (7 skipped - recently audited)
Step 4: Execute Audits
For each file, spawn the docs-delegation-auditor subagent with the following context:
- Scope (plugin:name or project)
- Full path to the file
- Last audit date or "Never audited"
- Current audit date
- Project root path
Run subagents in parallel batches of 3-5.
Subagents write findings to .claude/temp/ as both JSON (for recovery/aggregation) and markdown (for human review). The main conversation thread collects results and updates audit logs using its Write/Edit tools.
CRITICAL: After ALL audits complete, sync results to the audit log at .claude/audit/docs-delegation.md.
Step 5: Final Summary
Report total files audited, results by scope, and details table. List any compliance issues with remediation steps.
## Audit Complete
### Summary
- **Total audited**: 8 files
- **COMPLIANT**: 5 (62%)
- **PARTIALLY COMPLIANT**: 2 (25%)
- **NON-COMPLIANT**: 1 (13%)
### Results
| Scope | File | Classification | Score |
| --- | --- | --- | --- |
| plugin | hook-management/SKILL.md | ✅ COMPLIANT | 95/100 |
| plugin | skill-development/SKILL.md | ✅ COMPLIANT | 100/100 |
| project | workflows.md | ⚠️ PARTIAL | 78/100 |
| plugin | lesson-014-analysis.md | ❌ NON-COMPLIANT | 65/100 |
### Issues Found
1. **lesson-014-analysis.md** (Score: 65)
- HIGH: Hardcoded `PreToolUse`, `PostToolUse` without delegation note
- Missing MANDATORY section
- **Action**: Add verification note pointing to docs-management
Scoring
Files are scored out of 100 points with deductions for hardcoded patterns:
| Deduction | Amount | Condition |
|---|---|---|
| HIGH risk pattern | -15 each | Hardcoded without delegation note |
| MEDIUM risk pattern | -8 each | Hardcoded without delegation note |
| Missing MANDATORY section | -20 | File has hardcoded data but no delegation section |
| Missing verification notes | -15 | Hardcoded data without verification blockquote |
Thresholds:
- COMPLIANT (85+): Ready for use, proper delegation
- PARTIALLY COMPLIANT (70-84): Functional with improvement opportunities
- NON-COMPLIANT (<70): Hardcoded data that should be delegated
Important Notes
HIGH Risk Patterns
These indicate hardcoded Claude Code information that should delegate to docs-management:
| Pattern | Example |
|---|---|
| Hook event types | PreToolUse, PostToolUse, SessionStart |
| YAML frontmatter fields (in prose) | allowed-tools, permissionMode, color |
| Settings keys | CLAUDE_HOOK_*, apiChoice, sandboxMode |
MEDIUM Risk Patterns
| Pattern | Example |
|---|---|
| GitHub issue references | #10437, #15326 |
| Model names with versions | Opus 4.5, claude-opus-4-5 |
| Token limits | 25K tokens, context window |
Compliance Patterns (What Makes Files Compliant)
| Pattern | Description |
|---|---|
| Verification note | > **Documentation Verification:** blockquote |
| MANDATORY section | ## MANDATORY: or ## 🚨.*MANDATORY |
| Query pattern table | Table with docs-management query patterns |
| Skill reference | invoke the X-management skill |
Exempt Patterns (Not Flagged)
| Pattern | Reason |
|---|---|
hooks.json event names |
Configuration specification |
allowed-tools in YAML frontmatter |
Self-specification |
tools in agent YAML frontmatter |
Agent definition |
| Educational content | Instructional, not authoritative |
canonical/ directories |
Scraped docs cache |
Audit Log Location
All audit results are written to .claude/audit/docs-delegation.md.
Use /audit-log docs-delegation to view current audit status.
Example Usage
Example 1: Audit All Files
User: /audit-docs-delegation
Claude: Discovering audit targets...
## Audit Plan
**Mode**: SMART
**Files discovered**: 25
1. [plugin:claude-ecosystem] skills/hook-management/SKILL.md
2. [plugin:claude-ecosystem] skills/skill-development/SKILL.md
3. [plugin:tac] analysis/lesson-014-analysis.md
...
**Will audit**: 12 files (13 skipped - recently audited)
[Spawns docs-delegation-auditor subagents]
## Audit Complete
| Scope | File | Classification | Score |
| --- | --- | --- | --- |
| plugin | hook-management/SKILL.md | ✅ COMPLIANT | 95/100 |
Example 2: Force Audit All
User: /audit-docs-delegation --force
Claude: Auditing all files (force mode)...
Example 3: Audit Specific Skill
User: /audit-docs-delegation hook-management
Claude: Auditing hook-management skill...
Example 4: Plugin-Only Audit
User: /audit-docs-delegation --plugin-only
Claude: Auditing plugin skills only...
Converted and distributed by TomeVault — claim your Tome and manage your conversions.