Paths: File paths (shared/, references/, ../ln-*) are relative to skills repo root. If not found at CWD, locate this SKILL.md directory and go up one level for repo root.

Code Quality Checker

Analyzes Done implementation tasks with quantitative Code Quality Score based on metrics, MCP Ref validation, and issue penalties.

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

Code Quality Score

Formula: Code Quality Score = 100 - metric_penalties - issue_penalties

Issue penalties by severity:

Score interpretation:

Issue Prefixes

PERF- subcategories:

MNT- subcategories:

When to Use

• Invoked by ln-510-quality-coordinator Phase 2
• All implementation tasks in Story status = Done
• Before regression testing (ln-513) and test planning (ln-520)

Workflow (concise)

1. Load Story (full) and Done implementation tasks (full descriptions) via Linear; skip tasks with label “tests”.
2. Collect affected files from tasks (Affected Components/Existing Code Impact) and recent commits/diffs if noted.
3. Calculate code metrics:
   • Cyclomatic Complexity per function (target ≤10)
   • Function size (target ≤50 lines)
   • File size (target ≤500 lines)
   • Nesting depth (target ≤3)
   • Parameter count (target ≤4)

3.5) MCP Ref Validation (MANDATORY for code changes):

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 approach vs alternatives for project context
• Flag suboptimal choices as OPT- issues

Level 2 — BEST PRACTICES (BP-):

• Research: ref_search_documentation("{chosen_approach} best practices {tech_stack} 2026")
• For libraries: query-docs(library_id, "best practices implementation patterns")
• Flag deviations from recommended patterns as BP- issues

Level 3 — PERFORMANCE (PERF-):

• PERF-ALG: Analyze algorithm complexity (detect O(n²)+, research optimal via MCP Ref)
• PERF-CFG: Check library configs (connection pooling, batch sizes, timeouts) via query-docs
• PERF-PTN: Research pattern pitfalls: ref_search_documentation("{pattern} performance bottlenecks")
• PERF-DB: Check for N+1, missing indexes via query-docs(orm_library_id, "query optimization")

Triggers for MCP Ref validation:

• New dependency added (package.json/requirements.txt changed)
• New pattern/library used
• API/database changes
• Loops/recursion in critical paths
• ORM queries added

4. Analyze code for static issues (assign prefixes):

   • SEC-: hardcoded creds, unvalidated input, SQL injection, race conditions
   • MNT-: DRY violations (MNT-DRY: duplicate logic), dead code (MNT-DC: per shared/references/clean_code_checklist.md — 4 categories: unreachable, unused, commented-out, backward-compat), complex conditionals, poor naming
   • ARCH-: layer violations, circular dependencies, guide non-compliance

5. Calculate Code Quality Score:

   • Start with 100
   • Subtract metric penalties (see Code Metrics table)
   • Subtract issue penalties (see Issue penalties table)

6. Output verdict with score and structured issues. Add Linear comment with findings.

7. Agent Review (MANDATORY — Delegated to ln-512):

   MANDATORY STEP: This step MUST execute after Step 6. DO NOT skip. If agents unavailable, ln-512 returns SKIPPED — acceptable. But invocation MUST happen.

   Invoke Skill(skill="ln-512-agent-reviewer", args="{storyId}").

   • ln-512 gets Story/Task references from Linear, builds prompt with references, runs agents in parallel, persists prompts and results in .agent-review/{agent}/.
   • Merge returned suggestions into issues list (same prefixes: SEC-, PERF-, MNT-, ARCH-, BP-, OPT-).
   • If verdict = SUGGESTIONS with area=security or area=correctness → escalate PASS → CONCERNS.
   • If verdict = SKIPPED → Self-Review fallback (native Claude reviews code).
   • Display: agent stats from ln-512 output.

Critical Rules

