ln-623-duplication-overabstraction-auditor
Checks evidence-backed duplication, over-abstraction, and unused extensibility. Use when auditing DRY/KISS/YAGNI risk.
How do I install this agent skill?
npx skills add https://github.com/levnikolaevich/claude-code-skills --skill ln-623-duplication-overabstraction-auditorIs this agent skill safe to install?
- Gen Agent Trust Hubpass
The skill is a specialized code auditor for identifying duplication and over-abstraction issues (DRY/KISS/YAGNI). It uses standard file search and code-graph tools. While functionally safe, it exhibits a low-severity indirect prompt injection surface typical of code analysis tools that process untrusted data without explicit boundary markers.
- Socketpass
No alerts
- Snykpass
Risk: LOW · No issues
What does this agent skill do?
Paths: File paths (
references/,../ln-*) are relative to this skill directory.
Duplication & Over-Abstraction Auditor (L3 Worker)
Type: L3 Worker
Specialized worker auditing duplication, over-abstraction, and unused extensibility.
Purpose & Scope
- Audit duplication and over-abstraction (DRY/KISS/YAGNI)
- Return structured findings with severity, location, effort, pattern_signature, recommendations
- Emit
MERGE_DUPLICATION,REMOVE_ABSTRACTION, orREMOVE_YAGNI - Calculate compliance score (X/10) for Duplication & Over-Abstraction category
Inputs
MANDATORY READ: Load references/audit_worker_core_contract.md and references/mcp_tool_preferences.md.
Tool policy: You may run as an isolated subagent where host AGENTS.md is not in scope, so default to hex-line MCP first for file reads, search, and edits. Load references/mcp_integration_patterns.md only when MCP behavior is unclear.
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
Detection policy: use two-layer detection (candidate scan, then context verification); load references/two_layer_detection.md only when the verification method is ambiguous.
- Parse context -- extract fields, determine
scan_path(domain-aware if specified), extractoutput_dir - Load detection patterns
- MANDATORY READ: Load
references/detection_patterns.mdfor language-specific Grep/Glob patterns - Select patterns matching project's
tech_stack
- MANDATORY READ: Load
- Scan codebase for violations (Layer 1)
- All Grep/Glob patterns use
scan_path(not codebase_root) - Graph acceleration (if available): IF
contextStore.graph_indexedOR.hex-skills/codegraph/index.dbexists:- 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. Raiselimitonly for deliberate drill-down. - Outline-first read:
outline(file_path)before reading large source files -- understand structure before analyzing principles.
- DRY (1.1-1.10):
- Follow step-by-step detection from
detection_patterns.md - Apply exclusions from
detection_patterns.md#exclusions
- All Grep/Glob patterns use
- 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
- Generate recommendations
- MANDATORY READ: Load
references/refactoring_decision_tree.mdfor pattern selection - Match each finding to appropriate refactoring pattern via decision tree
- MANDATORY READ: Load
- Collect findings with severity, location, effort, pattern_id, pattern_signature, recommendation
- Tag each finding with
domain: domain_name(if domain-aware) - Assign
pattern_signaturefor managed aggregation
- Tag each finding with
- Calculate score using penalty algorithm
- Write Report: Build full markdown report in memory per
references/templates/audit_worker_report_template.md, write to{output_dir}/ln-623--{domain}.md(or623-principles.mdin 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 (see Output Format)
Two-Layer Detection
Detection policy: use two-layer detection (candidate scan, then context verification); load references/two_layer_detection.md only when the verification method is ambiguous.
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?"
| Finding Type | Layer 2 Downgrade Examples |
|---|---|
| DRY | Modules with different lifecycle/ownership -> skip. Intentional duplication for decoupling -> skip |
| KISS | Framework-required abstraction (e.g., DI in Spring) -> downgrade. Single implementation today but interface for testing -> skip |
| YAGNI | Feature flag used in A/B testing -> skip. Config option used by ops team -> skip |
Audit Rules
1. DRY Violations (Don't Repeat Yourself)
MANDATORY READ: Load references/detection_patterns.md for detection steps per type.
| Type | What | Severity | Exception (skip/downgrade) | 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 | Different lifecycle/ownership modules -> skip. Intentional decoupling -> skip | 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 | Different security contexts (auth vs public) -> skip | 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 | User-facing strings requiring per-context wording -> downgrade | 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 | Modules with divergent evolution expected -> skip | 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 | Different bounded contexts; shared DB is worse than duplication -> skip | 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 | Tests intentionally isolated for clarity/independence -> downgrade | Extract to test helpers | M |
| 1.7 Repeated API Responses | Same response object shapes without DTOs | MEDIUM: in 5+ endpoints. LOW: <5 endpoints | Responses with different versioning lifecycle -> skip | 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 | Routes with different auth/rate-limit requirements -> skip | 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 | Types with different ownership/evolution paths -> skip | 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 | Mappings with different validation/enrichment rules -> skip | 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 | Exception (skip/downgrade) | Recommendation | Effort |
|---|---|---|---|---|---|
| Abstract class with 1 implementation | Grep abstract class -> count subclasses | HIGH: prevents understanding core logic | Interface for DI/testing -> skip. Framework-required (Spring, ASP.NET) -> skip | Remove abstraction, inline | L |
| Factory for <3 types | Grep factory patterns -> count branches | MEDIUM: unnecessary pattern | Factory used for DI/testing swap -> downgrade | Replace with direct construction | M |
| Deep inheritance >3 levels | Trace extends chain | HIGH: fragile hierarchy | Framework-mandated hierarchy (UI widgets, ORM models) -> downgrade | Flatten with composition | L |
| Excessive generic constraints | Grep <T extends ... & ...> | LOW: acceptable tradeoff | Type safety for public API boundary -> skip | Simplify constraints | M |
| Wrapper-only classes | Read: all methods delegate to inner | MEDIUM: unnecessary indirection | Adapter pattern for external API isolation -> skip | Remove wrapper, use inner directly | M |
3. YAGNI Violations (You Aren't Gonna Need It)
| Violation | Detection | Severity | Exception (skip/downgrade) | Recommendation | Effort |
|---|---|---|---|---|---|
| Dead feature flags (always true/false) | Grep flags -> verify never toggled | LOW: cleanup needed | A/B testing flags -> skip. Ops-controlled toggles -> skip | Remove flag, keep active code path | M |
| Abstract methods never overridden | Grep abstract -> search implementations | MEDIUM: unused extensibility | Plugin/extension point in public library -> downgrade | Remove abstract, make concrete | M |
| Unused config options | Grep config key -> 0 references | LOW: dead config | Env-specific configs (staging/prod) -> verify before flagging | Remove option | S |
| Interface with 1 implementation | Grep interface -> count implementors | MEDIUM: premature abstraction | Interface for DI/testing mock -> skip | Remove interface, use class directly | M |
| Premature generics (used with 1 type) | Grep generic usage -> count type params | LOW: over-engineering | Public library API designed for consumers -> skip | Replace generic with concrete type | S |
4. Evidence Gate
Do not report aesthetic preferences. A finding is valid only when the worker can show repeated code, an abstraction with no real variation point, or unused extensibility that adds maintenance cost.
| Issue | Required Evidence | Action |
|---|---|---|
| Duplication | matching code blocks, repeated validation/query/mapping, or pattern_signature repeated across files | MERGE_DUPLICATION |
| Over-abstraction | abstraction layer with one real implementation and no framework/testing need | REMOVE_ABSTRACTION |
| YAGNI | feature flag, config option, generic, or extension point with no current use | REMOVE_YAGNI |
Scoring Algorithm
MANDATORY READ: Load references/audit_scoring.md.
Output Format
MANDATORY READ: Load references/templates/audit_worker_report_template.md.
Write JSON summary per 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: "Duplication & Over-Abstraction".
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 managed aggregation. Follow references/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 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
Apply the already-loaded references/audit_worker_core_contract.md.
- Do not auto-fix: Report only
- Domain-aware scanning: If
domain_mode="domain-aware", scan ONLYscan_path - Tag findings: Include
domainfield in each finding when domain-aware - Pattern signatures: Include
pattern_id+pattern_signaturefor every DRY finding - Context-aware: Use project's
principles.mdto define what's acceptable - Effort realism: S = <1h, M = 1-4h, L = >4h
- Exclusions: Skip generated code, vendor, migrations (see
detection_patterns.md#exclusions) - Unique angle: Audit only duplication, over-abstraction, and unused extensibility. Do not audit delivery gates, security, package health, local complexity metrics, architecture boundaries, or runtime lifecycle.
- Action required: Every finding uses
MERGE_DUPLICATION,REMOVE_ABSTRACTION, orREMOVE_YAGNI.
Definition of Done
Apply the already-loaded 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 3 checks completed (scoped to scan_path):
- DRY (10 subcategories: 1.1-1.10), KISS, YAGNI
- Recommendations selected via
references/refactoring_decision_tree.md - Findings collected with severity, location, effort, action, pattern_id, pattern_signature, recommendation, domain
- Score calculated per
references/audit_scoring.md - Report written to
{output_dir}/ln-623--{domain}.mdwith 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
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/levnikolaevich/claude-code-skills/ln-623-duplication-overabstraction-auditor">View ln-623-duplication-overabstraction-auditor on skillZs</a>