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.

• 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

• Invoked by ln-510-quality-coordinator Phase 2
• All implementation tasks in Story status = Done
• Before ln-512 tech debt cleanup and ln-513 agent review

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)
4. MCP Ref Validation (MANDATORY for code changes — SKIP if

   --skip-mcp-ref

   flag passed):

   Fast-track mode: When invoked with

   --skip-mcp-ref

   , skip this entire step (no OPT-, BP-, PERF- checks). Proceed directly to step 5 (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 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
5. Analyze code for static issues (assign prefixes): MANDATORY READ:

   shared/references/clean_code_checklist.md

   • SEC-: hardcoded creds, unvalidated input, SQL injection, race conditions
   • MNT-: DRY violations (MNT-DRY-: duplicate logic), dead code (MNT-DC-: per checklist), complex conditionals, poor naming
   • MNT-DRY- cross-story hotspot scan: Grep for common pattern signatures (error handlers:

     catch.*Error|handleError

     , validators:

     validate|isValid

     , config access:

     getSettings|getConfig

     ) across ALL

     src/

     files (count mode). If any pattern appears in 5+ files, sample 3 files (Read 50 lines each) and check structural similarity. If >80% similar → MNT-DRY-CROSS (medium, -10 points):

     Pattern X duplicated in N files — extract to shared module.

   • MNT-DC- cross-story unused export scan: For each file modified by Story, count

     export

     declarations. Then Grep across ALL

     src/

     for import references to those exports. Exports with 0 import references → MNT-DC-CROSS (medium, -10 points):

     {export} in {file} exported but never imported — remove or mark internal.

   • OPT-OSS- cross-reference ln-645 (static, fast-track safe): IF

     docs/project/.audit/645-open-source-replacer*.md

     exists, check if any HIGH-confidence replacement matches files changed in current Story. IF match found → create OPT-OSS-{N} issue with module path, goal, recommended package, confidence, stars, license from ln-645 report. Severity: high if >200 LOC, medium otherwise. This check reads local files only — no MCP calls — runs even with

     --skip-mcp-ref

     .
   • ARCH-: layer violations, circular dependencies, guide non-compliance
   • ARCH-LB-: layer boundary violations (HTTP/DB/FS calls outside infrastructure layer)
   • ARCH-TX-: transaction boundary violations (commit() across multiple layers)
   • ARCH-DTO-: missing DTOs (4+ repeated params), entity leakage (ORM entities returned from API)
   • ARCH-DI-: direct instantiation in business logic (no DI container or mixed patterns)
   • ARCH-CEH-: centralized error handling absent or bypassed
   • ARCH-SES-: session ownership conflicts (DI + local session in same module)
   • MNT-GOD-: god classes (>15 methods or >500 lines per class)
   • MNT-SIG-: method signature quality (boolean flags, unclear returns)
   • MNT-ERR-: error contract inconsistency (mixed raise/return patterns in same service)
6. Calculate Code Quality Score:
   • Start with 100
   • Subtract metric penalties (see Code Metrics table)
   • Subtract issue penalties (see Issue penalties table)
7. Output verdict with score and structured issues. Add Linear comment with findings.

• 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.

• 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)
• ARCH- subcategories checked (LB, TX, DTO, DI, CEH, SES); MNT- subcategories checked (DC, DRY, GOD, SIG, ERR).
• Issues identified with prefixes and severity, sources from MCP Ref/Context7.
• Code Quality Score calculated.
• Output format:
  yaml

  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"
  
    # OPTIMALITY - OSS Replacement (from ln-645, fast-track safe)
    - id: "OPT-OSS-001"
      severity: high
      file: "src/utils/email-validator.ts"
      goal: "Email validation with MX checking"
      finding: "Custom 245-line module has HIGH-confidence OSS replacement"
      chosen: "Custom email-validator.ts (245 lines)"
      recommended: "zod + zod-email (28k stars, MIT, 95% coverage)"
      reason: "Battle-tested, actively maintained, reduces maintenance burden"
      source: "ln-645-audit"
  
    # 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"
  
    # ARCHITECTURE - Entity Leakage
    - id: "ARCH-DTO-001"
      severity: high
      file: "src/api/users.ts:35"
      finding: "ORM entity returned directly from API endpoint"
      issue: "User entity with password hash exposed in GET /users response"
      fix: "Create UserResponseDTO, map entity → DTO before return"
  
    # ARCHITECTURE - Centralized Error Handling
    - id: "ARCH-CEH-001"
      severity: medium
      file: "src/app.ts"
      finding: "No global error handler registered"
      issue: "Unhandled exceptions return stack traces to client in production"
      fix: "Add app.use(globalErrorHandler) with sanitized error responses"
  
    # MAINTAINABILITY - God Class
    - id: "MNT-GOD-001"
      severity: medium
      file: "src/services/order-service.ts"
      finding: "God class with 22 methods and 680 lines"
      issue: "OrderService handles creation, payment, shipping, notifications"
      fix: "Extract PaymentService, ShippingService, NotificationService"
  
    # 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.

• Code metrics:

  references/code_metrics.md

  (thresholds and penalties)
• Guides:

  docs/guides/

• Templates for context:

  shared/templates/task_template_implementation.md

• Clean code checklist:

  shared/references/clean_code_checklist.md