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

Tech Debt Cleaner (L3 Worker)

Type: L3 Worker

Automated cleanup of safe, low-risk tech debt findings from codebase audits.

Purpose & Scope

Consume audit findings from docs/project/codebase_audit.md (ln-620 output) or ln-511 code quality output
Filter to auto-fixable findings with confidence >=90%
Apply safe fixes: remove unused imports, delete dead code, clean commented-out blocks, remove unsupported aliases
Never touch business logic, complex refactoring, or architectural changes
Create single commit with structured summary of all changes
Invocable from ln-510 quality coordinator pipeline or standalone

Auto-Fixable Categories

Category	Source Prefix	Risk	Auto-Fix Action
Unused imports	MNT-DC-	LOW	Delete import line
Unused variables	MNT-DC-	LOW	Delete declaration
Unused functions (unexported)	MNT-DC-	LOW	Delete function block
Commented-out code (>5 lines)	MNT-DC-	LOW	Delete comment block
Backward-compat shims (>6 months)	MNT-DC-	MEDIUM	Delete shim + update re-exports
Unsupported aliases	MNT-DC-	LOW	Delete alias line
Trailing whitespace / empty lines	MNT-	LOW	Trim / collapse

NOT Auto-Fixable (skip always)

Category	Reason
DRY violations (MNT-DRY-)	Requires architectural decision on where to extract
God classes (MNT-GOD-)	Requires domain knowledge for splitting
Security issues (SEC-)	Requires context-specific fix
Architecture violations (ARCH-*)	Requires design decision
Performance issues (PERF-*)	Requires benchmarking
Any finding with effort M or L	Too complex for auto-fix

When to Use

Use after code quality analysis when safe low-risk cleanup can be applied
Standalone: After ln-620 codebase audit completes (user triggers manually)
Scheduled: As periodic "garbage collection" for codebase hygiene

Inputs

Pipeline mode (ln-510): findings from ln-511 code quality output (passed via coordinator context)
Standalone mode: docs/project/codebase_audit.md (ln-620 output)

MANDATORY READ: Load shared/references/mcp_tool_preferences.md — ALWAYS use hex-line MCP for code files when available. No fallback to standard Read/Edit unless hex-line is down.

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

Use hex-line as the primary path for code files and hex-graph as the primary path for dead-code reference checks. Built-in Read/Edit/Grep are fallback only when the relevant MCP is unavailable.

Workflow

Load findings: Read docs/project/codebase_audit.md. Parse findings from Dead Code section (ln-626 results) and Code Quality section (ln-624 results).
Filter to auto-fixable:
- Category must be in Auto-Fixable table above
- Severity must be LOW or MEDIUM (no HIGH/CRITICAL)
- Effort must be S (small)
- Skip files in: node_modules/, vendor/, dist/, build/, *.min.*, generated code, test fixtures
Verify each finding (confidence check): MANDATORY READ: Load shared/references/clean_code_checklist.md For each candidate fix: a) Read the target file at specified location b) Confirm the finding still exists (file may have changed since audit) c) Confirm removal is safe:
- For unused imports: grep codebase for usage (must have 0 references)
- For unused functions: grep for function name (must have 0 call sites)
- For commented-out code: verify block is code, not documentation
- For unsupported aliases: verify no consumers remain d) Assign confidence score (0-100). Only proceed if confidence >=90
Hex-line acceleration (if available): IF hex-line MCP server is available:
- Use outline(file_path) and discovery-first read_file() before manual cleanup edits. Re-read with edit_ready=true, verbosity="full" only when you need revision/checksums for edit_file.
- Batch cleanup: When fixing >3 files with same pattern (e.g., unused import removal), use bulk_replace(dry_run=true) to preview, then bulk_replace() to apply.
- Verified edits: After each fix, verify(file_path, checksums) to confirm no stale state.
- Semantic dead-code check: Use find_references() before deleting exports, wrappers, aliases, or shims.
- Fall back to per-file Edit or Grep only if the relevant MCP is unavailable.
Apply fixes with per-fix keep/discard (autoresearch pattern): MANDATORY READ: Load shared/references/ci_tool_detection.md for discovery hierarchy. Detect lint + typecheck commands once (reuse for all fixes).

