Quality Auditor

Quality Auditor

Overview

Evaluates tools, frameworks, systems, and codebases against the highest industry standards across 12 weighted dimensions. Produces evidence-based scores, identifies anti-patterns, and generates prioritized improvement roadmaps. Applies extra scrutiny to AI-generated code through the verification gap protocol, ensuring velocity does not compromise integrity.

When to use: Auditing code quality, reviewing AI-generated code, scoring codebases against industry benchmarks, enforcing pre-commit quality gates, comparing tools or frameworks, assessing technical debt.

When NOT to use: Quick code reviews without scoring, style-only linting (use a linter), feature implementation, routine PR reviews that do not require a full audit.

Quick Reference

Audit Phases

Scoring Scale

Common Mistakes

Delegation

• Discover codebase structure and gather audit evidence: Use Explore agent to survey file organization, dependencies, test coverage, and documentation
• Execute targeted quality checks across dimensions: Use Task agent to run linters, security scanners, performance profilers, and accessibility audits
• Design quality improvement roadmap: Use Plan agent to prioritize quick wins, short-term, and long-term recommendations from audit findings

For stylistic cleanup of AI-generated prose and code (emdash overuse, slop vocabulary, over-commenting, verbose naming), use the de-slopify skill.

>

If the usability-tester skill is available, delegate usability dimension evaluation and user flow validation to it.

Otherwise, recommend: pnpm dlx skills add oakoss/agent-skills -s usability-tester -a claude-code -y

References

• Audit Rubric -- pass/warn/fail thresholds, weighted scoring methodology, automated vs manual checklists, score caps, report format
• Dimension Rubrics -- detailed scoring criteria, evidence requirements, and rubric tables for all 12 dimensions
• Audit Report Template -- structured report format, executive summary, recommendations, risk assessment
• Anti-Patterns Guide -- code, architecture, security, testing, and process anti-patterns to identify during audits
• Verification Gap Protocol -- AI code verification methodology, critic agents, rejection protocol, risk-based review strategies

Anti-Patterns Guide

A catalog of anti-patterns to identify during quality audits, organized by category. Each anti-pattern includes detection strategies and severity levels.

Code Anti-Patterns

Detection Strategies

# Find functions over 50 lines (approximate)
rg -c "^}" -g "*.ts" | sort -t: -k2 -rn | head -20

# Find potential magic numbers
rg "\b(?:100|200|404|500|1000|3600|86400)\b" -g "*.ts" --stats

# Find duplicated string literals
rg -o '"[^"]{10,}"' -g "*.ts" --no-filename | sort | uniq -c | sort -rn | head -10

# Find deeply nested code
rg "^\s{16,}" -g "*.ts" -c | sort -t: -k2 -rn

# Find type bypassing
rg "(: any|as any|@ts-ignore|@ts-expect-error)" -g "*.ts" --stats

# Find debug artifacts
rg "console\.(log|debug|info|warn)" -g "*.ts" -g "!*.test.*" -g "!*.spec.*"

Architecture Anti-Patterns

Detection Strategies

# Find files importing from many different modules (high fan-out)
rg -c "^import" -g "*.ts" | sort -t: -k2 -rn | head -20

# Find circular imports (approximate -- look for mutual references)
rg "^import.*from" -g "*.ts" --no-heading | sort > /tmp/imports.txt

# Find barrel files that re-export everything (coupling amplifier)
rg "^export \* from" -g "index.ts" -g "index.tsx"

Security Anti-Patterns

Detection Strategies

# Find potential hardcoded secrets
rg -i "(api.?key|secret|password|token)\s*[:=]" -g "*.ts" -g "!*.test.*"

# Find potential SQL injection
rg "query\(.*\$\{" -g "*.ts"
rg "execute\(.*\+" -g "*.ts"

# Find missing auth checks in API routes
rg "export (async )?function (GET|POST|PUT|DELETE)" -g "*/api/**/*.ts" -l

