About absolute-debt
A skill for reducing repository-wide lint and type-checking debt in safe, test-verified waves. It targets existing violations and suppressions rather than issues in the current working diff.
Key features
- 01Scans lint and type errors across JS/TS, Python, and Go
- 02Inventories suppressions as technical debt
- 03Groups violations by rule for incremental fixes
- 04Ranks fixes by behavioral risk
- 05Runs tests, lint, typecheck, and build after each wave
Use cases
- 01Clear accumulated lint warnings and type errors
- 02Remove legacy checker suppressions
- 03Tighten lint or type-checking configuration
- 04Clean up existing violations on the main branch
Install
Copy the command and run it in a terminal.
npx skills add https:/After installing, type/absolute-debtin Claude Code to confirm it loaded.
Bundled filesREADME.mdreferences/health-engine.md
Details
From the project READMEStart your first response with the 🧾 emoji.
Absolute Debt
Pay down accumulated lint and type-checker debt across the repo — existing warnings,
errors, and suppressions that built up over time — in safe waves, by rule, with tests green
after each. The goal is a genuinely clean lint + typecheck, not a quieter one.
Runs the shared engine in references/health-engine.md — read it for the
DETECT → SCAN → TRIAGE → FIX → VERIFY → REPORT loop and the safety contract. This file
covers only what's specific to lint/type debt.
When to use
- "Fix our lint warnings", "clean up the type errors", "get the codebase to strict mode".
- Tightening config (enable a rule, raise
tsconfigstrictness) and clearing the fallout. - Burning down accumulated
eslint-disable/@ts-ignore/# type: ignoresuppressions.
debt vs simplify: simplify improves your working diff's quality. debt clears
pre-existing repo-wide lint/type violations on green main. Use debt for standing
cleanup, not for changes you're actively making.
What it scans
| Ecosystem | Lint debt | Type debt |
|---|---|---|
| JS/TS | eslint . (full report, by rule) | tsc --noEmit |
| Python | ruff check / flake8 | mypy / pyright |
| Go | golangci-lint run | go vet ./..., staticcheck |
Also inventory suppressions as debt in their own right: eslint-disable*,
@ts-ignore/@ts-expect-error, # type: ignore, # noqa, //nolint. Each is a hidden
violation. Count violations grouped by rule (not by file) — that's how you wave them.
Risk ranking (TRIAGE)
| Wave | Class | Default |
|---|---|---|
| 1 | autofixable lint (eslint --fix, ruff --fix, gofmt) | fix now — mechanical, safe |
| 2 | manual lint by rule, low behavioral risk (unused, style, imports) | fix this pass, one rule at a time |
| 3 | type errors, and lint rules that can change behavior if "fixed" wrong | gated — review each, may need real logic |
| 4 | removing suppressions (@ts-ignore etc.) | gated — each may surface a real bug |
Fix one rule across the repo per wave, not one file across all rules — keeps diffs reviewable and regressions bisectable. Config tightening (enable rule / raise strictness) is itself a finding: propose it, then clear what it surfaces.
Fix & verify
- Run the autofixers first (wave 1), commit-ready, then re-scan to see what's truly manual.
- Manual fixes: address the cause, not the symptom. A type error means the types are
wrong somewhere — fix the type, don't cast to
any/add# type: ignore. - Never clear a violation by suppressing it. Removing suppressions is the goal, not a tool.
- After each wave: full test + lint + typecheck + build. The violation count must drop and nothing regress.
Gotchas
- Fixing by suppressing.
@ts-ignoreto clear a type error adds debt. Forbidden here. any/castto win. Silences the checker, keeps the bug. Fix the real type.- One-file-all-rules waves. Mixes concerns, unreviewable. Go one-rule-all-files.
- Autofix without review.
--fixcan change behavior (e.g.prefer-conston a reassigned var via a bug). Run tests after autofix too. - Disabling the rule instead of fixing. Loosening config to hit zero is debt laundering, not paydown.
Companion commands
/absolute simplify— quality of code you're currently changing./absolute prune— many unused-var/import warnings vanish once dead code is pruned./absolute work— if clearing the debt needs real refactoring, hand off.