| name | techdebt |
| description | Scan editable code for tech debt, anti-patterns, and improvement opportunities across 5 categories. Reports findings; the code-modernizer agent applies fixes. |
| allowed-tools | ["Read","Grep","Glob","Bash(uv run poe quick-check)"] |
/techdebt — Tech Debt Scanner
PURPOSE
Surface tech debt and anti-patterns in editable code; do not fix.
CRITICAL
- Skip generated files — never flag or modify
api/**/*.py, models/**/*.py, client.py.
- Confirm dead code with LSP —
grep misses dynamic dispatch and re-exports; use LSP findReferences before declaring something dead.
STANDARD PATH
1. Run lint baseline
uv run poe quick-check
2. Scan editable files by category
Categories:
- Dead code — unused imports/vars/functions/classes; unreachable paths; commented-out blocks. Confirm with
LSP findReferences before flagging.
- Outdated patterns — anti-patterns from
katana_public_api_client/docs/guide.md "Response Handling" section and CLAUDE.md "Known Pitfalls" (UNSET misuse, manual status checks, retry wrapping, hasattr on attrs models, raw list mocks).
- Code duplication — repeated logic that should be a helper, copy-pasted test setup that should be a fixture.
- Code smells — broad
except Exception, missing type annotations on public functions, parameter explosions, name shadowing, circular imports.
- Missing best practices — public functions without docstrings, async tests missing
@pytest.mark.asyncio, fixtures that should be scope="session".
3. Report each finding
**File**: path/to/file.py:42
**Category**: outdated pattern
**Current**: if not isinstance(value, type(UNSET)): use(value)
**Fix**: use(unwrap_unset(value, default))
**Priority**: HIGH | MEDIUM | LOW
4. Output
## Tech Debt Report
### Summary
- Dead code: N
- Outdated patterns: N
- Code duplication: N
- Code smells: N
- Missing best practices: N
### HIGH | MEDIUM | LOW
[grouped findings]
### Improvements to CLAUDE.md
[new anti-patterns discovered]
This skill is report-only. To apply fixes, run harness-kit:simplify for generic
cleanup, then spawn the code-modernizer agent for Katana-specific rewrites.
EDGE CASES
- Dead code candidate has zero
git grep hits — still run LSP findReferences. Pyright walks the real type graph including from m import * and aliased re-exports.
- Recurring anti-pattern not in CLAUDE.md — recommend adding it to "Known Pitfalls" so future scans catch it earlier.
RELATED
code-modernizer agent — actively rewrites the patterns this skill flagsharness-kit:simplify skill — generic cleanup (run before code-modernizer)/review skill — design review (broader than tech debt)