# Find potential XSS in React (dangerouslySetInnerHTML)
rg "dangerouslySetInnerHTML" -g "*.tsx"

# Check for sensitive data in logs
rg "console\.\w+\(.*(?:password|secret|token|key)" -g "*.ts" -i

Testing Anti-Patterns

Detection Strategies

# Check test coverage
npx vitest --coverage --reporter=json

# Find tests without assertions
rg "it\(|test\(" -A 20 -g "*.test.*" | rg -v "expect\(|assert"

# Find snapshot-heavy test files
rg "toMatchSnapshot|toMatchInlineSnapshot" -c -g "*.test.*" | sort -t: -k2 -rn

# Find tests with timeouts (flaky test signal)
rg "setTimeout|waitFor|sleep" -g "*.test.*" -c | sort -t: -k2 -rn

Process Anti-Patterns

Pre-Commit Audit Checklist

Before declaring any task finished, verify:

1. Contract integrity -- code matches defined interfaces (Zod schemas, TypeScript types) 2. Architectural alignment -- idiomatic patterns for the stack in use 3. Security sanitization -- all inputs validated, no secrets in logs or code 4. Performance hygiene -- no N+1 queries, images optimized, bundle size checked 5. Cleanliness audit -- no console.log, debug artifacts, or commented-out code 6. Traceability -- the "why" is documented for non-obvious decisions (comments or ADRs)

Risk-Based PR Categorization

Categorize changes by risk level to allocate review effort appropriately:

Route high-risk changes to domain experts. Auto-approve low-risk, well-scoped changes that pass automated gates. Flag unrelated changes bundled in the same PR for separation.

Audit Report Template

Use this template structure when producing quality audit reports. Every section requires evidence -- no scores without justification.

Phase 0: Resource Completeness Check

This check is mandatory before scoring. The audit must fail if resources are incomplete.

Verification steps:

1. Count resources in directories vs registry entries (must match) 2. Verify all resources in filesystem are discoverable through the registry 3. Check cross-references point to existing entries 4. Verify CLI reads from registry (not hardcoded data)

Critical failure conditions (cap overall score at 6/10):

• Registry missing >10% of resources from directories
• README documents resources not in registry
• CLI uses mock/hardcoded data instead of registry
• Cross-references point to non-existent resources

Report Template

# Quality Audit Report: [Tool/System Name]

**Date:** [Date]
**Version Audited:** [Version]
**Auditor:** [Agent/Skill name]

---

## Executive Summary

**Overall Score:** [X.X]/10 - [Rating]

**Rating Scale:**

- 9.0-10.0: Exceptional
- 8.0-8.9: Excellent
- 7.0-7.9: Very Good
- 6.0-6.9: Good
- 5.0-5.9: Acceptable
- Below 5.0: Needs Improvement

**Key Strengths:**

1. [Strength 1 with evidence -- file path, metric, or example]
2. [Strength 2 with evidence]
3. [Strength 3 with evidence]

**Critical Areas for Improvement:**

1. [Weakness 1 with specific file references]
2. [Weakness 2 with specific file references]
3. [Weakness 3 with specific file references]

**Recommendation:** [Exceptional / Excellent / Very Good / Good / Acceptable / Needs Improvement]

---

## Detailed Scores

| Dimension            | Weight | Score | Rating   | Priority          |
| -------------------- | ------ | ----- | -------- | ----------------- |
| Code Quality         | 10%    | X/10  | [Rating] | [High/Medium/Low] |
| Architecture         | 10%    | X/10  | [Rating] | [High/Medium/Low] |
| Documentation        | 10%    | X/10  | [Rating] | [High/Medium/Low] |
| Usability            | 10%    | X/10  | [Rating] | [High/Medium/Low] |
| Performance          | 8%     | X/10  | [Rating] | [High/Medium/Low] |
| Security             | 10%    | X/10  | [Rating] | [High/Medium/Low] |
| Testing              | 8%     | X/10  | [Rating] | [High/Medium/Low] |
| Maintainability      | 8%     | X/10  | [Rating] | [High/Medium/Low] |
| Developer Experience | 10%    | X/10  | [Rating] | [High/Medium/Low] |
| Accessibility        | 8%     | X/10  | [Rating] | [High/Medium/Low] |
| CI/CD                | 5%     | X/10  | [Rating] | [High/Medium/Low] |
| Innovation           | 3%     | X/10  | [Rating] | [High/Medium/Low] |

