Paths: File paths (
references/,../ln-*) are relative to this skill directory.
Code Quality Checker
Type: L3 Worker Category: 5XX Quality
Analyzes Done implementation tasks with quantitative Code Quality Score based on metrics, MCP Ref validation, and issue penalties.
Inputs
| Input | Required | Source | Description |
|---|---|---|---|
storyId | Yes | args, git branch, kanban, user | Story to process |
Resolution: Story Resolution Chain. Status filter: In Progress, To Review
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. - use hex-graph as the primary path for clone, architecture, and semantic quality evidence when the project is indexed. Fall back to Grep/Read only when graph is unavailable or unsupported.
Purpose & Scope
- Load Story and Done implementation tasks (exclude test tasks)
- Calculate Code Quality Score using metrics and issue penalties
- MCP Ref validation: Verify optimality, best practices, and performance via external sources
- Check for DRY/KISS/YAGNI violations, architecture boundary breaks, security issues
- Produce quantitative verdict with structured issue list; never edits Linear or kanban
Code Metrics
| Metric | Threshold | Penalty |
|---|---|---|
| Cyclomatic Complexity | ≤10 OK, 11-20 warning, >20 fail | -5 (warning), -10 (fail) per function |
| Function size | ≤50 lines OK, >50 warning | -3 per function |
| File size | ≤500 lines OK, >500 warning | -5 per file |
| Nesting depth | ≤3 OK, >3 warning | -3 per instance |
| Parameter count | ≤4 OK, >4 warning | -2 per function |
Code Quality Score
Formula: Code Quality Score = 100 - metric_penalties - issue_penalties
Issue penalties by severity:
| Severity | Penalty | Examples |
|---|---|---|
| high | -20 | Security vulnerability, O(n²)+ algorithm, N+1 query |
| medium | -10 | DRY violation, suboptimal approach, missing config |
| low | -3 | Naming convention, minor code smell |
Score interpretation:
| Score | Status | Verdict |
|---|---|---|
| 90-100 | Excellent | PASS |
| 70-89 | Acceptable | CONCERNS |
| <70 | Below threshold | ISSUES_FOUND |
Issue Prefixes
| Prefix | Category | Default Severity | MCP Ref |
|---|---|---|---|
| SEC- | Security (auth, validation, secrets) | high | — |
| SEC-DESTR- | Destructive ops (guards: DB, FS, MIG, ENV, FORCE) | high/medium | — |
| PERF- | Performance (algorithms, configs, bottlenecks) | medium/high | ✓ Required |
| MNT- | Maintainability (DRY, SOLID, complexity, dead code) | medium | — |
| ARCH- | Architecture (layers, boundaries, patterns, contracts) | medium | — |
| BP- | Best Practices (implementation differs from recommended) | medium | ✓ Required |
| OPT- | Optimality (better approach exists for this goal) | medium | ✓ Required |
OPT- subcategories:
| Prefix | Category | Severity |
|---|---|---|
| OPT-OSS- | Open-source replacement available | medium (high if >200 LOC) |
ARCH- subcategories:
| Prefix | Category | Severity |
|---|---|---|
| ARCH-LB- | Layer Boundary: I/O outside infra, HTTP in domain | high |
| ARCH-TX- | Transaction Boundaries: commit() in 3+ layers, mixed UoW ownership | high (CRITICAL if auth/payment) |
| ARCH-DTO- | Missing DTO (4+ params without DTO), Entity Leakage (ORM entity in API response) | medium (high if auth/payment) |
| ARCH-DI- | Dependency Injection: dependencies not replaceable for testing (direct instantiation, no injection mechanism). Exception: small scripts/CLIs where params/closures suffice → skip | medium |
| ARCH-CEH- | Centralized Error Handling: errors silently swallowed, stack traces leak to prod, no consistent error logging. Exception: 50-line scripts → downgrade to LOW | medium (high if no handler at all) |
| ARCH-SES- | Session Ownership: DI session + local session in same module | medium |
| ARCH-AI-SEB | Side-Effect Breadth: 3+ side-effect categories in one leaf function. Conflict Resolution: orchestrator/coordinator functions (imports 3+ services AND delegates sequentially) are EXPECTED to have multiple categories — do NOT flag SEB | medium |
| ARCH-AI-AH | Architectural Honesty: read-named function with write side-effects | medium |
| ARCH-AI-FO | Flat Orchestration: leaf service imports 3+ other services. Orchestrator imports are expected — do NOT flag | medium |
| ARCH-EVENT- | Event Channel Consistency: publisher/subscriber name mismatch (MISMATCH), orphaned channel with no counterpart (ORPHAN) | high (mismatch), medium (orphan) |
PERF- subcategories:
| Prefix | Category | Severity |
|---|---|---|
| PERF-ALG- | Algorithm complexity (Big O) | high if O(n²)+ |
| PERF-CFG- | Package/library configuration | medium |
| PERF-PTN- | Architectural pattern performance | high |
| PERF-DB- | Database queries, indexes | high |
MNT- subcategories:
| Prefix | Category | Severity |
|---|---|---|
| MNT-DC- | Dead code: replaced implementations, unused exports/re-exports, backward-compat wrappers, unsupported aliases | medium (high if public API) |
| MNT-DRY- | DRY violations: duplicate logic across files | medium |
| MNT-GOD- | God Classes: class with >15 methods or >500 lines (not just file size) | medium (high if >1000 lines) |
| MNT-SIG- | Method Signature Quality: boolean flag params, unclear return types, inconsistent naming, >5 optional params | low |
| MNT-ERR- | Error Contract inconsistency: mixed raise + return None in same service | medium |
When to Use
- All implementation tasks in Story status = Done
- Before tech debt cleanup and inline agent review
Workflow (concise)
MANDATORY READ: Load references/input_resolution_pattern.md
-
Resolve storyId: Run Story Resolution Chain per guide (status filter: [In Progress, To Review]).
-
Load Story (full) and Done implementation tasks (full descriptions) via Linear; skip tasks with label "tests".
-
Collect changed files (
changed_files[]): MANDATORY READ: Loadreferences/git_scope_detection.md- IF invoked by ln-510: use
changed_files[]from coordinator context → proceed to Enrich step in guide - IF invoked standalone: run full algorithm from guide
- IF invoked by ln-510: use
-
Two-Layer Detection (MANDATORY): MANDATORY READ: Load
references/two_layer_detection.mdAll threshold-based findings require Layer 2 context analysis. Layer 1 finding without Layer 2 = NOT a valid finding. Before reporting any metric violation, ask: "Is this violation intentional or justified by design?" See Exception column in metrics below. -
Calculate code metrics:
- Cyclomatic Complexity per function (target ≤10; Exception: enum/switch dispatch, state machines, parser grammars → downgrade to LOW)
- Function size (target ≤50 lines; Exception: orchestrator functions with sequential delegation)
- File size (target ≤500 lines; Exception: config/schema/migration files, generated code)
- Nesting depth (target ≤3)
- Parameter count (target ≤4; Exception: builder/options patterns)
-
MCP Ref Validation (MANDATORY for code changes — SKIP if
--skip-mcp-refflag passed): MANDATORY READ: Loadreferences/research_tool_fallback.mdFast-track mode: When invoked with
--skip-mcp-ref, skip this entire step (no OPT-, BP-, PERF- checks). Proceed directly to step 6 (static analysis). This reduces cost from ~5000 to ~800 tokens while preserving metrics + static analysis coverage.Level 1 — OPTIMALITY (OPT-):
- Extract goal from task (e.g., "user authentication", "caching", "API rate limiting")
- Research alternatives:
ref_search_documentation("{goal} approaches comparison {tech_stack} 2026") - Compare chosen