#+TITLE: Code-Quality Sweep Workflow
#+AUTHOR: Craig Jennings & Claude
#+DATE: 2026-06-28

* Overview

One trigger that runs every behavior-preserving quality pass over a scope of
*existing* code, in order, then surfaces what got filed for later. It's a thin
orchestrator — each pass keeps its own discipline and its own confirm gate; this
workflow only sequences them and collects the residue.

The passes it chains:

1. =/refactor= — structural and logic cleanup on measurable metrics (complexity,
   duplication, dead-code) plus the simplification lens.
2. =readability-audit= ([[file:readability-audit.org][readability-audit.org]]) — prose and human-reader clarity
   (comments, file headers, names, organization).

It deliberately does *not* run =/simplify=: that works the current uncommitted
diff, not existing committed code, so it belongs to the moment you've just made a
change, not to a sweep of code already in the tree (see "The /simplify boundary"
below).

* When to Use This Workflow

- "code quality sweep" / "quality sweep"
- "run every quality pass on <scope>" / "full quality pass on <scope>"
- "give me every pass on <file/module/tree>"

Do NOT use it for:
- *In-flight diff cleanup* — that's =/simplify= on the change you just made.
- *Bug hunting* — these passes are behavior-preserving; for defects use =debug=
  or =/review-code=.
- *Performing the structural refactors it files* — those become =:refactor:=
  tasks; work them later via =/refactor rename= / =/refactor simplification= or
  =/start-work=.

* Steps

** 1. Scope

Pick the target: one file, a named module set, or the whole tree (honor
=.aiignore=). The same scope is passed to both passes so they cover the same
code.

** 2. /refactor <scope>

Run =/refactor= on the scope. Its default full scan covers complexity,
duplication, dead-code, and simplification. It presents findings and applies
only what's approved (its own gate) — structure and logic first, so the
readability pass audits the cleaned-up code.

** 3. readability-audit on <scope>

Run the readability-audit workflow on the same scope. Its cheap comment- and
name-only fixes (dimensions A/B/C) land inline and are verified by a green
suite; its structural findings (dimension D — split a module, rename a public
symbol) are *filed* as =:refactor:= tasks rather than done here.

** 4. Surface the residue

Collect and report what the sweep left behind for later work:

- The =:refactor:= tasks readability-audit filed (the structural backlog).
- Any =/refactor= findings deferred rather than applied in step 2.

That residue is the "do this next" list the sweep produces; it's not a failure
to finish, it's the structural work that needs its own design and test pass.

* The /simplify boundary

=/simplify= and this sweep don't overlap: =/simplify= cleans the *current diff*
and applies its fixes directly, so reach for it right after making a change,
before committing. This sweep works *existing committed code* and runs the
scan-and-present passes. One trigger can't sensibly do both — a diff you're
holding and a tree you're auditing are different inputs.

* Verification

Each pass owns its verification (=/refactor= runs the suite after applying;
readability-audit verifies inline fixes against a green suite). The umbrella
adds nothing beyond sequencing, so when both passes report green, the sweep is
clean — confirm that before reporting done rather than assuming it.