**Overall Score:** [Weighted Average]/10

---

## Dimension Analysis

### [N]. [Dimension Name]: [Score]/10

**Rating:** [Excellent/Good/Acceptable/Poor]

**Strengths:**

- [Specific strength with file reference]

**Weaknesses:**

- [Specific weakness with file reference]

**Evidence:**

- [Code examples, metrics, tool output]

**Improvements:**

1. [Specific actionable improvement]

[Repeat for all 12 dimensions]

---

## Recommendations

### Immediate Actions (Quick Wins) -- 1-2 weeks

1. **[Action]**
   - Impact: High
   - Effort: Low
   - Timeline: [X] days

### Short-term Improvements -- 1-3 months

1. **[Improvement]**
   - Impact: Medium-High
   - Effort: Medium
   - Timeline: [X] weeks

### Long-term Strategic -- 3-12 months

1. **[Strategic improvement]**
   - Impact: High
   - Effort: High
   - Timeline: [X] months

---

## Risk Assessment

### High-Risk Issues

**[Issue]:**

- Risk Level: Critical/High
- Impact: [Description]
- Mitigation: [Specific steps]

### Medium-Risk Issues

[List with same format]

### Low-Risk Issues

[List with same format]

---

## Comparative Analysis

| Feature/Aspect | [This Tool] | [Leader 1] | [Leader 2] |
| -------------- | ----------- | ---------- | ---------- |
| [Aspect]       | [Score]     | [Score]    | [Score]    |

---

## Quality Metrics

| Metric           | Result | Target   | Status      |
| ---------------- | ------ | -------- | ----------- |
| Code Coverage    | [X]%   | 80%+     | [Pass/Fail] |
| Complexity Avg   | [X]    | <15      | [Pass/Fail] |
| Dependency Vulns | [X]    | 0 high   | [Pass/Fail] |
| Bundle Size      | [X] KB | [Budget] | [Pass/Fail] |

---

## Conclusion

[Summary of findings, overall assessment, final recommendation]

**Final Verdict:** [Detailed recommendation with next steps]

Weighted Score Calculation

Calculate the overall score using dimension weights:

Overall = (CodeQuality * 0.10) + (Architecture * 0.10) + (Documentation * 0.10)
        + (Usability * 0.10) + (Performance * 0.08) + (Security * 0.10)
        + (Testing * 0.08) + (Maintainability * 0.08) + (DX * 0.10)
        + (Accessibility * 0.08) + (CICD * 0.05) + (Innovation * 0.03)

Round to one decimal place. Apply any caps (Phase 0 failure caps at 6.0).

Evidence Standards

Every score must include at least one of:

• File reference -- specific path and line number
• Metric -- quantitative measurement from a tool
• Code example -- concrete snippet demonstrating the issue
• Tool output -- scan results, coverage reports, benchmark data

Scores without evidence are invalid. If a dimension cannot be evaluated (e.g., no UI means accessibility is not applicable), note it as "N/A" and redistribute the weight proportionally.

The Rejection Protocol

If the audit fails any critical check:

1. Stop -- do not proceed with the commit or final report 2. Analyze -- identify the specific deviation from standards 3. Remediate -- apply the fix immediately 4. Re-audit -- restart the checklist from Phase 0

Audit Rubric

A structured rubric for executing quality audits with clear pass/warn/fail thresholds, weighted scoring, and a distinction between automated and manual audit items.

Pass / Warn / Fail Thresholds

Each dimension receives a 1-10 score, then maps to a threshold:

