1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
|
#+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.
|
