/smell

name: smell
description: "Detect software architecture bad smells, algorithmic complexity hotspots, and anti-patterns in a codebase. Produces a detailed markdown report identifying violations of architectural principles, design patterns, code quality, and performance complexity. Triggers on: smell, code smell, architecture smell, find anti-patterns, detect bad smells, complexity analysis, 代码坏味道, 架构坏味道, 反模式, 找出坏味道, 复杂度分析."
user-invocable: true

Smell — Architecture Bad Smell Detector

Analyze a codebase to find violations of software architecture principles, anti-patterns, code "bad smells," and algorithmic complexity hotspots. Produce a comprehensive, actionable markdown report.

**Knowledge base:** This skill encodes architectural patterns, anti-patterns, code smells, and algorithmic complexity heuristics drawn from industry research and practice, including the classic code smells catalog by Martin Fowler / Kent Beck (as organized on refactoring.guru: Bloaters, Object-Orientation Abusers, Change Preventers, Dispensables, Couplers).

---

The Job

1. Understand the scope — ask what part of the project to analyze (full project, specific module, or recent changes) 2. Scan the codebase using `find`, `grep`, and `Agent` (Explore subagent) to gather candidate signals and evidence 3. Validate candidates against context, callers, history, workload, and measurements before confirming findings 4. Generate a detailed markdown report saved to `tasks/smell-report-[timestamp].md` 5. Present a summary of confirmed findings and separate candidates to the user

---

Step 1: Scope Clarification

Ask the user:

What scope should I analyze?
  A. Entire project (thorough, may take time)
  B. Specific module/directory: [please specify]
  C. Only recently changed files (git diff)
  D. Only architectural-level issues (skip low-level code smells)

If the user doesn't specify, default to option A for small projects (< 100 files) or C for large projects.

---

Step 2: Evidence Gathering

**Use the Explore subagent** (`Agent` with `subagent_type: "Explore"`) to scan the codebase for architectural patterns and anti-patterns. Run multiple parallel explorations:

Exploration Commands

Run these in parallel to gather evidence efficiently:

1. **Project Structure Scan:** Map the directory tree, identify the architectural style (layered, modular monolith, microservices, etc.) 2. **Dependency Analysis:** Find import/include patterns, check for circular dependencies, identify coupling hotspots 3. **Module/Component Scan:** Identify God Objects (files > 500 lines), check cohesion, check single responsibility violations 4. **Pattern Detection:** Look for known anti-pattern signatures (static cling, service locator abuse, leaky abstractions) 5. **Testing Scan:** Check test coverage patterns, test file locations, test-to-code ratios 6. **Naming & Clarity Scan:** Flag misleading names, overly generic names (Manager, Helper, Util), inconsistent naming conventions 7. **Complexity Scan:** Detect algorithmic complexity hotspots — nested loops, N+1 queries, repeated scans, sort-in-loop, expensive recomputation in render paths

Key Heuristics

Heuristics are **candidate signals, not findings**. A line-count, nesting, naming, or Big-O match must be validated against the code's responsibility, callers, change history, workload, and intentional constraints. Do not assign severity from a threshold alone.

| Category | Smell | Detection Heuristic | |----------|-------|-------------------| | **Architecture** | Big Ball of Mud | No clear directory structure; everything in root or one flat folder; no separation of concerns | | **Architecture** | Violated Layer Boundaries | Inner layers importing outer layers; infrastructure code in domain/core layer | | **Architecture** | Missing Architecture | No `src/`, `lib/`, `core/` separation; SQL inline with UI code; HTTP handlers mixed with business logic | | **Architecture** | Distributed Monolith | Microservices sharing a database; services that can't deploy independently | | **Architecture** | Anemic Domain Model | Model/entity classes with only getters/setters and no behavior; all logic in services | | **Architecture** | CQRS Without Need | Separate read/write models for simple CRUD; unnecessary complexity | | **Architecture** | Over-Layered Architecture | Excessive layers/tiers that add pass-through code with no real value | | **Architecture** | Over-Abstraction | So many indirections/interfaces/generics that you get lost following the code | | **Architecture** | Futuristic Architecture | Speculative flexibility for requirements that may never come (predicting the future) | | **Architecture** | Technology-Enthusiast Architecture | Shiny/unproven tech adopted in production because it's new, not because it fits | | **Architecture** | Overkill Architecture | Heavyweight architecture/tech thrown at a simple problem | | **Architecture** | Cloud/Visio Architecture | Diagrams disconnected from the actual code and runtime reality | | **Coupling** | Circular Dependencies | Module A imports B, B imports A; detected via import graph analysis | | **Coupling** | Content Coupling | One module directly accesses another's internal/private members | | **Coupling** | Common Coupling | Excessive global variables/shared mutable state; singleton abuse | | **Coupling** | Stamp Coupling | Passing large data structures when only a few fields are needed | | **Cohesion** | God Object | Single class/module > 500 lines; > 20 public methods; handles unrelated concerns | | **Cohesion** | Shotgun Surgery | A single change requires touching 5+ files across unrelated modules | | **Cohesion** | Feature Envy | Method calls foreign class methods more than its own class methods | | **Cohesion** | Data Clumps | Same group of 3+ parameters appearing together in multiple method signatures | | **Design** | Leaky Abstractions | Implementation details (DB queries, HTTP calls) exposed through interfaces