Hard fail conditions (override any score):

• Phase 0 resource completeness fails -- cap overall at 6.0
• Any security dimension score of 3 or below -- flag as release blocker
• Any critical anti-pattern found without a mitigation plan -- fail the audit

Dimension Rubric Summary

Each dimension uses consistent criteria across three levels. See dimension-rubrics.md for full per-dimension detail.

Code Quality (10%)

Architecture (10%)

Documentation (10%)

Usability (10%)

Performance (8%)

Security (10%)

Testing (8%)

Maintainability (8%)

Developer Experience (10%)

Accessibility (8%)

CI/CD (5%)

Innovation (3%)

Weighted Scoring Methodology

Calculating the Overall Score

Multiply each dimension score by its weight, then sum:

Overall = (CodeQuality * 0.10) + (Architecture * 0.10) + (Documentation * 0.10)
        + (Usability * 0.10) + (Performance * 0.08) + (Security * 0.10)
        + (Testing * 0.08) + (Maintainability * 0.08) + (DX * 0.10)
        + (Accessibility * 0.08) + (CICD * 0.05) + (Innovation * 0.03)

Round to one decimal place.

Handling N/A Dimensions

When a dimension does not apply, redistribute its weight proportionally:

Example: CLI tool with no UI -- Accessibility (8%) is N/A

Remaining weight = 100% - 8% = 92%
Adjusted weights = each remaining dimension weight / 0.92

Code Quality: 10% / 0.92 = 10.9%
Security: 10% / 0.92 = 10.9%
...

Weight Adjustments by Project Type

Customize weights based on what matters most:

Document any weight adjustments in the audit report with justification.

Score Caps

Apply the lowest applicable cap.

Automated vs Manual Audit Items

Automated Checks (Run First)

These checks produce objective, repeatable results. Run them before manual review.

Manual Review Items

These require human or AI judgment. Perform after automated checks pass.

Audit Execution Order

1. Run all automated checks and collect results 2. If any automated check fails, stop and remediate before manual review 3. Perform manual review items, scoring each dimension 4. Calculate weighted overall score 5. Apply score caps if any hard-fail conditions triggered 6. Generate the audit report

Audit Report Format

Structure every audit report with these sections in order:

# Quality Audit Report: [Subject]

**Date:** [Date]
**Version:** [Version]
**Auditor:** [Agent or person]

## Executive Summary

**Overall Score:** [X.X]/10 - [Pass/Warn/Fail]

**Top 3 Strengths:** [With evidence]
**Top 3 Weaknesses:** [With evidence]
**Recommendation:** [Exceptional / Excellent / Good / Acceptable / Needs Improvement]

## Automated Gate Results

| Gate | Result | Details |
| ---- | ------ | ------- |

## Dimension Scores

| Dimension | Weight | Score | Level | Evidence Summary |
| --------- | ------ | ----- | ----- | ---------------- |

**Weighted Overall:** [X.X]/10
**Caps Applied:** [None / list]

## Findings by Priority

### Critical (Fix Before Release)

### High (Fix This Sprint)

### Medium (Plan for Next Sprint)

### Low (Backlog)

## Recommendations

### Quick Wins (High Impact / Low Effort)

### Short-Term (1-3 Months)

### Long-Term (3-12 Months)

## Risk Matrix

| Risk | Likelihood | Impact | Mitigation |
| ---- | ---------- | ------ | ---------- |

See audit-report-template.md for the full template with all subsections.

Calibration Guidelines

To maintain consistent scoring across audits:

• 10/10 is rare -- reserved for industry-leading implementations (Linux kernel code quality, Stripe documentation)
• Most quality software scores 6-7 -- this is the realistic baseline
• A score of 8+ means genuinely above average -- requires strong evidence
• Compare against industry leaders, not team averages or personal standards
• Every score needs evidence -- file paths, metrics, tool output, or concrete examples
• Scores without evidence are invalid -- reject them during review

Dimension Rubrics

