Audit — Refactoring Smells

When to use

• Пользователь просит провести аудит рефакторинга проекта на PHP — найти god-классы, мёртвый код, циклические зависимости, дублирование и непокрытые тестами горячие пути, и оценить находки. Аудит рефакторинга, а не Laravel или Битрикс.
• The user wants a refactoring audit of an existing PHP codebase — find god classes, circular dependencies, dead code, copy-paste duplication, or untested hot paths.
• The user wants to locate copy-paste duplication, dead or unreachable code, or oversized classes and methods across a PHP project.
• The user asks which refactors matter most, wants technical debt quantified, or needs a prioritised backlog of structural cleanups for a legacy PHP project.

When NOT to use

• Do not use this skill to design a new feature or a greenfield module; it audits existing code for smells and has nothing to scan on a blank slate.
• Do not run a refactoring audit when the user asks to fix one specific bug or implement one change; make the minimal targeted edit instead of scanning for smells.

Core guidance

• Emit structured FINDINGS, not prose — Report each smell as a FINDING with id (AUD-REFACTOR-{nnn}), title, evidence (path:line), domain, severity, impact, effort (1-5), confidence (0.5-1.0), roi_score, remediation, and tags — never a free-form paragraph.
• Never emit a finding without evidence — Every finding MUST carry concrete evidence as path:line pointing at real code you sampled; if you cannot cite a file and line, do not emit the finding.
• Rank findings by ROI score — Compute roi_score = (impact * severity * confidence) / effort for every finding and sort the report descending, so the highest-leverage, lowest-cost refactors surface first.

Decision Engine

Walk this section before choosing an implementation path.

For the smell you found, is the affected code on a hot path (frequently executed or
business-critical) and is it currently covered by tests?

├── Cold or rarely executed path: → Lower ROI — record the finding with reduced impact so it does not crowd out hot-path work;
if the code is also unreachable, reclassify it as dead code and propose deletion.

├── Hot path but already tested: → High ROI, lower risk — the tests are a safety net. Emit a finding whose remediation is
the concrete refactor (extract class, break cycle, dedupe) with the existing suite as the guard.

└── Hot path and untested: → Highest ROI — this is the danger zone. Emit a high-severity finding whose remediation
is add characterization tests first, then refactor; never refactor untested hot code blind.

Full engine: references/decision-engine.md — Decision Tree, Priority Matrix, Decision Table.

Workflows

Workflow: Emit Report

Progress:
- [ ] Build one finding per confirmed smell with `id` (`AUD-REFACTOR-{nnn}`), `title`,
`evidence`, `domain`, `severity`, `impact`, `effort`, `confidence`, `remediation`, and `tags`
- [ ] Compute `roi_score = (impact * severity * confidence) / effort` for each finding and sort
the report descending so the highest-leverage refactors appear first
- [ ] For each finding, write remediation that names the concrete fix and links to the
implementation or strategy skill that performs it, then hand the ranked report off as
the input to scoped fix tasks

1. Build one finding per confirmed smell with id (AUD-REFACTOR-{nnn}), title, evidence, domain, severity, impact, effort, confidence, remediation, and tags.
   • Verify: Every finding has all required fields populated and a path:line in evidence.
2. Compute roi_score = (impact * severity * confidence) / effort for each finding and sort the report descending so the highest-leverage refactors appear first.
   • Verify: The report is ordered by roi_score descending with the score shown on each finding.
3. For each finding, write remediation that names the concrete fix and links to the implementation or strategy skill that performs it, then hand the ranked report off as the input to scoped fix tasks.
   • Verify: Each remediation names a next step; hot-path items reference test-first strategy skills.

Workflow: Scan Codebase

Progress:
- [ ] Run structural tooling — a copy-paste detector (phpcpd), PHPStan or Psalm for dead code
and complexity, and a class-size or churn report — to enumerate candidate smells
- [ ] Open each candidate file, read the code, and confirm the smell is real — count
responsibilities, trace the dependency cycle, or check callers — recording the exact
path:line for evidence
- [ ] For each confirmed smell, walk the Decision Engine to set severity and impact by hot-path
and test-coverage status, estimate effort, and assign confidence

