audit

What this skill does

# Comprehensive Design Audit

You are performing a deep, comprehensive audit of design artifact alignment across the project or a specified scope. This skill covers all six drift categories and produces a structured report with prioritized findings.

## Process

<!-- Governing: ADR-0016 (Workspace Mode), SPEC-0014 REQ "Artifact Path Resolution" -->

0. **Resolve artifact paths**: Follow the **Artifact Path Resolution** pattern from `references/shared-patterns.md` to determine the ADR and spec directories. If `$ARGUMENTS` contains `--module <name>`, resolve paths relative to that module; otherwise, in a workspace, aggregate across all modules. The resolved ADR directory is `{adr-dir}` and spec directory is `{spec-dir}`.

   <!-- Governing: ADR-0016 (Workspace Mode), SPEC-0014 REQ "Cross-Module Aggregation" -->

   **Cross-module aggregation**: When in aggregate mode (no `--module`, workspace detected), iterate over all discovered modules and run the full audit analysis (steps 4–6) per module. Label every finding with its source module in the output tables (add a `Module` column). After per-module analysis, include a **Cross-Module Summary** section that aggregates finding counts per module and highlights any cross-module inconsistencies (e.g., one module's ADR contradicting another module's spec). When `--module` is provided, scope to that single module — no module labels needed. When in single-module mode (no workspace), operate normally.

1. **Parse arguments**: Extract the scope and flags from `$ARGUMENTS`.
   - Scope can be a topic keyword (`security`, `api`, `database`), a directory path (`src/`), or omitted for a full project audit.
   - `--review`: Enable team review mode. Default: off. Mutually exclusive with: `--scrum`.
   - `--scrum`: Enable scrum triage ceremony. Default: off. Mutually exclusive with: `--review`.
   - `--module <name>`: Resolve artifact paths relative to the named module. Default: none.
   - If scope matches nothing, report: "No design artifacts or source files matched the scope \"{scope}\". Try a broader scope, or run `/sdd:audit` without a scope for a full project audit."

2. **Locate design artifacts**:
   - Scan `{adr-dir}` for ADR files. If the directory does not exist, report: "The `{adr-dir}` directory does not exist. Run `/sdd:adr [description]` to create your first ADR."
   - Scan `{spec-dir}` for spec files. If the directory does not exist, report: "The `{spec-dir}` directory does not exist. Run `/sdd:spec [capability]` to create your first spec."
   - If neither ADRs nor specs exist, report: "No design artifacts found. Create an ADR with `/sdd:adr` or a spec with `/sdd:spec` first."
   - It is valid for only ADRs or only specs to exist -- proceed with whatever is available and note which categories cannot be checked.

3. **Choose execution mode**: Check if `$ARGUMENTS` contains `--scrum` or `--review`. `--scrum` takes precedence over `--review` if both are present.

   **Default (no `--review`, no `--scrum`)**: Single-agent mode.
   - Perform the full analysis yourself across all six categories.
   - Self-review the findings for accuracy and completeness before producing the report.
   - Verify that severity assignments follow the rules in this document.

   **With `--review`** (and no `--scrum`): Team review mode.
   - Tell the user: "Creating an audit team to analyze and review findings. This takes a few minutes."
   - Create a Claude Team with `TeamCreate`:
     - Spawn an **auditor** agent (`general-purpose`) to perform the full analysis and write the audit report
     - Spawn a **reviewer** agent (`general-purpose`) to validate the auditor's findings for accuracy, completeness, and correct severity assignments
   - If `TeamCreate` fails, fall back to single-agent mode and tell the user: "Team creation failed. Proceeding with single-agent audit and self-review."

   **With `--scrum`**: Scrum triage mode — see the **Scrum Triage Ceremony** section below. When `--scrum` is set, complete the standard audit analysis (steps 4–6) first, then enter the ceremony. Do NOT run `--review` mode when `--scrum` is set.

