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, or REMOVE_YAGNI
• Calculate compliance score (X/10) for Duplication & Over-Abstraction category

Inputs

MANDATORY READ: Load references/audit_worker_core_contract.md. Tool policy: follow host AGENTS.md MCP preferences; load references/mcp_tool_preferences.md and references/mcp_integration_patterns.md only when host policy is absent or 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.

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
3. 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
4. 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
5. Generate recommendations
   • MANDATORY READ: Load references/refactoring_decision_tree.md for pattern selection
   • Match each finding to appropriate refactoring pattern via decision tree
6. 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 managed aggregation
7. Calculate score using penalty algorithm
8. Write Report: Build full markdown report in memory per references/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
9. 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?"

Audit Rules

1. DRY Violations (Don't Repeat Yourself)

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