1. Run structural tooling — a copy-paste detector (phpcpd), PHPStan or Psalm for dead code and complexity, and a class-size or churn report — to enumerate candidate smells.
   • Verify: You have a raw list of candidate locations for duplication, dead code, and oversized classes.
2. Open each candidate file, read the code, and confirm the smell is real — count responsibilities, trace the dependency cycle, or check callers — recording the exact path:line for evidence.
   • Verify: Every retained candidate has a confirmed path:line and a one-line description of the smell.
3. For each confirmed smell, walk the Decision Engine to set severity and impact by hot-path and test-coverage status, estimate effort, and assign confidence.
   • Verify: Each candidate has severity, impact, effort (1-5) and confidence (0.5-1.0) grounded in its evidence.

Best practices

• In each finding's remediation, point to the implementation skill that performs the fix — e.g
• Open and read the actual files — do not infer smells from names or directory structure
• When a finding sits on an untested hot path, the remediation must sequence characterization tests first and the structural change second — never propose refactoring critical untested code without a safety net

Anti-patterns

See references/anti-patterns.md.

Debugging

1. Dynamic calls flagged as dead code — PHP resolves many calls at runtime, so static reachability under-reports what is actually used. Fix: Before deleting, grep for the symbol as a string, check DI config, routes, event maps, and Bitrix agents/handlers; lower confidence on the finding when dynamic use is plausible.
2. Every finding rated the same severity — When all scores are equal, roi_score no longer discriminates and the backlog is effectively unordered. Fix: Calibrate each axis independently against the evidence — blast radius for impact, defect likelihood for severity, realistic hours for effort — so scores spread and the ranking sorts.
3. Judging god classes by line count alone — Size is a weak proxy; responsibility count and change frequency are what make a class dangerous. Fix: Score god-class findings on responsibilities, fan-in/fan-out, and churn, not raw lines, and set effort/impact accordingly so stable large classes rank low.

Production checklist

• Every finding in the report carries concrete path:line evidence pointing at code that was actually read.
• Findings on untested hot paths remediate with characterization tests before any structural change is proposed.
• The pass produces findings and remediation guidance only; it does not apply large refactors or edit code as a side effect.
• Dead-code findings confirm the code is unreachable statically and dynamically before recommending deletion.
• Each finding's remediation names a concrete next step and, where one exists, the implementation skill that performs it.
• The report lists findings sorted descending by roi_score with impact, severity, effort, and confidence shown.

Version notes

• Analyzer capabilities scale with PHP version (PHP >=7.4) — The audit applies to PHP >=7.4 through 8.4, but static-analysis fidelity grows with the version: typed properties, enums, and readonly on 8.x let PHPStan and Psalm resolve dead code and unused symbols far more precisely than on 7.4's looser types.

Security

• Treat unreferenced code as a possible live risk — When auditing dead code, watch for unreferenced-but-reachable endpoints, admin scripts, or debug routes: seemingly dead files can still be served over HTTP and expose input sinks. Flag such code as a security finding, not just a cleanup, and validate reachability before assuming it is inert.

Testing

• Activation and decision behavior are verified in eval/scenarios/audit/refactoring.yaml.
• When a finding sits on an untested hot path, the remediation must sequence characterization tests first and the structural change second — never propose refactoring critical untested code without a safety net.

Additional resources

• references/anti-patterns.md
• references/core.md
• references/decision-engine.md
• references/examples.md
• references/pitfalls.md
• references/recipes.md
• references/version-differences.md

Knowledge graph

Related: audit/project-analysis
Behavior constraints: ai-rules/strategy-no-untested-refactor

Skill contract

Produces: audit.refactor-findings
Requires: repo.php-source
Risk: medium · Confidence: 0.9