3a. **Tier 3 staleness check** (v5.0.0+):

   <!-- Governing: ADR-0026 (Tiered Index Freshness), SPEC-0019 REQ "Tier 3 Staleness Threshold for Consumer Skills" -->

   On entry, check the qmd index's last-modified timestamp for this repo's collections (use the exact-prefix match algorithm from `references/qmd-helpers.md` § "This-Repo Collection Identification"). If older than the configured staleness threshold (default 120m, configurable in CLAUDE.md `### SDD Configuration` `#### Index Freshness` `**Staleness Threshold**` per the **Config Resolution** pattern), trigger a silent `qmd update` first. Emit a one-line note in the report header: `Index was {age} stale — refreshed before running.` On fresh, proceed silently. On qmd update failure, surface the error per `qmd-helpers.md` § "Error Handling" and continue best-effort.

3b. **qmd-aware artifact retrieval per target file** (v5.0.0+):

   <!-- Governing: ADR-0024 (qmd as hard dependency), SPEC-0019 REQ "qmd-Smart Drift Skills" -->

   Audit operates at scale across many target files. For each target file in scope, use qmd hybrid retrieval (per `references/qmd-helpers.md` § "Hybrid Retrieval") to identify the top-K candidate ADRs and specs governing that specific file, then deep-read only those candidates. The pre-v5 "read all ADRs and specs once, then semantically match against every target" path is removed in v5 — per-target qmd retrieval is the canonical mechanism.

   Per-file query construction follows the same pattern as `/sdd:check`:
   - `lex`: file path basename + exported symbols + governing comment block content
   - `vec`: one-sentence summary of what the file does
   - `intent: "/sdd:audit {scope} — find ADRs and specs governing {file}"`
   - `collections: ["{repo}-adrs", "{repo}-specs"]` (or per-module variants)
   - `limit: 8`, `minScore: 0.3`

   Per-target retrieval is more expensive than the pre-v5 single-pass scan, but produces dramatically tighter, file-relevant context for the drift analysis in Step 5. On large audit scopes (entire repo), this is what `/sdd:audit` was designed to scale to — the per-target retrieval is small per-call and runs in qmd's sub-second hybrid path.

   On qmd unreachable / timeout per `qmd-helpers.md` § "Error Handling", surface the error and stop. Per ADR-0024 / SPEC-0019 REQ "qmd Assumption in Consumer Skills", fallback paths were eliminated in v5; the failure mode is "fix qmd, retry."

4. **Validate spec artifact pairing**: For each spec directory found under `{spec-dir}`, check that both `spec.md` and `design.md` exist. If a `spec.md` exists without a corresponding `design.md` (or vice versa), report as `[WARNING]` under "Stale Artifacts" with finding: "Unpaired spec artifact: {path} exists but {missing-file} is missing. Per ADR-0003, spec.md and design.md are a paired unit." (Governing: ADR-0003, SPEC-0003)

5. **Analyze across all six categories**:

   **Code vs. Specification Drift**: Does the implementation match spec requirements and scenarios?
   - Read each spec's requirements and scenarios
   - Find implementing code files by semantic relevance
   - Check MUST/SHALL requirements -- violations are `[CRITICAL]`
   - Check SHOULD/RECOMMENDED requirements -- violations are `[WARNING]`
   - Check scenario coverage -- missing scenarios are `[WARNING]`

   **Code vs. ADR Drift**: Does the implementation follow accepted ADR decisions?
   - Read each accepted ADR's decision outcome and consequences
   - Find implementing code files
   - Check that the chosen approach is implemented -- violations are `[CRITICAL]`
   - Check architectural constraints -- violations are `[WARNING]`

   **ADR vs. Spec Inconsistencies**: Are ADR decisions consistent with spec requirements?
   - Cross-reference ADR decisions with related spec requirements
   - Check for contradictions -- contradictions are `[CRITICAL]`
   - Chec