Sw Audit

---
name: sw-audit
description: >-
  Periodic codebase health check. Analyzes architecture, complexity,
  consistency, and debt across the full codebase. Produces persistent
  findings in AUDIT.md.
argument-hint: "[path | --full]"
allowed-tools:
  - Read
  - Write
  - Glob
  - Grep
  - Task
---

# Specwright Audit

## Goal

Find systemic codebase issues that per-change quality gates miss.
Architecture debt, complexity growth, convention drift, and accumulated
workarounds compound silently. Surface them, let the user prioritize,
and persist findings for future design cycles.

## Inputs

- The codebase itself
- `{projectArtifactsRoot}/CONSTITUTION.md` -- practices to check against
- `{projectArtifactsRoot}/AUDIT.md` -- prior findings (if exists, for ID matching)
- `{projectArtifactsRoot}/LANDSCAPE.md` -- module structure (if exists, for triage)
- `{projectArtifactsRoot}/config.json` -- audit config (optional `audit` section)

## Outputs

- `{projectArtifactsRoot}/AUDIT.md` -- findings per `protocols/audit.md` format
- Findings presented to user grouped by dimension before saving

## Constraints

**Scope (LOW freedom):**
- This skill reads and analyzes. It NEVER modifies source code, creates branches, runs builds, or starts work units.
- Does NOT create `currentWork` in workflow.json. Does NOT require a lock. Can run while a work unit is in progress.
- It is not a core workflow stage and never claims top-level work ownership.
- On compaction: re-run from scratch (no state to recover).

**Triage (MEDIUM freedom):**
- Determine audit depth from argument and codebase size:
  - Path argument → **Focused**: analyze specified directory/module only
  - `--full` argument → **Full**: parallel agents, all dimensions
  - No argument → auto-triage: Standard (<50 files) or Full (50+ files)
- If LANDSCAPE.md exists, use module count to inform triage.

**Analysis (HIGH freedom):**
- Four dimensions: architecture, complexity, consistency, debt.
- Delegate per `protocols/delegation.md`:
  - `specwright-architect`: architecture + complexity (structural analysis)
  - `specwright-reviewer`: consistency + debt (convention and quality analysis)
- Standard depth: 2 agent calls (sequential or parallel).
- Full depth: up to 4 parallel calls (one per dimension).
- Include constitution practices as the baseline for consistency checks.

**Synthesis (LOW freedom):**
- Agents return raw findings. The skill itself aggregates results.
- If prior AUDIT.md exists: match findings per `protocols/audit.md` (dimension + location). Reuse matched IDs, assign new IDs for unmatched. Mark unmatched prior findings as stale.
- Purge resolved findings older than 90 days.
- Enforce size cap per protocol. Write AUDIT.md.

**Presentation (MEDIUM freedom):**
- Show findings grouped by dimension. For each: severity, location, description, impact.
- Apply `protocols/decision.md` CURATION for severity and export decisions:
  - Cascading impact → BLOCKER. Auto-export to backlog as BL-{n} with `finding` tag.
  - Isolated impact → WARN. Stays in AUDIT.md only.
  - The finding remains in AUDIT.md regardless; backlog items are for action tracking.
- Maximum 20 findings per run. If more, keep highest-severity.

## Protocol References

- `protocols/audit.md` -- finding format, IDs, matching, lifecycle
- `protocols/delegation.md` -- agent delegation
- `protocols/decision.md` -- autonomous decision framework (CURATION for severity)
- `protocols/context.md` -- config and anchor doc loading
- `protocols/backlog.md` -- backlog item format and write targets

## Failure Modes

| Condition | Action |
|-----------|--------|
| No codebase files found | STOP: "No source files to audit." |
| Agents unavailable | Fall back to inline analysis (less thorough) |
| Prior AUDIT.md parse error | WARN, start fresh (no ID continuity) |
| Compaction during audit | Re-run from scratch |