with one click
with one click
| name | tech-debt |
| description | Scan pyx12 for tech debt and produce a prioritized report |
| argument-hint | [path | category] |
| context | fork |
| agent | Explore |
Produce a prioritized report of tech debt in the codebase. Accepts an optional argument to scope the scan: a file path, a directory, or a category name (type-ignores, todos, legacy-typing, bare-except, any). No argument runs every category over pyx12/.
The goal is a short, actionable report โ not a backlog dump. Lead with the items most worth fixing this week.
pyx12/ for every categorypyx12/ โ restrict every category to that pathpyx12/Run these in parallel (independent Grep / Bash calls) and collect counts + locations.
a. # type: ignore comments โ explicit type holes. Group by error code (arg-type, union-attr, assignment, unused-ignore, etc.). The project enforces mypy strict, so each ignore is a deliberate concession worth re-examining.
Grep: pattern = "type:\s*ignore", glob = "*.py", output_mode = "content", -n = true
b. TODO / FIXME / HACK / XXX โ author-flagged debt. Catches both inline # TODO and TODO: mentions inside docstrings.
Grep: pattern = "\b(TODO|FIXME|HACK)\b|#\s*XXX\b", glob = "*.py", output_mode = "content", -n = true
The XXX arm requires # because XXX appears in test fixture data as a placeholder X12 sender id (e.g. D00XXX) โ without the # constraint the report would drown in those false positives. Filter out pyx12/test/x12testdata.py as belt-and-suspenders.
c. Legacy typing imports โ from typing import List, Dict, Tuple, Optional, Union, Set, FrozenSet, Type. Project is Python 3.11+, so prefer built-in generics (list[X], dict[K, V], X | None).
Grep: pattern = "^from typing import .*\b(List|Dict|Tuple|Optional|Union|Set|FrozenSet|Type)\b", glob = "*.py", output_mode = "content", -n = true
d. Bare except: โ silently swallows everything.
Grep: pattern = "^\s*except\s*:", glob = "*.py", output_mode = "content", -n = true
e. Explicit Any annotations in production code. Tests, examples, scripts, and pyx12/map/* are excluded from mypy's strict-untyped-def rules โ only flag Any outside those.
Grep: pattern = ":\s*Any\b|->\s*Any\b|list\[Any\]|dict\[[^]]+,\s*Any\]", glob = "*.py", output_mode = "files_with_matches"
Then filter out: pyx12/test/, pyx12/tests/, pyx12/examples/, pyx12/scripts/, pyx12/map/.
f. Long modules โ files over 1000 lines are concentrate-of-debt candidates.
Bash: .venv/Scripts/python -c "import pathlib; [print(f'{len(p.read_text().splitlines())}\t{p}') for p in sorted(pathlib.Path('pyx12').rglob('*.py')) if len(p.read_text().splitlines()) > 1000]"
For each # type: ignore location, glance at one line of context โ some are load-bearing (e.g. intentional type holes around X12 map XML) and some are stale survivors of refactors. Note which look like clean wins.
For TODOs, check git blame on a sample to see whether they're recent (worth surfacing) or ancient (probably won't be fixed and could just be removed).
Output to stdout as markdown โ do not create a file. Structure:
## Tech debt summary โ pyx12/{scope}
**Counts:** N type-ignores ยท N TODOs ยท N legacy-typing imports ยท N bare-except ยท N modules >1000 LOC
### Top 5 to fix next
1. [file.py:line](file.py#Lline) โ short reason (e.g. "single unused-ignore โ clean win")
2. ...
### By category
#### `# type: ignore` (N total)
- arg-type: N โ list locations
- union-attr: N โ list locations
- ... (group by error code)
#### TODO/FIXME/HACK (N total)
- [file.py:line](file.py#Lline) โ comment text
#### Legacy typing imports (N total)
- file.py: List, Dict โ use built-ins
#### Bare except (N total)
- ...
#### Long modules
- file.py: N lines
### Notes
Anything ambiguous or context-dependent the user should know before acting.
Rank candidates for "Top 5 to fix next" by impact รท effort:
unused-ignore codes, single-file legacy typing imports, bare-except in non-error-handling codepyx12/map/ (XML-driven), anything in examples/ or scripts/ (excluded from strict mypy already)If a fix is small enough to do in this session, say so explicitly and offer to do it.
pyproject.toml exclude pyx12.test.*, pyx12.tests.*, pyx12.examples.*, pyx12.scripts.*, pyx12.map.* from untyped-def checks. Don't flag missing annotations in those modules โ they're intentional.error_handler.py") instead of listing each one.