cc-os/plugins/cc-architect/references/tool-patterns/audit-pattern.md

Audit Pattern

Smart implicit audits that run automatically when modifying tools or handling vague requests.

Purpose

Prevent drift and degradation by auditing before changes, not just when explicitly requested.

When to Use

Implicit audit triggers:

• User asks to "modify" or "update" an existing tool
• User gives vague request like "improve this skill"
• User asks to "add" something to an existing tool
• Any change to a tool that has golden examples

Explicit audit triggers:

• User asks to "audit" or "review" a tool
• User pulls a tool from marketplace and wants evaluation

Skip audit when:

• Creating a brand new tool (nothing to audit yet)
• User gives specific, unambiguous instructions
• Quick fixes to obvious bugs (typos, syntax errors)

Implementation Checklist

Tools implementing this pattern must:

• Define audit scope in workflow (what gets checked)
• Check for prior decisions in .decisions/ before auditing
• Run audit as subagent(s) to keep main thread light
• Write findings to scratch workspace (gitignored)
• Classify findings by severity
• Check golden examples for behavioral impact
• Record new decisions made during audit
• Clean up scratch files after user acts on findings

Workflow Structure

1. Detect implicit trigger
   └─→ "modify" / "update" / "add to" / vague request

2. Load prior context
   └─→ Read .decisions/ for this tool
   └─→ Read invariants.md if exists
   └─→ Read golden examples

3. Run audit subtasks (parallel where possible)
   └─→ Structure audit (haiku)
   └─→ Content audit (opus)
   └─→ Quality audit (opus)
   └─→ Change impact analysis

4. Assemble findings
   └─→ Classify severity
   └─→ Flag golden example impacts

5. Present to user
   └─→ Summary with verdict
   └─→ What will change and why

6. Record decisions
   └─→ Write to .decisions/

Example Reference

See ${CLAUDE_PLUGIN_ROOT}/workflows/audit-skill.md for a complete audit workflow implementation.

Anti-patterns

Audit theater: Running audits but ignoring findings. Every significant finding must be addressed or explicitly deferred.

Audit fatigue: Auditing every tiny change. Reserve for modifications that could affect behavior.

Silent audits: Running audits without telling the user. Always surface findings.

Cross-references

• Verification Pattern - Audits feed into verification
• Decisions Record - Audits must record decisions
• Reversion Protection - Audits check golden examples