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 Principles Auditor (L3 Worker)

Specialized worker auditing code principles (DRY, KISS, YAGNI) and design patterns.

Purpose & Scope

• Worker in ln-620 coordinator pipeline – invoked by ln-620-codebase-auditor
• Audit code principles (DRY/KISS/YAGNI, error handling, DI)
• Return structured findings with severity, location, effort, pattern_signature, recommendations
• Calculate compliance score (X/10) for Code Principles category

Inputs (from Coordinator)

MANDATORY READ: Load shared/references/task_delegation_pattern.md#audit-coordinator--worker-contract for contextStore structure.

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

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

Workflow

1. Parse context — extract fields, determine scan_path (domain-aware if specified)
2. Load detection patterns
   • MANDATORY READ: Load references/detection_patterns.md for language-specific Grep/Glob patterns
   • Select patterns matching project’s tech_stack
3. Scan codebase for violations
   • All Grep/Glob patterns use scan_path (not codebase_root)
   • Follow step-by-step detection from detection_patterns.md
   • Apply exclusions from detection_patterns.md#exclusions
4. Generate recommendations
   • MANDATORY READ: Load references/refactoring_decision_tree.md for pattern selection
   • Match each finding to appropriate refactoring pattern via decision tree
5. Collect findings with severity, location, effort, pattern_id, pattern_signature, recommendation
   • Tag each finding with domain: domain_name (if domain-aware)
   • Assign pattern_signature for cross-domain matching by ln-620
6. Calculate score using penalty algorithm
7. Return JSON result to coordinator
   • Include domain and scan_path fields (if domain-aware)

Audit Rules

1. DRY Violations (Don’t Repeat Yourself)

MANDATORY READ: Load references/detection_patterns.md for detection steps per type.

Recommendation selection: Use references/refactoring_decision_tree.md to choose the right refactoring pattern based on duplication location (Level 1) and logic type (Level 2).

2. KISS Violations (Keep It Simple, Stupid)

3. YAGNI Violations (You Aren’t Gonna Need It)

4. Missing Error Handling

• Find async functions without try-catch
• Check API routes without error middleware
• Verify database calls have error handling

Effort: M

5. Centralized Error Handling

• Search for centralized error handler: ErrorHandler, errorHandler, error-handler.*
• Check if middleware delegates to handler
• Verify async routes use promises/async-await
• Anti-pattern: process.on("uncaughtException") usage

Recommendation: Create single ErrorHandler class. Middleware catches and forwards. Use async/await. DO NOT use uncaughtException listeners.

Effort: M-L

6. Dependency Injection / Centralized Init

• Check for DI container: inversify, awilix, tsyringe (Node), dependency_injector (Python), Spring @Autowired (Java), ASP.NET IServiceCollection (C#)
• Grep for new SomeService() in business logic (direct instantiation)
• Check for bootstrap module: bootstrap.ts, init.py, Startup.cs, app.module.ts

Recommendation: Use DI container. Centralize init in bootstrap module. Inject via constructor.

Effort: L

7. Missing Best Practices Guide

• Check for: docs/architecture.md, docs/best-practices.md, ARCHITECTURE.md, CONTRIBUTING.md

Recommendation: Create docs/architecture.md with layering rules, error handling patterns, DI usage, coding conventions.

Effort: S

Scoring Algorithm

MANDATORY READ: Load shared/references/audit_scoring.md for unified scoring formula.

Output Format

MANDATORY READ: Load shared/references/audit_output_schema.md for base JSON structure.

Return JSON with additional fields for DRY findings:

{
  "category": "Architecture & Design",
  "score": 6,
  "domain": "users",
  "scan_path": "src/users",
  "total_issues": 12,
  "critical": 1,
  "high": 3,
  "medium": 5,
  "low": 3,
  "checks": [
    {"id": "dry_violations", "name": "DRY Violations", "status": "failed", "details": "6 duplications found (types 1.2, 1.5, 1.8)"},
    {"id": "kiss_violations", "name": "KISS Violations", "status": "warning", "details": "1 over-engineered abstraction"},
    {"id": "yagni_violations", "name": "YAGNI Violations", "status": "passed", "details": "No unused code"}
  ],
  "findings": [
    {
      "severity": "HIGH",
      "location": "src/users/validators/email.ts:12",
      "issue": "Email validation regex duplicated in 3 files",
      "principle": "DRY Principle",
      "pattern_id": "dry_1.2",
      "pattern_signature": "validation_email",
      "recommendation": "Extract to shared/validators/email.ts",
      "effort": "M",
      "domain": "users"
    }
  ]
}

pattern_id: DRY type identifier (dry_1.1 through dry_1.10). Omit for non-DRY findings.

pattern_signature: Normalized key for the detected pattern (e.g., validation_email, sql_users_findByEmail, middleware_auth_validate_ratelimit). Used by ln-620 coordinator for cross-domain matching — same signature in multiple domains triggers cross-domain DRY finding. See detection_patterns.md for format per DRY type.

Critical Rules

• Do not auto-fix: Report only
• Domain-aware scanning: If domain_mode="domain-aware", scan ONLY scan_path
• Tag findings: Include domain field in each finding when domain-aware
• Pattern signatures: Include pattern_id + pattern_signature for every DRY finding
• Context-aware: Use project’s principles.md to define what’s acceptable
• Effort realism: S = <1h, M = 1-4h, L = >4h
• Exclusions: Skip generated code, vendor, migrations (see detection_patterns.md#exclusions)

Definition of Done

• contextStore parsed (including domain_mode and current_domain)
• scan_path determined (domain path or codebase root)
• Detection patterns loaded from references/detection_patterns.md
• All 7 checks completed (scoped to scan_path):
  • DRY (10 subcategories: 1.1-1.10), KISS, YAGNI, Error Handling, Centralized Errors, DI/Init, Best Practices Guide
• Recommendations selected via references/refactoring_decision_tree.md
• Findings collected with severity, location, effort, pattern_id, pattern_signature, recommendation, domain
• Score calculated per shared/references/audit_scoring.md
• JSON returned to coordinator with domain metadata

Reference Files

• Detection patterns: references/detection_patterns.md
• Refactoring decision tree: references/refactoring_decision_tree.md
• Audit scoring formula: shared/references/audit_scoring.md
• Audit output schema: shared/references/audit_output_schema.md

Version: 5.0.0 Last Updated: 2026-02-08