code-smells-and-antipatterns

name	code-smells-and-antipatterns
description	Review the current diff for new or worsened maintainability/design issues: code smells, architecture boundary leaks, weak cohesion, and risky coupling. Use for structural changes, public APIs, adapters/integrations, or design review; avoid generic full-codebase audits.
metadata	{"short-description":"Diff-focused maintainability review"}

Purpose

This is the parent skill for diff-focused maintainability review. It finds only issues introduced or worsened by the current diff: code smells, design anti-patterns, architecture boundary leaks, and modularity/coupling regressions.

Do not turn this into a full-codebase audit. Read unchanged code only as needed to understand whether the diff made the design worse.

When to use (trigger conditions)

Agents MUST use this skill when any of the following applies:

• New module/subsystem or new main class is introduced.
• A change introduces or edits public APIs or cross-module boundaries.
• A change adds or changes a DB, HTTP, framework, SDK, queue, filesystem, or service boundary.
• A change increases indirection, flags, config branching, shared state, or manager/service hubs.
• A refactor moves logic across files or layers (controller/usecase/domain/adapters/etc.).
• Review request explicitly mentions smells, anti-patterns, architecture boundaries, modularity, cohesion, coupling, god object, big ball of mud, anemic domain model, or shotgun surgery.

If none applies, do not force it.

References

Open only the reference material that matches the diff:

• references/code-smells-and-antipatterns.md for smell labels, impact, and smallest fixes.
• references/architecture-boundary-review.md for dependency direction, ports, adapters, DTOs, and boundary leaks.
• references/modularity-cohesion-coupling.md for cohesion and coupling checks.
• references/finding-template.md for the expected review shape.

How to use (procedure; must be stepwise)

1. Identify the units impacted by the diff (files + key functions/classes).
2. Identify new imports/dependencies and any boundary crossings changed by the diff.
3. Scan for new or worsened issues only:
   • smell/design anti-pattern: use the smell catalog;
   • boundary issue: check dependency direction, type leakage, DTOs, wrappers, and error translation;
   • modularity issue: describe each changed unit in one sentence, then check worst cohesion/coupling form.
4. Produce up to 3 findings, each with:
   • label (smell, anti-pattern, boundary issue, or modularity/coupling issue)
   • why this looks like it (evidence from the diff)
   • risk if left as-is
   • smallest fix (prefer minimal diff)
   • fix lens/reference or existing narrower skill to apply
5. If you choose NOT to fix now, state:
   • why it is not new/worsened, or
   • why fixing now would increase risk, and
   • what to monitor (tests/metrics/logs) until a planned follow-up.

Output expectation (strict format)

Require the output to include:

Smells & Anti-patterns Review

• Scope: (changed units)
• Findings: (0–3 items)

For each finding:

Finding N: (type: smell|design anti-pattern|architecture boundary issue|modularity/coupling issue; impact: blocker|important|nice-to-have)

• Introduced/Worsened by this diff?: yes|no
• Evidence (diff-level):
• Why it matters here:
• Smallest fix:
• Fix lens/reference:
• If not fixing now (only allowed if not introduced/worsened): justification + follow-up note

If there are 0 findings:

• State: "No new/worsened maintainability issues found" and list what you checked.