Each of the 12 dimensions requires specific evaluation criteria, evidence, and a scoring rubric. Weights total 100% and can be adjusted based on the project type and priorities.

Scoring Principles

• Compare against industry leaders, not average tools
• Reference established standards (OWASP, WCAG, IEEE, ISO)
• Consider real-world usage and edge cases
• Provide specific examples for each score -- cite file paths, line numbers, metrics
• 10/10 is rare -- reserved for truly exceptional, industry-leading work
• Most quality tools score 6-7 -- this is the realistic baseline

1. Code Quality (10%)

Evaluate: Structure, naming conventions, duplication, cyclomatic/cognitive complexity, error handling, code smells, design patterns, SOLID principles.

Evidence required:

• Specific file examples with line references
• Complexity metrics (cyclomatic, cognitive)
• Pattern identification (design patterns used or missing)
• Duplication analysis results

Key checks:

# Find functions over 50 lines (approximate complexity signal)
rg -c "^}" -g "*.ts" | sort -t: -k2 -rn | head -20

# Find potential magic numbers
rg "\b(?:100|200|404|500|1000|3600|86400)\b" -g "*.ts" --stats

# Find duplicated string literals
rg -o '"[^"]{10,}"' -g "*.ts" --no-filename | sort | uniq -c | sort -rn | head -10

2. Architecture (10%)

Evaluate: System design, modularity, separation of concerns, scalability, dependency management, API design, data flow, coupling/cohesion, architectural patterns.

Evidence required:

• Component analysis and dependency graph
• Coupling/cohesion assessment
• Architectural fitness for stated requirements
• API design consistency

Key checks:

# Find files importing from many different modules (high fan-out)
rg -c "^import" -g "*.ts" | sort -t: -k2 -rn | head -20

# Find deeply nested code (architectural complexity signal)
rg "^\s{16,}" -g "*.ts" -c | sort -t: -k2 -rn

3. Documentation (10%)

Evaluate: Completeness, clarity, accuracy, organization, practical examples, API docs, troubleshooting guides, architecture docs.

Evidence required:

• Documentation inventory (what exists vs what should exist)
• Missing sections identified
• Quality assessment of examples (do they work?)
• Accuracy check (does documentation match implementation?)

4. Usability (10%)

Evaluate: Learning curve, installation ease, configuration complexity, workflow efficiency, error message quality, defaults, command/API ergonomics.

Evidence required:

• Time-to-first-success measurement
• Pain points identified during testing
• Error message quality assessment
• Default configuration adequacy

5. Performance (8%)

Evaluate: Execution speed, resource usage (CPU, memory), startup time, scalability under load, optimization techniques, caching, database queries, bundle size.

Evidence required:

• Benchmarks (startup time, operation latency)
• Resource measurements (memory, CPU)
• Bottleneck identification
• N+1 query detection (if applicable)
• Bundle size analysis (if applicable)

6. Security (10%)

Evaluate: Vulnerability assessment, input validation, authentication/authorization, data encryption, dependency vulnerabilities, secret management, OWASP Top 10.

Evidence required:

• Vulnerability scan results (npm audit, Snyk, Semgrep)
• OWASP Top 10 checklist completion
• Input validation coverage
• Secret management audit

Key checks:

# Find potential hardcoded secrets
rg -i "(api.?key|secret|password|token)\s*[:=]" -g "*.ts" -g "!*.test.*"

# Find potential SQL injection
rg "query\(.*\$\{" -g "*.ts"

# Check dependency vulnerabilities
npm audit --json | jq '.vulnerabilities | length'

7. Testing (8%)

Evaluate: Coverage (unit/integration/e2e), test quality, automation, CI integration, test organization, mocking strategies, performance tests, security tests.

Evidence required:

• Coverage reports with branch/line/function breakdown
• Test inventory (unit vs integration vs e2e ratio)
• Test quality assessment (do tests verify behavior or implementation?)
• CI integration status

8. Maintainability (8%)

