ln-623-code-principles-auditor（ln 623 代码原则审核员）

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. If shared/ is missing, fetch files via WebFetch from https://raw.githubusercontent.com/levnikolaevich/claude-code-skills/master/skills/{path}.

Code Principles Auditor (L3 Worker)

Type: L3 Worker

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

Purpose & Scope

• 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

MANDATORY READ: Load shared/references/audit_worker_core_contract.md. MANDATORY READ: Load shared/references/mcp_tool_preferences.md and shared/references/mcp_integration_patterns.md

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

Use hex-graph first when clone groups, implementations, or semantic relationships materially improve the audit. Use hex-line first for local code reads when available. If MCP is unavailable, unsupported, or not indexed, continue with built-in Read/Grep/Glob/Bash and state the fallback in the report.

Workflow

MANDATORY READ: Load shared/references/two_layer_detection.md for detection methodology.

1. Parse context -- extract fields, determine scan_path (domain-aware if specified), extract output_dir
2. Load detection patterns

- MANDATORY READ: Load references/detection_patterns.md for language-specific Grep/Glob patterns - Select patterns matching project's tech_stack

1. 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: - DRY (1.1-1.10): audit_workspace(path=scan_path, verbosity="minimal", limit=5, clone_member_limit=3) -- each returned clone group = DRY candidate. Raise limits only for deliberate drill-down. Use clone kind and hotspot context for severity triage. Fall back to grep patterns if unavailable. - KISS inheritance: find_implementations(symbol) for abstract classes -- count implementations (1 = KISS candidate). Trace inheritance depth via graph. - Complexity: audit_workspace(path=scan_path, verbosity="minimal", limit=5) -- use returned hotspots to pre-identify complex functions for KISS/quality analysis. Raise limit only for deliberate drill-down. - Outline-first read: outline(file_path) before reading large source files -- understand structure before analyzing principles. - Follow step-by-step detection from detection_patterns.md - Apply exclusions from detection_patterns.md#exclusions

1. Analyze context per candidate (Layer 2)

- DRY: read both code blocks to confirm true duplication (not just similar naming or shared interface) - KISS: check if abstraction serves DI pattern (valid single-impl interface) or is premature - YAGNI: check if feature flag was recently added (intentional) or dormant for months

1. Generate recommendations

- MANDATORY READ: Load references/refactoring_decision_tree.md for pattern selection - Match each finding to appropriate refactoring pattern via decision tree

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

1. Calculate score using penalty algorithm
2. Write Report: Build full markdown report in memory per shared/templates/audit_worker_report_template.md, write to {output_dir}/ln-623--{domain}.md (or 623-principles.md in global mode) in single Write call. Include <!-- FINDINGS-EXTENDED --> JSON block with pattern_signature fields for cross-domain DRY analysis
3. Return Summary: Return minimal summary to coordinator (see Output Format)

Two-Layer Detection (MANDATORY)

MANDATORY READ: Load shared/references/two_layer_detection.md

All findings require Layer 2 context analysis. Layer 1 finding without Layer 2 = NOT a valid finding. Before reporting, ask: "Is this violation intentional or justified by design?"

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

Outcome Goal: All errors are logged with context and return clear user-facing messages. No error is silently swallowed. Stack traces never leak to production responses. Implementation choice (ErrorHandler class, middleware, decorator) depends on project stack and size.

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

Outcome Goal: Dependencies are replaceable for testing without modifying production code. No tight coupling between service instantiation and business logic. Implementation choice (DI container, factory functions, parameter injection, closures) depends on project size and stack.

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_worker_core_contract.md and shared/references/audit_scoring.md.

Output Format

MANDATORY READ: Load shared/references/audit_worker_core_contract.md and shared/templates/audit_worker_report_template.md.

Write JSON summary per shared/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-623--{domain}.md (or 623-principles.md in global mode) with category: "Architecture & Design".

FINDINGS-EXTENDED block (required for this worker): After the Findings table, include a <!-- FINDINGS-EXTENDED --> JSON block containing all DRY findings with pattern_signature for cross-domain matching by ln-620 coordinator. Follow shared/templates/audit_worker_report_template.md.

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). Same signature in multiple domains triggers cross-domain DRY finding. Format is defined in references/detection_patterns.md.

Return summary per shared/references/audit_summary_contract.md.

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-623--users.md
Score: X.X/10 | Issues: N (C:N H:N M:N L:N)

Critical Rules

MANDATORY READ: Load shared/references/audit_worker_core_contract.md.

• 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

MANDATORY READ: Load shared/references/audit_worker_core_contract.md.

• contextStore parsed (including domain_mode, current_domain, output_dir)
• 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
• Report written to {output_dir}/ln-623--{domain}.md with FINDINGS-EXTENDED block (atomic single Write call)
• Summary written per contract

Reference Files

• Detection patterns: references/detection_patterns.md
• Refactoring decision tree: references/refactoring_decision_tree.md

Version: 5.0.0 Last Updated: 2026-02-08