Group verified fixes by file. For each file (process files independently):
- Sort fixes within file by line number descending (bottom-up prevents line shift)
- Apply ALL fixes for this file using Edit tool
- Run lint/typecheck on the modified file
- IF passes → git add {file} (status: keep)
- IF fails → git checkout -- {file} (status: discard), log discarded fixes
- Track per fix: file, lines removed, category, finding ID, status (keep/discard)
If no lint/type commands detected: apply all fixes, skip per-file verification with warning, git add all modified files.

Create commit (kept fixes only):

All kept files already staged via git add in step 4
If zero files kept (all discarded): skip commit, report all failures

Commit message format:

chore: automated tech debt cleanup

Removed {N} auto-fixable findings from codebase audit:
- {count} unused imports
- {count} dead functions
- {count} commented-out code blocks
- {count} unsupported aliases

Source: docs/project/codebase_audit.md
Confidence threshold: >=90%

Update audit report:

Add "Last Cleanup" section to docs/project/codebase_audit.md:

## Last Automated Cleanup
**Date:** YYYY-MM-DD
**Findings fixed:** N of M auto-fixable
**Skipped:** K (confidence <90% or verification failed)
**Build check:** PASSED / SKIPPED

Output Format

verdict: CLEANED | NOTHING_TO_CLEAN | ALL_DISCARDED
stats:
  total_findings: {from audit}
  auto_fixable: {filtered count}
  kept: {files that passed lint/typecheck}
  discarded: {files that failed lint/typecheck}
  skipped: {confidence <90 or stale}
fixes:
  - file: "src/utils/helpers.ts"
    line: 45
    category: "unused_function"
    removed: "formatDate()"
    finding_id: "MNT-DC-003"
    status: "keep"
  - file: "src/api/v1/auth.ts"
    line: 12
    category: "unsupported_alias"
    removed: "export { newAuth as oldAuth }"
    finding_id: "MNT-DC-007"
    status: "discard"
    discard_reason: "typecheck failed: Type error in auth.ts:15"
commit_sha: "abc1234" | null

Critical Rules

Safety first: Never fix if confidence <90%. When in doubt, skip.
Bottom-up editing: Always apply fixes from bottom to top of file to avoid line number shifts.
Per-file keep/discard: If linter/type-checker fails for a file, revert only that file (git checkout -- {file}), keep other successful files.
No business logic: Never modify function bodies, conditionals, or control flow.
Explicit staging: Stage files by name, never git add . or git add -A.
Idempotent: Running twice produces no changes if audit report unchanged.
Git-aware: Only operate on tracked files. Skip untracked or ignored files.
Exclusions: Skip generated code, vendor directories, minified files, test fixtures.

Runtime Summary Artifact

MANDATORY READ: Load shared/references/quality_summary_contract.md, shared/references/quality_worker_runtime_contract.md

Runtime profile:

family: quality-worker
worker: ln-512
summary kind: quality-worker
payload fields used by coordinators: worker, status, verdict, issues, warnings, artifact_path

Invocation rules:

standalone: omit runId and summaryArtifactPath
managed: pass both runId and exact summaryArtifactPath
always write the validated summary before terminal outcome

Definition of Done

Audit report loaded and parsed
Findings filtered to auto-fixable categories
Each finding verified with confidence >=90%
Fixes applied bottom-up per file
Build integrity verified (lint + type check) or skipped with warning
Single commit created with structured message (or all reverted on build failure)
Audit report updated with "Last Automated Cleanup" section
Output YAML returned to caller

Reference Files

Clean code checklist: shared/references/clean_code_checklist.md
Audit output schema: shared/references/audit_output_schema.md
Audit report template: shared/templates/codebase_audit_template.md

Version: 1.0.0 Last Updated: 2026-02-15

ln-512-tech-debt-cleaner