levnikolaevich/ln-624-code-maintainability-hotspot-auditor

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 and references/mcp_tool_preferences.md. Tool policy: You may run as an isolated subagent where host AGENTS.md is not in scope, so default to hex-line MCP first for file reads, search, and edits. Load references/mcp_integration_patterns.md only when 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 duplicates, import from central file
• Use enums for related constants

Effort: M (extract constants, update imports, consolidate)

8. Method Signature Quality

What: Poor method contracts reducing readability and maintainability

Detection:

| Issue | Pattern | Example | |-------|---------|---------| | Boolean flag params | >=2 boolean params in signature | def process(data, is_async: bool, skip_validation: bool) | | Too many optional params | >=3 optional params with defaults | def query(db, limit=10, offset=0, sort="id", order="asc") | | Inconsistent verb naming | Different verbs for same operation type in one module | get_user() vs fetch_account() vs load_profile() | | Unclear return type | -> dict, -> Any, -> tuple without TypedDict/NamedTuple | def get_stats() -> dict instead of -> StatsResponse |

Severity:

• MEDIUM: Boolean flag params (use enum/strategy), unclear return types
• LOW: Too many optional params, inconsistent naming

Recommendation:

• Boolean flags: replace with enum, strategy pattern, or separate methods
• Optional params: group into config/options dataclass
• Naming: standardize verb conventions per module (get_ for sync, fetch_ for async, etc.)
• Return types: use TypedDict, NamedTuple, or dataclass instead of raw dict/tuple

Effort: S-M (refactor signatures + callers)

9. Identifier Consistency Across Layers

What: Same concept uses different identifiers across API contracts, DTOs, services, repositories, DB columns, or internal modules

Detection:

| Issue | Pattern | Example | |-------|---------|---------| | External contract drift | API/OpenAPI/external-schema field name differs from DTO/service/repo/DB column | user_id in OpenAPI but uid in DTO, userId in service, user column in DB | | Synonym drift (internal) | Same entity referenced by competing names across modules | customer vs client vs account vs user for one concept | | Unmediated casing/translation | snake/camel/kebab swap without an explicit serializer alias | created_at API field assigned to creationTime with no alias declared | | Abbreviation drift | Full and abbreviated forms coexist for one concept | organization vs org vs orgId vs organizationId |

Severity:

• HIGH: External-contract field renamed inside code without an explicit serializer alias -- silent breakage risk when the upstream contract changes
• MEDIUM: Synonym drift for one entity across 3+ modules (customer / client / account)
• MEDIUM: Casing translation without an explicit alias mapping
• LOW: Two-variant drift in one bounded module; abbreviation drift in internal-only code
• Downgrade when: ORM-mediated mapping with explicit column alias, framework-required transforms (e.g. GraphQL camelCase via codegen), generated DTOs from contract, language-keyword collision forcing rename -> downgrade or skip

Layer 2 requirement: Synonym drift detection relies on a curated project glossary or on reading usage context. Grep alone is insufficient -- always confirm the two identifiers refer to the same concept before reporting.

Recommendation:

• External-contract case: carry the external API name as-is through DTO / service / repository / DB column. If casing or language conventions conflict, configure a serializer alias once at the boundary (@JsonProperty, alias_generator, @SerializedName) rather than renaming the field inside the code
• Internal-only case: pick the most semantically precise variant, apply find/replace across the modules, record the canonical term in a shared glossary or shared constants/enum module. Add a lint rule or codegen step where possible to prevent reintroduction
• For verb naming within a single module, see Rule #8 (Method Signature Quality)

Effort: S-M (rename + serializer config). L when a DB column rename plus migration is required

Scoring Algorithm

MANDATORY READ: Load references/audit_scoring.md.

Output Format

MANDATORY READ: Load references/templates/audit_worker_report_template.md.

Write JSON summary per references/audit_summary_contract.md. In managed mode the caller passes both runId and summaryArtifactPath; in standalone mode the worker generates its own run-scoped artifact path per shared contract.

Write report to {output_dir}/ln-624--{domain}.md (or 624-quality.md in global mode) with category: "Code Maintainability Hotspots" and checks: cyclomatic_complexity, deep_nesting, long_methods, god_classes, too_many_params, quadratic_algorithms, magic_numbers, method_signatures, identifier_consistency.

When summaryArtifactPath is absent, write the standalone runtime summary under .hex-skills/runtime-artifacts/runs/{run_id}/evaluation-worker/{worker}--{identifier}.json and optionally echo the same summary in structured output.

Report written: .hex-skills/runtime-artifacts/runs/{run_id}/audit-report/ln-624--orders.md
Score: X.X/10 | Issues: N (C:N H:N M:N L:N)

Critical Rules

Apply the already-loaded references/audit_worker_core_contract.md.

• Do not auto-fix: Report only
• Domain-aware scanning: If domain_mode="domain-aware", scan ONLY scan_path (not entire codebase)
• Tag findings: Include domain field in each finding when domain-aware
• Metrics tools: Use existing tools when available (ESLint complexity plugin, radon, gocyclo)
• Unique angle: Audit local maintainability hotspots only. Do not audit duplication, package health, architecture boundaries, N+1 persistence behavior, or orchestration ownership. Identifier-consistency findings cover naming continuity of one concept across layers; this is distinct from ln-623 (code duplication) and ln-643 (DTO presence / layer leakage in signatures).
• Action required: Every finding uses REFACTOR_HOTSPOT, SIMPLIFY_SIGNATURE, EXTRACT_CONSTANT, or UNIFY_IDENTIFIER.

Definition of Done

Apply the already-loaded references/audit_worker_core_contract.md.

• [ ] contextStore parsed (including domain_mode, current_domain, output_dir)
• [ ] scan_path determined (domain path or codebase root)
• [ ] All 9 checks completed (scoped to scan_path):
  • complexity, nesting, length, god classes, parameters, O(n^2), constants, method signatures, identifier consistency
• [ ] Findings collected with severity, location, effort, recommendation, domain
• [ ] Score calculated
• [ ] Report written to {output_dir}/ln-624--{domain}.md (atomic single Write call)
• [ ] Summary written per contract

Reference Files

• Audit output schema: references/audit_output_schema.md

---

Version: 3.0.0 Last Updated: 2025-12-23