ln-624-code-maintainability-hotspot-auditor

What this skill does

> **Paths:** File paths (`references/`, `../ln-*`) are relative to this skill directory.

# Code Maintainability Hotspot Auditor (L3 Worker)

**Type:** L3 Worker

Specialized worker auditing local code hotspots that are hard to read, change, or reason about.

## Purpose & Scope

- Audit **code maintainability hotspots** (priority: medium)
- Check complexity metrics, method signature quality, local algorithmic efficiency, constants management, identifier consistency across layers
- Emit `REFACTOR_HOTSPOT`, `SIMPLIFY_SIGNATURE`, `EXTRACT_CONSTANT`, or `UNIFY_IDENTIFIER`
- Return structured findings with severity, location, effort, recommendations
- Calculate compliance score (X/10) for Code Quality category

## Inputs

**MANDATORY READ:** Load `references/audit_worker_core_contract.md`.
Tool policy: follow host AGENTS.md MCP preferences; load `references/mcp_tool_preferences.md` and `references/mcp_integration_patterns.md` only when host policy is absent or MCP behavior is unclear.

Receives `contextStore` with: `tech_stack`, `best_practices`, `principles`, `codebase_root`, `output_dir`.

**Domain-aware:** Supports `domain_mode` + `current_domain` (see `audit_output_schema.md#domain-aware-worker-output`).

## Workflow

Detection policy: use two-layer detection (candidate scan, then context verification); load `references/two_layer_detection.md` only when the verification method is ambiguous.

1) **Parse context** -- extract fields, determine `scan_path` (domain-aware if specified), extract `output_dir`
2) **Scan codebase for violations (Layer 1)**
   - All Grep/Glob patterns use `scan_path` (not codebase_root)
   - **Graph acceleration (if available):** IF `contextStore.graph_indexed` OR `.hex-skills/codegraph/index.db` exists:
     - **Complexity + God classes:** `audit_workspace(path=scan_path, verbosity="minimal", limit=5)` -- use returned hotspots to pre-identify complex functions and god classes. Raise `limit` only for deliberate drill-down.
     - **Module metrics:** `analyze_architecture(path=scan_path, verbosity="full")` -- use returned coupling metrics for cascade depth and coupling analysis.
     - Fall back to grep patterns below if graph unavailable.
     - **Outline-first read:** `outline(file_path)` before reading large source files -- understand function/class structure for complexity analysis.
   - Example: `Grep(pattern="if.*if.*if", path=scan_path)` for nesting detection
3) **Analyze context per candidate (Layer 2 -- MANDATORY)**
   Layer 1 finding without Layer 2 = NOT a valid finding. Before reporting, ask: "Is this violation intentional or justified by design?"
   - Cyclomatic complexity: is complexity from switch/case on enum (valid) or deeply nested conditions (bad)? Enum dispatch -> downgrade to LOW or skip
   - O(n^2): read context -- what's n? If bounded (n < 100), downgrade severity
   - God class: is it a config/schema/builder class? -> downgrade
   - Identifier drift: is the rename mediated by an explicit serializer alias (`@JsonProperty`, `alias_generator`, `@SerializedName`) or an ORM column mapping (`@Column(name=...)`)? If yes -> downgrade or skip
4) **Collect findings with severity, location, effort, recommendation**
   - Tag each finding with `domain: domain_name` (if domain-aware)
5) **Calculate score using penalty algorithm**
6) **Write Report:** Build full markdown report in memory per `references/templates/audit_worker_report_template.md`, write to `{output_dir}/ln-624--{domain}.md` (or `624-quality.md` in global mode) in single Write call
7) **Return Summary:** Return minimal summary (see Output Format)

## Audit Rules (Priority: MEDIUM)

### 1. Cyclomatic Complexity
**What:** Too many decision points in single function (> 10)

**Detection:**
- Count if/else, switch/case, ternary, &&, ||, for, while
- Use tools: `eslint-plugin-complexity`, `radon` (Python), `gocyclo` (Go)

**Severity:**
- **HIGH:** Complexity > 20 (extremely hard to test)
- **MEDIUM:** Complexity 11-20 (refactor recommended)
- **LOW:** Complexity 8-10 (acceptable but monitor)
- **Downgrade when:** Enum/switch dispatch, state machines, parser grammars -> downgrade to LOW or skip