Evaluate: Technical debt, code readability, refactorability, modularity, developer documentation, contribution guidelines, code review process, versioning strategy.

Evidence required:

• Technical debt analysis (TODO/FIXME count, deprecated API usage)
• Contribution difficulty assessment
• Versioning strategy evaluation (semver compliance)
• Dependency freshness (outdated packages)

9. Developer Experience (10%)

Evaluate: Setup ease, debugging experience, error messages, tooling support, hot reload/fast feedback, CLI ergonomics, IDE integration.

Evidence required:

• Setup time measurement (clone to running)
• Developer pain points during evaluation
• Tooling assessment (TypeScript, linting, formatting)
• Feedback loop speed (save to result)

10. Accessibility (8%)

Evaluate: WCAG compliance, keyboard navigation, screen reader support, color contrast, cognitive load, inclusive design.

Evidence required:

• WCAG 2.2 AA/AAA audit results
• Keyboard navigation testing
• Screen reader compatibility
• Color contrast ratios

11. CI/CD (5%)

Evaluate: Automation level, build pipeline, testing automation, deployment automation, release process, monitoring/alerts, rollback capabilities.

Evidence required:

• Pipeline configuration review
• DORA metrics assessment (deployment frequency, lead time for changes, change failure rate, time to restore service, reliability)
• Rollback capability verification

12. Innovation (3%)

Evaluate: Novel approaches, creative solutions, forward-thinking design, industry leadership, unique value proposition.

Evidence required:

• Novel features or approaches identified
• Comparison with alternatives in the ecosystem
• Industry impact or influence assessment

Special Evaluation Criteria

Developer Tools

Additional factors: setup time (<5 min = 10/10), error message quality, debugging experience, community support, IDE integration depth.

Frameworks and Libraries

Additional factors: bundle size, tree-shaking support, TypeScript support (strict mode), browser compatibility, migration path from previous versions.

CLI Tools

Additional factors: one-command simplicity, automatic defaults, clear visual feedback (progress indicators, colors), minimal required decisions, forgiving design (easy undo, backups).

Industry Benchmarks

Standards Referenced

• Code Quality: Clean Code (Martin), Code Complete (McConnell), SonarQube quality gates
• Architecture: Clean Architecture (Martin), Domain-Driven Design (Evans)
• Security: OWASP Top 10, SANS Top 25, CWE/SANS
• Accessibility: WCAG 2.2 (AA/AAA), inclusive design guidelines
• Testing: Test Pyramid (Cohn), 80% minimum coverage target
• Performance: Core Web Vitals, RAIL model (Google), performance budgets

Verification Gap Protocol

AI-assisted development accounts for a significant and growing share of committed code. The bottleneck has shifted from writing code to reviewing, validating, and governing it. This protocol ensures velocity does not compromise integrity.

The Verification Gap

The verification gap is the distance between what AI-generated code appears to do and what it actually does in production. AI output can produce functions that compile and pass basic tests yet introduce redundancy, fragile logic, security vulnerabilities, or compliance risks.

Key risks of unverified AI code:

• Compiles and runs but contains subtle logic errors
• Passes unit tests but fails under real-world edge cases
• Introduces architectural drift by not following project conventions
• Creates security vulnerabilities through incomplete input validation
• Adds unnecessary complexity or dead code paths
• Generates plausible but incorrect implementations of business rules

Closing the Gap

1. Critic Agent Pattern

Use high-reasoning models to audit the output of faster code-generation models. The critic agent reviews with a different perspective than the generator.

Critic agent responsibilities:

• Verify contract integrity (does output match interfaces, schemas, types?)
• Check architectural alignment (does it follow project patterns?)
• Validate security sanitization (are inputs validated, secrets protected?)
• Assess performance hygiene (N+1 queries, bundle size, resource usage)
• Confirm cleanliness (no debug artifacts, commented-out code, TODOs)

How to implement:

