refactor-audit

Files (1)

• SKILL.md

SKILL.md (first lines)

# Refactor Audit

Decide whether structural refactoring is warranted, with evidence. The skill answers *"is there enough architecture drift to justify a separate refactor right now?"* and routes to the right next workflow. It does not perform the refactor.

## When to invoke

Any of:

- Explicit user request — *"audit this codebase"*, *"are we drifting?"*, *"run a refactor audit"*
- After completing a cluster of related feature slices (post-feature-cluster review)
- Before a tagged release (release-hardening pass)
- When `zoom-out` skill flags drift during long-running work
- When the same agent mistake recurs across sessions (Hashimoto's harness rule)
- When review bandwidth feels disproportionate to PR size

**No calendar cadence default.** Calendar sweeps are busywork unless the team already runs scheduled maintenance windows. Trigger-based is the default.

## Output artifact

Produces `.local/refactor-audit-YYYY-MM-DD.md` with the structure below. The artifact is the deliverable — never just inline a verbal answer.

```
# Refactor Audit — <repo> — <date>

## Previous audit reviewed
<path to latest prior .local/refactor-audit-*.md, or "none">

## Tooling discovered
<commands found in justfile / Makefile / pyproject.toml / package.json /
.github/workflows / sonar-project.properties — what CAN be measured here>

## Signals

### Hard signals (CI/baseline-backed metrics)
| Signal | Fired? | Evidence | Baseline |

### Soft signals (judgment / agent observations)
| Signal | Fired? | Evidence (commit refs, session notes) |

### Tooling-gap signals (plausible but no tool/baseline exists)
| Signal | Why we can't measure | Candidate tool to add |

## Repeated soft signals
<soft signals that ALSO fired in the previous audit — names + brief
diff vs prior evidence; empty list if no prior audit or no repeats>

## Decision

### Stage 1 — Separate refactor work warranted?
<yes / no, with the trigger row that fired from the Stage 1 table>

### Stage 2 — Workflow routing (only if Stage 1 = yes)
<one of:
  improve-codebase-architecture (requires-plan: no) /
  improve-codebase-architecture (requires-plan: yes — scope first) /
  large-feature playbook>

## Rationale
<2-4 sentences citing which signals support the decision, and how the
Repeated soft signals list (if any) influenced Stage 1>

## Guardrail candidates
<repeated soft signals → CI checks/lints/import-linter contracts/coverage
thresholds that would convert these into hard signals next time>

## Validation gaps
<things we couldn't check because tooling is missing; record explicitly,
do not silently skip>
```

## Discover tooling first

Read these files to discover what's actually measurable in *this* repo before claiming any signal:

- `justfile`, `Makefile`, `package.json`, `pyproject.toml`
- `.github/workflows/*`, `.gitlab-ci.yml`
- `sonar-project.properties`, `.semgrep.yml`, `import-linter.cfg`
- Repo `AGENTS.md` / `CLAUDE.md` for declared conventions
- `docs/adr/` for prior architectural decisions

If a signal's tool isn't present in the repo, record it under **tooling-gap**, not under hard signals.

## Signals — three tiers

### Hard signals (CI/baseline-backed)

These have evidence the agent can produce; they require the repo to have the tool configured.

- **Test walltime regression** vs. the repo's own baseline. Python: `pytest --durations=10`. JS/TS: jest/vitest reporters.
- **Coverage regression** vs. baseline. Python: `pytest-cov`. JS/TS: `c8`/`nyc`/jest coverage.
- **Repeated CI failures in the same area** — git log + CI history; same module failing on unrelated PRs is a structural smell.
- **Lint/type complexity threshold crossed** — Python: `ruff` complexity rules (`C90`, `PLR`), `mypy --strict` regressions. JS/TS: eslint complexity rules.
- **Import cycle detected** — Python: `import-linter`, `grimp`, `pydeps --max-bacon`. JS/TS: `madge --circular`.
- **Duplication threshold breach** — Python: `pylint duplicate-code`, `radon`. JS/TS: `jscpd`.
- **Sonar / Trail-of-Bits / fp-check findings cluster** in one module.

Always compare against the **repo's own baseline**. There is no universal "20% slower" threshold; if no baseline exists, record under tooling-gap and propose recording one.

### Soft signals (judgment / observation)

These rely on session notes, commit history, or agent recall.

- Same agent mistake recurring across two or more sessions (Hashimoto's harness trigger)
- "Just one more thing" responsibility creep — one module growing across unrelated features
- Repeated cross-file edits to express one concept — coupling smell
- Review burden disproportionate to PR size — review requires repeated clarification rounds, multiple missed-caller findings, or reviewer cannot validate a small PR without reconstructing several modules
- `zoom-out` skill flagged drift during long-running work
- Multiple recent slices needed an unplanned "fix this adjacent thing" detour
- Missed-caller surprises during reviews (Sourcegraph/Amp lens — completeness gaps)

### Tooling-gap signals

Plausible signals we cannot currently observe because the tool isn't configured. Examples:
- "Import cycles" in a Python repo that has no `import-linter` or `grimp` — log as tooling-gap, propose adding the tool.
- "Duplication" in a JS/TS repo with no `jscpd` configured — same.

Tooling-gap signals do NOT count toward the decision rule. They DO appear in the guardrail-candidates section.

## Prior-audit comparison

From clemens33/dotfiles, MIT.

More from clemens33/dotfiles