audit

name	audit
description	Run a comprehensive backend quality audit across all eight dimensions. Orchestrates scan, critique, harden, distill, verify, and humanize skills, deduplicates findings, and produces a unified report with verdict. Use when assessing overall codebase health. Triggers: 'audit backend', 'full quality check', 'run audit', or /axiom:audit. Do NOT use for targeted checks — use individual skills instead.
user-invokable	true
metadata	{"author":"lvlup-sw","version":"0.1.0","category":"assessment","dimensions":["all"]}

Audit — Comprehensive Backend Quality Assessment

Overview

The anchor skill that orchestrates all other axiom skills to produce a comprehensive backend quality report. Runs deterministic checks and qualitative assessments across all 8 dimensions, deduplicates findings, computes per-dimension metrics, and delivers a unified verdict.

Triggers

Use when:

• Assessing overall codebase or module health
• Preparing for a release or major refactor
• Onboarding to understand existing technical debt
• User says "audit", "full quality check", "assess quality"

Do NOT use when:

• Targeting a specific concern (use axiom:critique, axiom:harden, axiom:distill, or axiom:verify directly)
• Running only deterministic checks (use axiom:scan)
• Performing workflow-specific review (workflow tools orchestrate axiom, not the reverse)

Process

Step 1: Scope Resolution

Determine the assessment scope from the scope argument:

• File: Assess a single file
• Directory: Assess all files in a directory (recursive)
• Codebase: Assess the entire project (default: current working directory)

Exclude by default: node_modules/, dist/, .git/, binary files, generated files.

Step 2: Deterministic Scan

Run axiom:scan with dimensions: all for the resolved scope. This produces the mechanical findings that ground the qualitative assessment.

Step 3: Qualitative Assessment

Run each specialized skill in sequence, passing the scope:

1. axiom:critique — Architecture (DIM-6) + Topology (DIM-1)
2. axiom:harden — Observability (DIM-2) + Resilience (DIM-7)
3. axiom:distill — Hygiene (DIM-5) + Topology (DIM-1)
4. axiom:verify — Test Fidelity (DIM-4) + Contracts (DIM-3)
5. axiom:humanize — Prose Quality (DIM-8)

Each skill produces findings in the standard format: @skills/backend-quality/references/findings-format.md

Step 4: Deduplicate and Aggregate

Merge findings from all skills using these rules:

• Same evidence + same dimension: Merge into single finding (keep most detailed explanation)
• Same evidence + different dimensions: Keep both (finding genuinely spans two concerns)
• Same pattern + different files: Keep as separate findings
• Deterministic + qualitative for same issue: Merge, mark as deterministic: true

Step 5: Coverage Check

Verify all 8 dimensions were assessed. If any dimension has zero findings and zero checks:

• Warning: "DIM-N ({name}) was not assessed — no checks or findings produced"
• This may indicate the scope doesn't contain code relevant to that dimension

Step 6: Compute Verdict

Apply the verdict exactly as defined in @skills/backend-quality/references/scoring-model.md (single source of truth). Do not redefine thresholds here; compute and report the inputs required by the model (HIGH/MEDIUM/LOW counts).

Compute per-dimension metrics:

• Pass rate (deterministic checks only)
• Finding count (all findings)
• Severity distribution (HIGH / MEDIUM / LOW)

Step 7: Produce Report

Output the structured report per the template in @skills/backend-quality/references/scoring-model.md:

# Backend Quality Report

**Scope:** [assessed scope]
**Verdict:** [CLEAN | NEEDS_ATTENTION]
**Date:** [current date]

## Summary
[Per-dimension table with findings, severity counts, pass rates]

## HIGH-Priority Findings
[Findings requiring immediate attention]

## MEDIUM-Priority Findings
[Findings to address soon]

## LOW-Priority Findings
[Polish and minor items]

## Dimensional Coverage
[Which dimensions assessed, any gaps]

## Recommendations
[Top 3-5 prioritized action items]

Pairing Contract Check

When the assessed scope contains a project-specific invariants skill (any loaded skill with frontmatter pairs-with: axiom:design), audit runs an advisory check against the pairing contract documented at @skills/backend-quality/references/pairing-contract.md.

Two checks, both LOW severity, both advisory only:

1. Overlap declaration. The paired skill must declare axiom_overlap: DIM-N for at least one of its invariants. A paired skill with zero overlap declarations is technically compliant (axiom_overlap is optional per the contract) but suggests the pairing isn't specializing axiom dimensions in any documented way — likely a documentation gap.
2. Overlap validity. Each declared axiom_overlap value must reference a real dimension (DIM-1 through DIM-8). Typos like DIM-9 or DIM-1A are flagged.

Severity rationale. Pairing-contract violations don't break functionality; they erode the design-time interleaving experience over time. LOW severity reflects that. These findings never escalate the audit verdict beyond NEEDS_ATTENTION and never produce HIGH/MEDIUM unless other findings independently warrant them.

Output format. Findings carry dimension: pairing-contract (a meta dimension distinct from DIM-1..DIM-8) so reviewers can filter them when desired:

{
  "severity": "LOW",
  "dimension": "pairing-contract",
  "skill": "exarchos:design-invariants",
  "description": "Paired skill declares pairs-with: axiom:design but no invariant has an axiom_overlap declaration.",
  "required_fix": "Add axiom_overlap: DIM-N to at least one invariant, or update the pairing-contract declaration to reflect that this skill is project-specific without dimension overlap."
}

Error Handling

• Empty scope (no files to assess): Return "Nothing to assess — no files found in scope" with verdict CLEAN
• Partial skill failure: If one skill errors, continue with the remaining skills. Report the error in the output: "axiom:{skill} encountered an error: {message}. Results from other skills are still valid."
• Scope validation: Verify file/directory exists before starting. If not found: "Scope not found: {path}"

Composition Guide

For details on how audit discovers skills, handles deduplication, and formats reports, see @skills/audit/references/composition-guide.md.

References

• Dimension taxonomy: @skills/backend-quality/references/dimensions.md
• Finding format: @skills/backend-quality/references/findings-format.md
• Scoring model: @skills/backend-quality/references/scoring-model.md
• Composition details: @skills/audit/references/composition-guide.md
• Pairing contract: @skills/backend-quality/references/pairing-contract.md