**Recommendation:** Split function, extract helper methods, use early returns

**Effort:** M-L (depends on complexity)

### 2. Deep Nesting (> 4 levels)
**What:** Nested if/for/while blocks too deep

**Detection:**
- Count indentation levels
- Pattern: if { if { if { if { if { ... } } } } }

**Severity:**
- **HIGH:** > 6 levels (unreadable)
- **MEDIUM:** 5-6 levels
- **LOW:** 4 levels
- **Downgrade when:** Nesting from early-return guard clauses (structurally deep but linear logic) -> downgrade

**Recommendation:** Extract functions, use guard clauses, invert conditions

**Effort:** M (refactor structure)

### 3. Long Methods (> 50 lines)
**What:** Functions too long, doing too much

**Detection:**
- Count lines between function start and end
- Exclude comments, blank lines

**Severity:**
- **HIGH:** > 100 lines
- **MEDIUM:** 51-100 lines
- **LOW:** 40-50 lines (borderline)
- **Downgrade when:** Orchestrator functions with sequential delegation; data transformation pipelines -> downgrade

**Recommendation:** Split into smaller functions, apply Single Responsibility

**Effort:** M (extract logic)

### 4. God Classes/Modules (> 500 lines)
**What:** Files with too many responsibilities

**Detection:**
- Count lines in file (exclude comments)
- Check number of public methods/functions

**Severity:**
- **HIGH:** > 1000 lines
- **MEDIUM:** 501-1000 lines
- **LOW:** 400-500 lines
- **Downgrade when:** Config/schema/migration files, generated code, barrel/index files -> skip

**Recommendation:** Split into multiple files, apply separation of concerns

**Effort:** L (major refactor)

### 5. Too Many Parameters (> 5)
**What:** Functions with excessive parameters

**Detection:**
- Count function parameters
- Check constructors, methods

**Severity:**
- **MEDIUM:** 6-8 parameters
- **LOW:** 5 parameters (borderline)
- **Downgrade when:** Builder/options pattern constructor; framework-required signatures (middleware, hooks) -> skip

**Recommendation:** Use parameter object, builder pattern, default parameters

**Effort:** S-M (refactor signature + calls)

### 6. O(n^2) or Worse Algorithms
**What:** Inefficient nested loops over collections

**Detection:**
- Nested for loops: `for (i) { for (j) { ... } }`
- Nested array methods: `arr.map(x => arr.filter(...))`

**Severity:**
- **HIGH:** O(n^2) in hot path (API request handler)
- **MEDIUM:** O(n^2) in occasional operations
- **LOW:** O(n^2) on small datasets (n < 100)
- **Downgrade when:** Bounded n (n < 100 guaranteed by domain); one-time init/migration code -> downgrade to LOW or skip

**Recommendation:** Use hash maps, optimize with single pass, use better data structures

**Effort:** M (algorithm redesign)

### 7. Constants Management
**What:** Magic numbers/strings, decentralized constants, duplicates

**Detection:**

| Issue | Pattern | Example |
|-------|---------|---------|
| Magic numbers | Hardcoded numbers in conditions/calculations | `if (status === 2)` |
| Magic strings | Hardcoded strings in comparisons | `if (role === 'admin')` |
| Decentralized | Constants scattered across files | `MAX_SIZE = 100` in 5 files |
| Duplicates | Same value multiple times | `STATUS_ACTIVE = 1` in 3 places |
| No central file | Missing `constants.ts` or `config.py` | No single source of truth |

**Severity:**
- **HIGH:** Magic numbers in business logic (payment amounts, statuses)
- **MEDIUM:** Duplicate constants (same value defined 3+ times)
- **MEDIUM:** No central constants file
- **LOW:** Magic strings in logging/debugging
- **Downgrade when:** HTTP status codes (200, 404, 500) -> skip. Math constants (0, 1, -1) in algorithms -> skip. Test data -> skip

**Recommendation:**
- Create central constants file (`constants.ts`, `config.py`, `constants.go`)
- Extract magic numbers to named constants: `const STATUS_ACTIVE = 1`
- Consolidate dupl