Rule Audit

Audit Categories

Redundant Rules

Rules that overlap significantly with other rules.

Example:

• R-003: "Use descriptive variable names"
• R-007: "Variables should have meaningful names"
• Finding: 85% similar, consider merging

Overly Broad Rules

Rules using general terms without specific criteria.

Example:

• ❌ "All code must be good quality"
• ✅ "All functions must be under 50 lines and have cyclomatic complexity < 10"

Potentially Unused Rules

Rules that may be outdated or unnecessary.

Example:

• Rule: "Check things" (too vague, no enforcement)
• Suggestion: Expand with specific requirements or remove

Output Format

{
  "totalRules": 12,
  "totalIssues": 5,
  "redundant": [
    {
      "rule1": "R-003",
      "rule2": "R-007",
      "similarity": "85%",
      "suggestion": "Consider merging R-003 and R-007"
    }
  ],
  "broad": [
    {
      "ruleId": "R-001",
      "reason": "Uses general terms without specific constraints",
      "suggestion": "Add specific validation criteria"
    }
  ],
  "unused": [
    {
      "ruleId": "R-010",
      "reason": "Too short and lacks enforcement language",
      "suggestion": "Expand or consider removal"
    }
  ]
}

Examples

Example 1: Healthy Constitution

Input: 10 well-defined, specific, non-overlapping rules

Output:

# Rule Audit Report

**Date:** 2026-04-01
**Total Rules:** 10
**Issues Found:** 0

## ✅ All Clear

No issues found. The constitution is in good health!

Example 2: Issues Found

Input: 8 rules with some overlap and vagueness

Output:

# Rule Audit Report

**Date:** 2026-04-01
**Total Rules:** 8
**Issues Found:** 3

## 🔄 Redundant Rules (1)

- **R-003** and **R-005** are 82% similar
  - Suggestion: Consider merging R-003 and R-005

## 🌐 Overly Broad Rules (2)

- **R-001**: Rule uses general terms without specific constraints
  - Suggestion: Add specific validation criteria or constraints

- **R-007**: Rule uses general terms without specific constraints
  - Suggestion: Add specific validation criteria or constraints

Integration

This skill is run periodically (weekly/monthly) or on demand:

# Run audit
npm run audit

# Or via gitclaw
gitclaw run audit

Benefits

1. Prevents Rule Bloat - Identifies redundant rules
2. Maintains Quality - Flags vague or weak rules
3. Ensures Relevance - Detects unused rules
4. Guides Cleanup - Provides actionable recommendations
5. Constitutional Health - Long-term governance quality

Recommendations Structure

Priority Levels

• High: Redundant rules (merge needed)
• Medium: Overly broad rules (refinement needed)
• Low: Potentially unused rules (review needed)

Action Types

• Merge: Combine similar rules
• Refine: Add specific criteria to broad rules
• Expand: Add detail to short rules
• Remove: Delete truly unused rules (requires human approval)

Report Storage

• Saved to: memory/audit-report.md
• Format: Markdown (human-readable)
• Includes: Date, findings, recommendations

CLI Usage

# Run audit and view report
npm run audit

# Output
🔍 Agent Constitution - Rule Audit
📘 [AuditorAgent] Auditing 4 rules...
⚠️ [AuditorAgent] Found 1 potential issues

# Rule Audit Report
[Full report displayed and saved]

Technical Implementation

• Class: agents/AuditorAgent.js
• Methods:
  • findRedundantRules() - Similarity detection
  • findOverlyBroadRules() - Specificity analysis
  • findUnusedRules() - Usage detection
  • generateAuditReport() - Report formatting
  • execute() - Main audit logic

Frequency

Recommended Schedule:

• After every 10 new rules added
• Monthly for active projects
• Before major releases
• When rule quality concerns arise

Human Involvement

The audit skill identifies issues but does not automatically fix them. All recommendations require human review and decision. This maintains human oversight of the constitution.