// Example: structured audit output from a critic agent
type AuditResult = {
  dimension: string;
  score: number;
  evidence: string[];
  issues: Array<{
    severity: 'critical' | 'high' | 'medium' | 'low';
    file: string;
    line: number;
    description: string;
    suggestion: string;
  }>;
};

2. Verifiable Goals

Every PR must produce a measurable signal of success. No code merges without at least one verifiable gate passing.

Required signals:

Verification script example:

#!/usr/bin/env bash
set -euo pipefail

echo "Running verification gates..."

echo "1. Type check"
npx tsc --noEmit --strict

echo "2. Lint"
npx eslint . --max-warnings 0

echo "3. Tests"
npx vitest run --coverage

echo "4. Build"
npm run build

echo "5. Security audit"
npm audit --audit-level=high

echo "All gates passed."

3. Human Oversight

Mandatory human sign-off for critical paths. Not all code requires the same level of review.

Critical paths requiring human review:

• Authentication and authorization logic
• Payment processing and financial calculations
• Data migration and schema changes
• Cryptographic operations
• Privacy-sensitive data handling (PII, HIPAA, GDPR)
• Infrastructure and deployment configuration

Standard paths for automated review:

• UI component styling
• Test additions for existing features
• Documentation updates
• Dependency version bumps (with passing gates)
• Configuration file changes

AI Code Standards

Excellence Over Mimicry

Do not repeat bad local patterns just because they exist in the codebase. AI-generated code should follow idiomatic standards for the stack, even if existing code does not.

// BAD: Mimicking a poor existing pattern found in the codebase
function getUser(id: any) {
  const res: any = db.query(`SELECT * FROM users WHERE id = ${id}`);
  return res;
}

// GOOD: Idiomatic, type-safe, parameterized
async function getUser(id: string): Promise<User | null> {
  return db.user.findUnique({ where: { id } });
}

No Black Boxes

Every complex function must explain its reasoning. AI-generated code is particularly prone to producing "it works" implementations without documenting non-obvious decisions.

// BAD: No explanation for the magic
function calculateDiscount(total: number): number {
  return total > 100 ? total * 0.85 : total > 50 ? total * 0.9 : total;
}

// GOOD: Business rules documented
function calculateDiscount(total: number): number {
  // Tiered discount per 2024 pricing agreement:
  // - Orders over $100: 15% discount
  // - Orders over $50: 10% discount
  // - Below $50: no discount
  if (total > 100) return total * 0.85;
  if (total > 50) return total * 0.9;
  return total;
}

Metadata Tagging

Tag AI-generated files for future auditing. This helps track which code was generated vs hand-written, enabling targeted reviews during audits.

// @generated - AI-assisted implementation
// @audit-date - 2026-01-15
// @generator - claude-opus-4-5

The Rejection Protocol

If the audit fails any check in the supreme checklist:

Step 1: Stop

Do not proceed with the commit, push, or report. A failed audit means the code is not ready.

Step 2: Analyze

Identify the specific deviation:

• Which gate failed?
• What is the root cause?
• Is this a pattern issue or an isolated problem?

Step 3: Remediate

Apply the fix immediately. Do not defer:

• Fix the type error, not suppress it
• Add the missing test, not skip the check
• Resolve the security issue, not add a TODO
• Correct the pattern, not document the workaround

Step 4: Re-Audit

Restart the checklist from step 1. A partial re-run is not sufficient because fixes can introduce new issues.

The Supreme Audit Checklist

Before any AI-generated code is accepted:

Context-Aware Review

Surface-level static analysis catches formatting and basic lint issues but misses deeper problems. Effective AI code review must also assess:

• Architectural fit -- does the change align with the system's design direction?
• Requirement alignment -- does the implementation match what was actually requested?
• Convention consistency -- does the code follow the team's established patterns?
• Future maintainability -- will this code be easy to modify in six months?
• Integration safety -- does the change interact correctly with existing code?

Quality Metrics for AI Code

Track these metrics to measure the effectiveness of AI code review: