techdebt_skill

Overview

This skill detects and helps remediate technical debt at the end of a coding session. It runs parallel subagents to quickly surface duplicated code, dead imports, security issues, and complexity hotspots. Use it before committing, merging, or as part of CI to keep the codebase healthy.

How this skill works

The orchestrator launches parallel subagents that each scan a specified scope: duplication, security, complexity, and dead code. Results are consolidated, deduplicated, ranked by severity (P0–P3), grouped by file, and summarized in a debt score and actionable report. Optional --fix runs an interactive auto-fix flow for safe, user-approved changes.

When to use it

• End of a development session before commit or merge
• Preparing a pull request or performing code review prep
• Nightly or CI deep scans for release readiness
• When refactoring or assessing large changesets
• To baseline and track debt trends over time

Best practices

• Run the default scan at session end to catch issues while context is fresh
• Address all P0 security or blocking findings before merging
• Use --deep for full-codebase audits and --category flags for focused runs
• Save and compare baselines to monitor debt trends
• Enable interactive --fix only for safe automated fixes; never auto-fix security issues

Example use cases

• Quick session wrap-up: run scan on changed files and fix unused imports
• Pull request gate: run deep scan in CI and block merge on P0 findings
• Refactor planning: identify high-complexity hotspots to prioritize extraction
• Duplication elimination: find repeated 30+ line blocks to extract utilities
• Security triage: detect hardcoded secrets and SQL injection patterns before release