• Read guides mentioned in Story/Tasks before judging compliance.
• MCP Ref validation: For ANY architectural change, MUST verify via ref_search_documentation before judging.
• Context7 for libraries: When reviewing library usage, query-docs to verify correct patterns.
• Language preservation in comments (EN/RU).
• Do not create tasks or change statuses; caller decides next actions.

Definition of Done

• Story and Done implementation tasks loaded (test tasks excluded).
• Code metrics calculated (Cyclomatic Complexity, function/file sizes).
• MCP Ref validation completed:
  • OPT-: Optimality checked (is chosen approach the best for the goal?)
  • BP-: Best practices verified (correct implementation of chosen approach?)
  • PERF-: Performance analyzed (algorithms, configs, patterns, DB)
• Issues identified with prefixes and severity, sources from MCP Ref/Context7.
• Code Quality Score calculated.
• Agent review: ln-512 invoked; suggestions merged into issues (or SKIPPED/Self-Review fallback).
• Output format:

  verdict: PASS | CONCERNS | ISSUES_FOUND
  code_quality_score: {0-100}
  metrics:
    avg_cyclomatic_complexity: {value}
    functions_over_50_lines: {count}
    files_over_500_lines: {count}
  issues:
    # OPTIMALITY
    - id: "OPT-001"
      severity: medium
      file: "src/auth/index.ts"
      goal: "User session management"
      finding: "Suboptimal approach for session management"
      chosen: "Custom JWT with localStorage"
      recommended: "httpOnly cookies + refresh token rotation"
      reason: "httpOnly cookies prevent XSS token theft"
      source: "ref://owasp-session-management"
  
    # BEST PRACTICES
    - id: "BP-001"
      severity: medium
      file: "src/api/routes.ts"
      finding: "POST for idempotent operation"
      best_practice: "Use PUT for idempotent updates (RFC 7231)"
      source: "ref://api-design-guide#idempotency"
  
    # PERFORMANCE - Algorithm
    - id: "PERF-ALG-001"
      severity: high
      file: "src/utils/search.ts:42"
      finding: "Nested loops cause O(n²) complexity"
      current: "O(n²) - nested filter().find()"
      optimal: "O(n) - use Map/Set for lookup"
      source: "ref://javascript-performance#data-structures"
  
    # PERFORMANCE - Config
    - id: "PERF-CFG-001"
      severity: medium
      file: "src/db/connection.ts"
      finding: "Missing connection pool config"
      current_config: "default (pool: undefined)"
      recommended: "pool: { min: 2, max: 10 }"
      source: "context7://pg#connection-pooling"
  
    # PERFORMANCE - Database
    - id: "PERF-DB-001"
      severity: high
      file: "src/repositories/user.ts:89"
      finding: "N+1 query pattern detected"
      issue: "users.map(u => u.posts) triggers N queries"
      solution: "Use eager loading: include: { posts: true }"
      source: "context7://prisma#eager-loading"
  
    # MAINTAINABILITY - Dead Code
    - id: "MNT-DC-001"
      severity: medium
      file: "src/auth/legacy-adapter.ts"
      finding: "Backward-compatibility wrapper kept after migration"
      dead_code: "legacyLogin() wraps newLogin() — callers already migrated"
      action: "Delete legacy-adapter.ts, remove re-export from index.ts"
  
    # MAINTAINABILITY - DRY
    - id: "MNT-DRY-001"
      severity: medium
      file: "src/service.ts:42"
      finding: "DRY violation: duplicate validation logic"
      suggested_action: "Extract to shared validator"
  

• Linear comment posted with findings.

Reference Files

• Code metrics: references/code_metrics.md (thresholds and penalties)
• Guides: docs/guides/
• Templates for context: shared/templates/task_template_implementation.md
• Agent review prompt: shared/agents/prompt_templates/code_review.md
• Agent review schema: shared/agents/schemas/code_review_schema.json
• Clean code checklist: shared/references/clean_code_checklist.md
• Agent delegation: shared/references/agent_delegation_pattern.md

Version: 5.0.0 Last Updated: 2026-01-29