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, output_dir.
Domain-aware: Supports domain_mode + current_domain (see audit_output_schema.md#domain-aware-worker-output).
Workflow
- Parse context — extract fields, determine
scan_path (domain-aware if specified), extract output_dir
- Load detection patterns
- MANDATORY READ: Load
references/detection_patterns.md for language-specific Grep/Glob patterns
- Select patterns matching project's
tech_stack
- 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
- Generate recommendations
- MANDATORY READ: Load
references/refactoring_decision_tree.md for pattern selection
- Match each finding to appropriate refactoring pattern via decision tree
- 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
- Calculate score using penalty algorithm
- Write Report: Build full markdown report in memory per
shared/templates/audit_worker_report_template.md, write to {output_dir}/623-principles-{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
- Return Summary: Return minimal summary to coordinator (see Output Format)
Audit Rules
1. DRY Violations (Don't Repeat Yourself)
MANDATORY READ: Load references/detection_patterns.md for detection steps per type.
| Type |
What |
Severity |
Default Recommendation |
Effort |
| 1.1 Identical Code |
Same functions/constants/blocks (>10 lines) in multiple files |
HIGH: business-critical (auth, payment). MEDIUM: utilities. LOW: simple constants <5x |
Extract function → decide location by duplication scope |
M |
| 1.2 Duplicated Validation |
Same validation patterns (email, password, phone, URL) across files |
HIGH: auth/payment. MEDIUM: user input 3+x. LOW: format checks <3x |
Extract to shared validators module |
M |
| 1.3 Repeated Error Messages |
Hardcoded error strings instead of centralized catalog |
MEDIUM: critical messages hardcoded or no error catalog. LOW: <3 places |
Create constants/error-messages file |
M |
| 1.4 Similar Patterns |
Functions with same call sequence/control flow but different names/entities |
MEDIUM: business logic in critical paths. LOW: utilities <3x |
Extract common logic (see decision tree for pattern) |
M |
| 1.5 Duplicated SQL/ORM |
Same queries in different services |
HIGH: payment/auth queries. MEDIUM: common 3+x. LOW: simple <3x |
Extract to Repository layer |
M |
| 1.6 Copy-Pasted Tests |
Identical setup/teardown/fixtures across test files |
MEDIUM: setup in 5+ files. LOW: <5 files |
Extract to test helpers |
M |
| 1.7 Repeated API Responses |
Same response object shapes without DTOs |
MEDIUM: in 5+ endpoints. LOW: <5 endpoints |
Create DTO/Response classes |
M |
| 1.8 Duplicated Middleware Chains |
Identical middleware/decorator stacks on multiple routes |
MEDIUM: same chain on 5+ routes. LOW: <5 routes |
Create named middleware group, apply at router level |
M |
| 1.9 Duplicated Type Definitions |
Interfaces/structs/types with 80%+ same fields |
MEDIUM: in 5+ files. LOW: 2-4 files |
Create shared base type, extend where needed |
M |
| 1.10 Duplicated Mapping Logic |
Same entity→DTO / DTO→entity transformations in multiple locations |
MEDIUM: in 3+ locations. LOW: 2 locations |
Create dedicated Mapper class/function |
M |
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)
| Violation |
Detection |
Severity |
Recommendation |
Effort |
| Abstract class with 1 implementation |
Grep abstract class → count subclasses |
HIGH: prevents understanding core logic |
Remove abstraction, inline |
L |
| Factory for <3 types |
Grep factory patterns → count branches |
MEDIUM: unnecessary pattern |
Replace with direct construction |
M |
| Deep inheritance >3 levels |
Trace extends chain |
HIGH: fragile hierarchy |
Flatten with composition |
L |
| Excessive generic constraints |
Grep <T extends ... & ...> |
LOW: acceptable tradeoff |
Simplify constraints |
M |
| Wrapper-only classes |
Read: all methods delegate to inner |
MEDIUM: unnecessary indirection |
Remove wrapper, use inner directly |
M |
3. YAGNI Violations (You Aren't Gonna Need It)
| Violation |
Detection |
Severity |
Recommendation |
Effort |
| Dead feature flags (always true/false) |
Grep flags → verify never toggled |
LOW: cleanup needed |
Remove flag, keep active code path |
M |
| Abstract methods never overridden |
Grep abstract → search implementations |
MEDIUM: unused extensibility |
Remove abstract, make concrete |
M |
| Unused config options |
Grep config key → 0 references |
LOW: dead config |
Remove option |
S |
| Interface with 1 implementation |
Grep interface → count implementors |
MEDIUM: premature abstraction |
Remove interface, use class directly |
M |
| Premature generics (used with 1 type) |
Grep generic usage → count type params |
LOW: over-engineering |
Replace generic with concrete type |
S |
4. Missing Error Handling
- Find async functions without try-catch
- Check API routes without error middleware
- Verify database calls have error handling
| Severity |
Criteria |
| CRITICAL |
Payment/auth without error handling |
| HIGH |
User-facing operations without error handling |
| MEDIUM |
Internal operations without 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
| Severity |
Criteria |
| HIGH |
No centralized error handler |
| HIGH |
Using uncaughtException listener (Express anti-pattern) |
| MEDIUM |
Middleware handles errors directly (no delegation) |
| MEDIUM |
Async routes without proper error handling |
| LOW |
Stack traces exposed in production |
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
| Severity |
Criteria |
| MEDIUM |
No DI container (tight coupling) |
| MEDIUM |
Direct instantiation in business logic |
| LOW |
Mixed DI and direct imports |
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
| Severity |
Criteria |
| LOW |
No architecture/best practices guide |
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/templates/audit_worker_report_template.md for file format.
Write report to {output_dir}/623-principles-{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. See template for format.
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. See detection_patterns.md for format per DRY type.
Return summary to coordinator:
Report written: docs/project/.audit/623-principles-users.md
Score: X.X/10 | Issues: N (C:N H:N M:N L:N)
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, 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}/623-principles-{domain}.md with FINDINGS-EXTENDED block (atomic single Write call)
- Summary returned to coordinator
Reference Files
- Worker report template:
shared/templates/audit_worker_report_template.md
- 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
1---2name: ln-623-code-principles-auditor-33description: Code principles audit worker (L3). Checks DRY (10 types), KISS/YAGNI, error handling, DI patterns. Returns findings with severity, location, effort, pattern_signature.4---5
6> **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.
7
8# Code Principles Auditor (L3 Worker)
9
10Specialized worker auditing code principles (DRY, KISS, YAGNI) and design patterns.
11
12## Purpose & Scope
13
14- **Worker in ln-620 coordinator pipeline** - invoked by ln-620-codebase-auditor
15- Audit **code principles** (DRY/KISS/YAGNI, error handling, DI)
16- Return structured findings with severity, location, effort, pattern_signature, recommendations
17- Calculate compliance score (X/10) for Code Principles category
18
19## Inputs (from Coordinator)
20
21**MANDATORY READ:** Load `shared/references/task_delegation_pattern.md#audit-coordinator--worker-contract` for contextStore structure.
22
23Receives `contextStore` with: `tech_stack`, `best_practices`, `principles`, `codebase_root`, `output_dir`.
24
25**Domain-aware:** Supports `domain_mode` + `current_domain` (see `audit_output_schema.md#domain-aware-worker-output`).
26
27## Workflow
28
291) **Parse context** — extract fields, determine `scan_path` (domain-aware if specified), extract `output_dir`
302) **Load detection patterns**
31 - **MANDATORY READ:** Load `references/detection_patterns.md` for language-specific Grep/Glob patterns
32 - Select patterns matching project's `tech_stack`
333) **Scan codebase for violations**
34 - All Grep/Glob patterns use `scan_path` (not codebase_root)
35 - Follow step-by-step detection from `detection_patterns.md`
36 - Apply exclusions from `detection_patterns.md#exclusions`
374) **Generate recommendations**
38 - **MANDATORY READ:** Load `references/refactoring_decision_tree.md` for pattern selection
39 - Match each finding to appropriate refactoring pattern via decision tree
405) **Collect findings with severity, location, effort, pattern_id, pattern_signature, recommendation**
41 - Tag each finding with `domain: domain_name` (if domain-aware)
42 - Assign `pattern_signature` for cross-domain matching by ln-620
436) **Calculate score using penalty algorithm**
447) **Write Report:** Build full markdown report in memory per `shared/templates/audit_worker_report_template.md`, write to `{output_dir}/623-principles-{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
458) **Return Summary:** Return minimal summary to coordinator (see Output Format)
46
47## Audit Rules
48
49### 1. DRY Violations (Don't Repeat Yourself)
50
51**MANDATORY READ:** Load `references/detection_patterns.md` for detection steps per type.
52
53| Type | What | Severity | Default Recommendation | Effort |
54|------|------|----------|----------------------|--------|
55| **1.1** Identical Code | Same functions/constants/blocks (>10 lines) in multiple files | HIGH: business-critical (auth, payment). MEDIUM: utilities. LOW: simple constants <5x | Extract function → decide location by duplication scope | M |
56| **1.2** Duplicated Validation | Same validation patterns (email, password, phone, URL) across files | HIGH: auth/payment. MEDIUM: user input 3+x. LOW: format checks <3x | Extract to shared validators module | M |
57| **1.3** Repeated Error Messages | Hardcoded error strings instead of centralized catalog | MEDIUM: critical messages hardcoded or no error catalog. LOW: <3 places | Create constants/error-messages file | M |
58| **1.4** Similar Patterns | Functions with same call sequence/control flow but different names/entities | MEDIUM: business logic in critical paths. LOW: utilities <3x | Extract common logic (see decision tree for pattern) | M |
59| **1.5** Duplicated SQL/ORM | Same queries in different services | HIGH: payment/auth queries. MEDIUM: common 3+x. LOW: simple <3x | Extract to Repository layer | M |
60| **1.6** Copy-Pasted Tests | Identical setup/teardown/fixtures across test files | MEDIUM: setup in 5+ files. LOW: <5 files | Extract to test helpers | M |
61| **1.7** Repeated API Responses | Same response object shapes without DTOs | MEDIUM: in 5+ endpoints. LOW: <5 endpoints | Create DTO/Response classes | M |
62| **1.8** Duplicated Middleware Chains | Identical middleware/decorator stacks on multiple routes | MEDIUM: same chain on 5+ routes. LOW: <5 routes | Create named middleware group, apply at router level | M |
63| **1.9** Duplicated Type Definitions | Interfaces/structs/types with 80%+ same fields | MEDIUM: in 5+ files. LOW: 2-4 files | Create shared base type, extend where needed | M |
64| **1.10** Duplicated Mapping Logic | Same entity→DTO / DTO→entity transformations in multiple locations | MEDIUM: in 3+ locations. LOW: 2 locations | Create dedicated Mapper class/function | M |
65
66**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).
67
68### 2. KISS Violations (Keep It Simple, Stupid)
69
70| Violation | Detection | Severity | Recommendation | Effort |
71|-----------|-----------|----------|---------------|--------|
72| Abstract class with 1 implementation | Grep `abstract class` → count subclasses | HIGH: prevents understanding core logic | Remove abstraction, inline | L |
73| Factory for <3 types | Grep factory patterns → count branches | MEDIUM: unnecessary pattern | Replace with direct construction | M |
74| Deep inheritance >3 levels | Trace extends chain | HIGH: fragile hierarchy | Flatten with composition | L |
75| Excessive generic constraints | Grep `<T extends ... & ...>` | LOW: acceptable tradeoff | Simplify constraints | M |
76| Wrapper-only classes | Read: all methods delegate to inner | MEDIUM: unnecessary indirection | Remove wrapper, use inner directly | M |
77
78### 3. YAGNI Violations (You Aren't Gonna Need It)
79
80| Violation | Detection | Severity | Recommendation | Effort |
81|-----------|-----------|----------|---------------|--------|
82| Dead feature flags (always true/false) | Grep flags → verify never toggled | LOW: cleanup needed | Remove flag, keep active code path | M |
83| Abstract methods never overridden | Grep abstract → search implementations | MEDIUM: unused extensibility | Remove abstract, make concrete | M |
84| Unused config options | Grep config key → 0 references | LOW: dead config | Remove option | S |
85| Interface with 1 implementation | Grep interface → count implementors | MEDIUM: premature abstraction | Remove interface, use class directly | M |
86| Premature generics (used with 1 type) | Grep generic usage → count type params | LOW: over-engineering | Replace generic with concrete type | S |
87
88### 4. Missing Error Handling
89
90- Find async functions without try-catch
91- Check API routes without error middleware
92- Verify database calls have error handling
93
94| Severity | Criteria |
95|----------|----------|
96| **CRITICAL** | Payment/auth without error handling |
97| **HIGH** | User-facing operations without error handling |
98| **MEDIUM** | Internal operations without error handling |
99
100**Effort:** M
101
102### 5. Centralized Error Handling
103
104- Search for centralized error handler: `ErrorHandler`, `errorHandler`, `error-handler.*`
105- Check if middleware delegates to handler
106- Verify async routes use promises/async-await
107- **Anti-pattern:** `process.on("uncaughtException")` usage
108
109| Severity | Criteria |
110|----------|----------|
111| **HIGH** | No centralized error handler |
112| **HIGH** | Using `uncaughtException` listener (Express anti-pattern) |
113| **MEDIUM** | Middleware handles errors directly (no delegation) |
114| **MEDIUM** | Async routes without proper error handling |
115| **LOW** | Stack traces exposed in production |
116
117**Recommendation:** Create single ErrorHandler class. Middleware catches and forwards. Use async/await. DO NOT use uncaughtException listeners.
118
119**Effort:** M-L
120
121### 6. Dependency Injection / Centralized Init
122
123- Check for DI container: `inversify`, `awilix`, `tsyringe` (Node), `dependency_injector` (Python), Spring `@Autowired` (Java), ASP.NET `IServiceCollection` (C#)
124- Grep for `new SomeService()` in business logic (direct instantiation)
125- Check for bootstrap module: `bootstrap.ts`, `init.py`, `Startup.cs`, `app.module.ts`
126
127| Severity | Criteria |
128|----------|----------|
129| **MEDIUM** | No DI container (tight coupling) |
130| **MEDIUM** | Direct instantiation in business logic |
131| **LOW** | Mixed DI and direct imports |
132
133**Recommendation:** Use DI container. Centralize init in bootstrap module. Inject via constructor.
134
135**Effort:** L
136
137### 7. Missing Best Practices Guide
138
139- Check for: `docs/architecture.md`, `docs/best-practices.md`, `ARCHITECTURE.md`, `CONTRIBUTING.md`
140
141| Severity | Criteria |
142|----------|----------|
143| **LOW** | No architecture/best practices guide |
144
145**Recommendation:** Create `docs/architecture.md` with layering rules, error handling patterns, DI usage, coding conventions.
146
147**Effort:** S
148
149## Scoring Algorithm
150
151**MANDATORY READ:** Load `shared/references/audit_scoring.md` for unified scoring formula.
152
153## Output Format
154
155**MANDATORY READ:** Load `shared/templates/audit_worker_report_template.md` for file format.
156
157Write report to `{output_dir}/623-principles-{domain}.md` (or `623-principles.md` in global mode) with `category: "Architecture & Design"`.
158
159**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. See template for format.
160
161**pattern_id:** DRY type identifier (`dry_1.1` through `dry_1.10`). Omit for non-DRY findings.
162
163**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. See `detection_patterns.md` for format per DRY type.
164
165Return summary to coordinator:
166```
167Report written: docs/project/.audit/623-principles-users.md
168Score: X.X/10 | Issues: N (C:N H:N M:N L:N)
169```
170
171## Critical Rules
172
173- **Do not auto-fix:** Report only
174- **Domain-aware scanning:** If `domain_mode="domain-aware"`, scan ONLY `scan_path`
175- **Tag findings:** Include `domain` field in each finding when domain-aware
176- **Pattern signatures:** Include `pattern_id` + `pattern_signature` for every DRY finding
177- **Context-aware:** Use project's `principles.md` to define what's acceptable
178- **Effort realism:** S = <1h, M = 1-4h, L = >4h
179- **Exclusions:** Skip generated code, vendor, migrations (see `detection_patterns.md#exclusions`)
180
181## Definition of Done
182
183- contextStore parsed (including domain_mode, current_domain, output_dir)
184- scan_path determined (domain path or codebase root)
185- Detection patterns loaded from `references/detection_patterns.md`
186- All 7 checks completed (scoped to scan_path):
187 - DRY (10 subcategories: 1.1-1.10), KISS, YAGNI, Error Handling, Centralized Errors, DI/Init, Best Practices Guide
188- Recommendations selected via `references/refactoring_decision_tree.md`
189- Findings collected with severity, location, effort, pattern_id, pattern_signature, recommendation, domain
190- Score calculated per `shared/references/audit_scoring.md`
191- Report written to `{output_dir}/623-principles-{domain}.md` with FINDINGS-EXTENDED block (atomic single Write call)
192- Summary returned to coordinator
193
194## Reference Files
195
196- **Worker report template:** `shared/templates/audit_worker_report_template.md`
197- **Detection patterns:** [references/detection_patterns.md](references/detection_patterns.md)
198- **Refactoring decision tree:** [references/refactoring_decision_tree.md](references/refactoring_decision_tree.md)
199- **Audit scoring formula:** `shared/references/audit_scoring.md`
200- **Audit output schema:** `shared/references/audit_output_schema.md`
201
202---
203**Version:** 5.0.0
204**Last Updated:** 2026-02-08
majiayu000