techdebt-scan

name	techdebt-scan
description	Scan editable code for tech debt and anti-patterns specific to this repo (UNSET misuse, manual status-code checks, retry wrapping, dead code). Reports findings without applying fixes.
allowed-tools	Read, Grep, Glob, Bash(uv run poe quick-check), Bash(uv run poe fix), Bash(git diff*), Bash(git log*)

/techdebt-scan — StatusPro tech-debt scan

PURPOSE

Find anti-patterns, dead code, and code smells in editable files. Survey only — does not apply fixes. For active remediation, spawn the code-modernizer agent.

CRITICAL

• Never flag or scan generated files — statuspro_public_api_client/api/**/*.py, statuspro_public_api_client/models/**/*.py, statuspro_public_api_client/client.py are output of regeneration
• LSP-verify before flagging dead code — run LSP findReferences on the symbol; pyright walks the real import graph (from x import *, aliased re-exports) that grep misses. Zero references = safe to flag.
• LSP-verify before flagging hasattr rewrites — run LSP hover. If the type points into an attrs model (Unset | T), the rewrite to unwrap_unset is safe. Plain Python class? It may be a real hasattr check — leave it.

STANDARD PATH

1. Establish baseline

uv run poe quick-check

2. Scan editable files by category

Scan statuspro_public_api_client/ (excluding generated paths above), statuspro_mcp_server/, tests/, scripts/:

• Dead code — unused imports/variables/functions/classes; verify with LSP findReferences before flagging
• UNSET / helper anti-patterns — isinstance(_, type(UNSET)), hasattr on attrs fields, manual response.status_code == 200, value if value is not None else UNSET
• Architecture violations — wrapping API methods with retry logic, broad except Exception without re-raise/log
• Code smells — too many parameters (extract dataclass), names shadowing built-ins, deeply nested conditionals, duplicate test-fixture logic
• Missing best practices — public functions without docstrings, async tests missing @pytest.mark.asyncio, fixtures that should be scope="session"

3. Auto-fix what's safe

uv run poe fix

4. Report

## Tech Debt Report

### Summary
- Dead code: N
- UNSET/helper anti-patterns: N
- Architecture violations: N
- Code smells: N
- Missing best practices: N

### HIGH (breaks conventions)
[file:line — current code → suggested fix]

### MEDIUM (code quality)
[...]

### LOW (nice to have)
[...]

### Improvements to CLAUDE.md
[Any new anti-patterns/pitfalls discovered worth documenting]

EDGE CASES

• [Apply fixes, don't just survey] — Spawn code-modernizer agent with this report; it actively rewrites and runs agent-check between batches.
• [New anti-pattern found] — Add it to CLAUDE.md "Known Pitfalls" or "Anti-Patterns to Avoid" so future scans catch it earlier.

RELATED

• code-modernizer agent — actively applies fixes for these categories
• CLAUDE.md "Known Pitfalls" + "Anti-Patterns to Avoid" — source of truth for project-specific debt