ha:techdebt
Analyze Home Assistant (Python) technical debt — duplicates, refactoring opportunities, ruff findings. Use when asked about code quality, cleanup, or what to improve.
SKILL.mdskills/techdebt/SKILL.md
GitHubTechnical Debt Detection
Find and eliminate duplicate code patterns, anti-patterns, and refactoring opportunities in Home Assistant integrations (Python).
Iron Laws - Never Violate These
- Search before refactoring - Understand full scope of duplication before extracting
- Three strikes rule - Extract shared code only after 3+ duplications
- Prefer composition - Use mixins, shared base entity classes, and helper functions over inheritance-heavy abstractions
- Test coverage first - Ensure tests exist before refactoring duplicated code
Analysis Checklist
1. Run ruff for Automated Detection
Run ruff check . --output-format json and parse the output.
Focus on:
- Design/complexity issues (
C901mccabe complexity,PLR0911/PLR0912/PLR0915too-many-returns/branches/statements) - Consistency issues (
Npep8-naming,Iimport ordering) - Dead code and untyped escapes (
F401/F841unused import/variable,ARGunused arguments,ANN401Anyannotations) — dead/commented-out code is Iron Law P10 and must be deleted, not flagged for later
Also run jscpd homeassistant/components/<domain> for a dedicated copy-paste/duplicate-code report (percentage duplicated, exact clone locations).
2. Find Repeated Coordinator Fetches
Use Grep to search for fetch logic living outside the coordinator — direct client/library calls (await client., hass.async_add_executor_job, session.get() repeated across homeassistant/components/**/*.py platform and entity files.
The coordinator should own the fetch; entities read coordinator.data. Repeated fetches in multiple entities are the primary duplication smell (P11: library owns protocol, coordinator owns fetch).
3. Find Duplicate Entity Descriptions & Validators
Use Grep with output_mode: "count" to count EntityDescription subclass instantiations (SensorEntityDescription(, BinarySensorEntityDescription(, ...) in homeassistant/components/**/*.py — near-identical descriptions belong in one shared tuple.
Use Grep to find repeated voluptuous validators (vol.Required, vol.Optional, cv.string, vol.Range) that recur across config_flow.py, services.py, and schema modules — extract to a shared schema constant.
4. Find Copy-Pasted Service Handlers & Platform Setup
Use Grep to find repeated service registrations (hass.services.async_register() and near-identical platform boilerplate (async_setup_entry, async_add_entities) across homeassistant/components/**/*.py.
Service actions should be registered once in async_setup (a services.py module — P18); repeated platform setup usually wants a shared entity base class.
Common Duplication Patterns
| Pattern | Symptom | Solution |
|---|---|---|
| Repeated fetches | Same client/library call in multiple entities or platforms | Centralize in the DataUpdateCoordinator; entities read coordinator.data (P11) |
| Duplicate entity descriptions | Same EntityDescription fields copied per entity |
Extract to a module-level tuple of descriptions / shared base description |
| Repeated voluptuous validators | Same vol.Required/cv.string combos on every schema |
Extract to a shared schema constant or cv helper |
| Similar platforms/services | Copy-pasted async_setup_entry or service handlers |
Extract a shared entity base class; register services once in services.py (P18) |
| Repeated transforms | Same comprehensions / .get() chains |
Extract to a helper function |
| Long functions/files | Methods or files exceeding ~400 lines, deep nesting (C901 violations) |
Split by responsibility; extract private helper methods |
| God coordinator/module | One coordinator or module doing unrelated things | Split by responsibility (see integration-architecture skill) |
| Dead / commented-out code | ruff F401/F841; grep commented-out blocks, restated framework defaults, unused translation keys |
Delete now — Iron Law P10 (dead, unused, commented-out code is never allowed) |
| Stale TODO/FIXME | Grep for TODO/FIXME/HACK comments with no tracking issue |
Convert to a tracked task or resolve now |
Reporting Format
For each duplication found, report:
- Location: File paths and line numbers
- Pattern: What code is duplicated
- Extraction: Suggested shared function / coordinator / entity description / schema
- Effort: Low/Medium/High to fix
Usage
Run /ha:techdebt to analyze the codebase and generate a prioritized report of technical debt with specific remediation steps.