Complexity Audit
Find accidental complexity without calling essential guarantees bloat. This is diagnosis, not permission to change code.
When to use
- Audit an existing module or repository independently of any state currently under check (the exact state being judged right now).
- Skip choosing an implementation (
yagni), reviewing a frozen change (requesting-code-review), or applying known structural work (refactor-architecture). - A whole-repository claim requires explicit whole-repository scope; otherwise name the bounded surface and make no wider claim.
Step 1: Freeze
- Open
assets/audit-report.mdbefore the inventory. Fill What was frozen first. - Declare the report path up front:
.sdlc-skills/audits/{{YYYY-MM-DD}}-{{topic}}.md. The coordinator owns it, and it sits outside the audited target's identity. Identify the target by revision. Use a working-tree hash (the template calls it the working-tree digest) only when the report path is outside the repository orgit check-ignore -qpasses for it. If the target is uncommitted and the report path is in-tree and unignored, stop; ask for a checkpoint or an ignored or out-of-repository report path. If the target drifts, stop or restart. - Fill every row of the template's inventory table.
- Prefer one bounded audit: one partition, dispatched as Step 2 says. If
the surface is large, split it into partitions with stable IDs, exclusive
inventories, and cross-boundary edges. Invoke
dispatching-parallel-agentsonly when read sets, resources, data boundaries, and outputs reconcile independently.
Step 2: Challenge read-only
- Fill the template's
Audit-input identityonce the partitions are written. Fillassets/yagni-auditor.mdwithassets/partition-report.mdbefore dispatching each exact partition, then dispatch asdispatching-parallel-agentsStep 2 says. - If the dispatch is empty, refused, or unavailable, follow the no-dispatch
rule in
dispatching-parallel-agentsStep 2. - Read each returned partition report; open its file if only a location was returned. Match Target, Audit inputs, Partition, and Verdict to the frozen request and to the auditor's allowed verdicts. If a field is missing, unreadable, conflicting, or mismatched, that partition is inconclusive. Keep the report unchanged; never infer a repository-wide conclusion from partial coverage.
- Fill every line of the template's coverage-reconciliation block from those reports before any finding.
Step 3: Publish decisions
- Fill every column of the template's findings table, one row per finding.
- Apply or approve nothing. If a structural change is accepted, invoke
refactor-architecturefor it. Behavior work goes to its feature or bug route. - Check that Step 2.4's block accounts for every partition, then stop. Review or branch finishing runs only if the user separately asks to ship the report.
Gotchas
- A caller search that returns only the candidate's own tests reads as
"used", and the row becomes
keep. Tests are not use: treat it as having no caller. - A working-tree hash captured before the audit reports DRIFT once the report lands at an unignored path under the audited tree, though no audited code changed.
Common mistakes
- “No direct caller”: dynamic, configured, generated, or external use remains
investigateuntil disproved or deprecated. - “One implementation”: a seam containing real impedance, policy, or test isolation may be justified; apply the deletion test (inline it into every caller: it stays only if that spreads complexity), not a slogan.
- “Tests and rollback are overhead”: a current assurance or recovery guarantee owns them; duplicate machinery with no distinct guarantee is the candidate.