---
name: quality-audit
description: >
  Full quality audit with tech debt scan and quality scoring. Computes a
  quality score (0-100), detects code drift, copy-paste patterns, stale docs,
  and accumulating tech debt. Run after every 3 iterations or when quality
  feels like it's degrading. If score drops below threshold, next iteration
  must be debt cleanup.
---

# Quality Audit — Full Quality Assessment

Comprehensive quality check that goes beyond quality gates.

## When to use

- After every 3 development iterations (mandatory)
- After every 3 milestones (full deep audit)
- When quality gates pass but output quality feels degraded
- When the codebase has grown significantly since last audit

## Steps

### 1. Run quality gates

Run the primary quality gate command from `AGENTS.md` §5.

Record pass/fail status. If gates fail, fix before continuing the audit.

### 2. Compute quality score

Score the project across the **quality dimensions configured for this project**.

Quality dimensions are NOT fixed — they are discovered in Phase 0, confirmed with
the human in Phase 1d, and recorded in `docs/project_spec.md` (or `AGENTS.md`).

**How to read the configured dimensions:**
1. Read `docs/project_spec.md` quality dimensions section
2. Each dimension has a name, weight, and what to check
3. Score each configured dimension on 0-to-weight scale
4. Sum all scores; normalize to 0-100 if needed
5. If a dimension is marked `deferred` (not yet applicable), skip it — do not penalize

**Default dimensions** (use only if no project-specific configuration exists yet):

| Dimension | What to check | Default weight |
|---|---|---|
| **Test health** | Coverage %, all tests passing, no skipped tests. If the project has user-facing surfaces, also check E2E test coverage of critical paths. | 20 |
| **Lint cleanliness** | Zero warnings, zero suppressed rules | 20 |
| **Doc freshness** | The primary doc validation command passes, no stale content | 20 |
| **Architecture integrity** | No dependency violations, layers respected | 20 |
| **Code hygiene** | No duplicated blocks >20 lines, no dead code, consistent naming | 20 |

**Evolving dimensions during operation:**
- If the audit reveals a quality gap not covered by existing dimensions,
  recommend adding a new dimension and ask the human to confirm its weight
- If a dimension consistently scores full marks, consider merging or reducing its weight
- Record dimension changes in `docs/documentation.md` Decision Log

### 3. Detect code drift patterns

Scan for these anti-patterns:

- **Copy-paste drift**: Similar code blocks (>20 lines) appearing in multiple files.
  Fix: extract to shared utility module.
- **Inconsistent error handling**: Some modules use structured errors, others use
  bare throws/prints. Fix: standardize on structured errors with remediation hints.
- **Growing file sizes**: Any source file exceeding 500 lines.
  Fix: decompose into smaller modules.
- **Orphaned code**: Functions/classes not called from anywhere.
  Fix: remove or document why they're kept.
- **Dependency direction violations**: Imports that break the documented layer rules.
  Fix: refactor to respect architecture constraints.

### 4. Check tech debt accumulation

Review `docs/documentation.md` for patterns:
- Same module appearing in "adjust" or "rollback" decisions repeatedly
- Same failure type recurring across iterations
- Workarounds that were "temporary" but never cleaned up

### 5. Generate audit report

Update `docs/plan.md` Quality Score History table:

```
| Milestone | Score | Date | Notes |
|---|---|---|---|
| M0 | 85 | 2025-01-15 | Initial baseline |
| M1 | 82 | 2025-01-22 | Minor test coverage drop |
```

Also update `docs/project_spec.md` §6 Quality Score:
```
Current score: <new score> / 100
Last audit: <date>
```

Also update `docs/plan.md` Operations Cadence:
```
| quality-audit | Every 3 iterations | <date / iteration> | <next due iteration> | docs/documentation.md Quality Audit entry |
```

### 6. Record findings

Update `docs/documentation.md`:
- Refresh `## Current State` with the new validation status and next action
- Add or update `## Known Issues` when the audit discovers unresolved debt

```
## Quality Audit: <date>
- **Quality score**: <score>/100 (previous: <prev_score>)
- **Iteration covered**: <latest iteration number included in this audit>
- **Trend**: improving | stable | degrading
- **Issues found**: <count>
- **Critical issues**: <list>
- **Recommended actions**: <list>
```

### 7. Enforce threshold

**If quality score < 70**: the NEXT iteration MUST be debt cleanup, not feature work.
Do not proceed with new features until score is back above 70.

**If quality score dropped by >10 points since last audit**: investigate root cause
and add a new category to `docs/failures/taxonomy.md` if applicable.

### 8. Check harness health

Review the harness itself — not just the code:

- Count L2+ recovery events in the last N iterations (from `docs/documentation.md`)
- Count failure categories in `docs/failures/taxonomy.md` that lack a prevention action
- Check whether any `harness-improvement` entries in the Decision Log are still unresolved

If L2+ recovery frequency > 30% of recent iterations, or more than 3 failure
categories lack prevention actions, recommend a **harness improvement deliverable**
in the next iteration (update docs, add tools, tighten constraints, etc.).

If the agent is uncertain what harness change would help, ask the human.

Record harness health in the audit report:
```
- **Harness health**: <healthy | needs-attention | degrading>
- **L2+ recovery frequency**: <X out of last N iterations>
- **Unresolved failure categories**: <count without prevention actions>
- **Recommended harness changes**: <list or "none">
```

## What this skill produces

- Updated quality score in `docs/plan.md` and `docs/project_spec.md`
- Audit entry in `docs/documentation.md`
- Harness health assessment with recommended improvements
- Optionally: new failure categories in `docs/failures/taxonomy.md`
- Optionally: list of refactoring tasks to add to current milestone
