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