audit

Audit Skill

Goal

Compare the project's rules/, skills/, and CLAUDE.md against the checklist in references/best-practices.md, then produce a report with actionable verdicts and optimization suggestions.

Help

When the user types audit help, output:

Audit — Usage

  audit                Audit everything (rules + skills + CLAUDE.md)
  audit rules          Audit rules only
  audit skills         Audit skills only
  audit links          Check reference links only

Workflow

1. Load the checklist

Read references/best-practices.md Chapter 7 "Optimization Checklist" as the audit standard. The built-in baseline checks below are used when the reference doc is missing; if the reference doc exists, it takes precedence.

2. Scan and check

• •Always On rules should be 0 (or very few and tiny)
• •Every rule must have a paths or description trigger
• •Size: 30–60 lines ideal, >130 lines needs review
• •No "role definition", "not-recommended examples", or generic knowledge
• •paths should not be too broad (e.g. **/*.h across languages)
• •No conflicting paths between rules

• •SKILL.md should stay under ~200 lines; larger content moves to references/
• •description must contain clear trigger words
• •Provide a help subcommand
• •Large content split into references/
• •Content should not duplicate project memory/feedback docs; reference them instead

• •No duplication with rules/skills
• •Glossary only for project-specific terms
• •Common commands should point to docs, not expand inline
• •No overlap with project-level memory entries

For any external reference inside a rule/skill/CLAUDE.md — CLI flags, API paths, tool names, package names, URLs, specific version numbers — trigger validation:

• •Internal/custom tools: grep the internal changelog, or run --help to verify the flag still exists
• •Git push workflows (refs/for/*, GitLab, Gerrit): verify the syntax is still supported
• •External SDKs / npm / pypi: check whether the package was renamed or deprecated
• •External doc URLs: check for 404s

Priority of evidence: measured > internal docs > official docs > memory.

• •Every markdown link [text](path) must resolve to an existing file
• •Directory-tree descriptions must match the real file structure

3. Output report

Each audited item gets a verdict + reason. Five verdict levels:

Group the report by verdict:

## Audit Report

### 🔴 Retire
[path + reason (alternative)]

### 🟠 Update (needs verification)
[path + reason + external references involved]

### 🔵 Merge into [X]
[path + target + specific content to merge]

### 🟡 Improve
[path + concrete change description]

### ✅ Keep
[path + brief reason]

Total: N Keep / N Improve / N Update / N Retire / N Merge

3.1 Reason style

Every audit reason must be self-contained and decision-enabling — readable without looking at other files. Avoid empty phrases:

Why strict reasons: Retire/Merge are destructive; the user must be able to decide based on the reason alone. Empty Keep reasons hide "looked at but not really audited".

4. Feed best practices back

After auditing, check whether any newly found issue type is not covered by references/best-practices.md:

• •"💡 This audit found a new issue type not in the checklist: [description]. Suggest appending it to the checklist. Update?"
• •If the user confirms, append the new check to the checklist chapter.