agentleFS
rayketcham-labrayketcham-lab/qn-claude-web/.claude/skills/techdebt/SKILL.md

techdebt

Skill2 starsChanged 8 months agoApache-2.0View on GitHub

Scan for technical debt and fix it. Uses Simplifier to identify dead code, duplication, complexity, and inconsistencies, then Verifier to confirm no regressions.

14 other projects use a version of this.

Adopted by

Most recently taken up by

Used with

Projects with it also use docs-ci, docs-interfaces and 8 more.

Other files people use alongside this one.

Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
  • jh941213Skill

    docs-ci

    문서 CI(링크·OpenAPI lint·breaking 게이트·mermaid 검증)나 문서 드리프트 감지(docs.yaml 신선도 검사)를 설치하거나 돌릴 때 사용. 문서 내용 작성은 docs-architecture·docs-interfaces·docs-manuals.

    Also in 3 projects that use this

  • jh941213Skill

    docs-interfaces

    API·이벤트 인터페이스 문서(OpenAPI·swagger·AsyncAPI 명세, 엔드포인트 레퍼런스, API 구성도·시퀀스, API CHANGELOG)를 만들거나 코드와 맞출 때 사용. 시스템 구성도는 docs-architecture, API 설계 원칙은 api-design-principles.

    Also in 3 projects that use this

  • RachaelQuiselSkill

    client-docs

    Client documentation. Use when a build needs documentation updates or missing project documents need to be identified.

    Also in 3 projects that use this

  • planailabsSkill

    docs-architecture

    Layout, build pipeline, and structural gotchas for this dual-Astro repo. Read before changing structure, routing, or adding content. Operational/dev-server questions → dev-build skill.

    Also in 3 projects that use this

  • diego-tobalinaSkill

    build-fix

    Fix build and compilation errors systematically. Run when build fails.

    Also in 3 projects that use this

  • nilecuiSkill

    async-python-patterns

    Master Python asyncio, concurrent programming, and async/await patterns for high-performance applications. Use when building async APIs, concurrent systems, or I/O-bound applications requiring non-blocking operations.

    Also in 3 projects that use this

  • +4 more from jh941213

The file

We split this skill into the rules it gives an agent

12 rules. 0 are common, 12 are distinctive, and 0 are very specific to this project.

  • 0

    Common

    Most of the 8 edited versions we read keep these.

  • 12

    Distinctive

    This author's own choices. Worth a look.

  • 0

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    Import ordering and formatting inconsistencies

    line 39
  2. Distinctive:

    Use Glob and Grep to find the files in scope

    line 42
  3. Distinctive:

    Use Grep to search for debt signals:

    line 43
  4. Distinctive:

    Use Read to examine flagged files for the deeper categories (duplication, complexity, naming)

    line 50
  5. Distinctive:

    Run the relevant lint/test command for the language

    line 69
  6. Distinctive:

    If tests fail, revert the change and move the item to the "Deferred" list

    line 70
  7. Distinctive:

    Run the full test suite for affected languages

    line 80
  8. Distinctive:

    Run lint checks (clippy, ruff, shellcheck as appropriate)

    line 81
  9. Distinctive:

    If anything regressed, report it and revert the offending fix

    line 83
  10. Distinctive:

    Before a release to clean up accumulated debt

    line 118
  11. Distinctive:

    After a large feature merge to catch rushed code

    line 119
  12. Distinctive:

    When onboarding to an unfamiliar codebase to understand its weak spots

    line 120

“Common” is measured: kept by at least 6 in 10 of the 8 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

/techdebt — Find and Fix Technical Debt

Scan a file, directory, or entire project for technical debt. Identify issues, fix what can be fixed safely, and report what remains.

Input: Optional path (file, directory, or . for the whole project). Defaults to . if no argument given.

Target: $ARGUMENTS

Phase 1 — SCAN (Identify Debt)

Agent perspective: Simplifier (subagent_type: simplifier)

Analyze the target for the following categories of technical debt, ordered by severity:

Category A — Correctness Risk

  • Missing error handling (silent failures, bare unwrap(), empty except:)
  • TODO/FIXME/HACK comments indicating known broken or incomplete code
  • Unreachable code paths that mask bugs

Category B — Maintainability

  • Duplicated logic (3+ lines repeated in 2+ places) that should be extracted
  • Overly complex functions (50+ lines or 4+ levels of nesting)
  • Inconsistent naming or patterns within the same module
  • Dead code and unused imports

Category C — Code Hygiene

  • Magic numbers/strings that should be constants
  • Outdated comments that no longer match the code
  • Unnecessary type conversions or redundant operations
  • Import ordering and formatting inconsistencies

How to scan:

  1. Use Glob and Grep to find the files in scope
  2. Use Grep to search for debt signals:
    TODO|FIXME|HACK|XXX|NOCOMMIT
    unwrap()  (Rust — without context)
    except:   (Python — bare except)
    # shellcheck disable  (Shell — suppressed warnings)
  3. Use Read to examine flagged files for the deeper categories (duplication, complexity, naming)
  4. For each finding, record: file:line, category (A/B/C), and a one-line description
SCAN checkpoint: [N] findings across [M] files. Breakdown: [A: X, B: Y, C: Z]

Phase 2 — FIX (Safe Remediation)

Agent perspective: Simplifier (subagent_type: simplifier)

Fix what can be fixed safely. Rules:

  1. Category A fixes — Always fix. Missing error handling and dead code are correctness risks.
  2. Category B fixes — Fix if the change is mechanical (extract function, rename, remove dead code). Skip if it requires design decisions.
  3. Category C fixes — Fix only if trivial (add constants, fix imports). Skip anything cosmetic that touches many files.

For each fix:

  • Make the change
  • Run the relevant lint/test command for the language
  • If tests fail, revert the change and move the item to the "Deferred" list
FIX checkpoint: [N] items fixed, [M] deferred. Files modified: [list]

Phase 3 — VERIFY (Confirm No Regressions)

Agent perspective: Verifier (subagent_type: verifier)

  1. Run the full test suite for affected languages
  2. Run lint checks (clippy, ruff, shellcheck as appropriate)
  3. Confirm all previously passing tests still pass
  4. If anything regressed, report it and revert the offending fix

Output Format

## Tech Debt Report: [Target]

**Scanned**: [N files, M lines]
**Found**: [X issues] — A: [n], B: [n], C: [n]
**Fixed**: [Y issues]
**Deferred**: [Z issues]

### Fixed
1. `path/file.ext:42` — [Category A] Added error handling for unchecked Result
2. `path/file.ext:87` — [Category B] Extracted duplicated validation into `validate_input()`
...

### Deferred (Requires Design Decision)
1. `path/file.ext:150` — [Category B] Function `process_all` is 120 lines; needs decomposition plan
2. `path/file.ext:33` — [Category A] TODO: "rewrite when upstream API stabilizes"
...

### Verification
- Tests: [X pass, Y fail, Z skip]
- Lint: PASS/FAIL
- Regressions: [None / List]

### Recommended Next Steps
- [ ] [Highest priority deferred item — why it matters]
- [ ] [Second priority — estimated effort]

When to Use

  • Regular codebase hygiene — run periodically on active projects
  • Before a release to clean up accumulated debt
  • After a large feature merge to catch rushed code
  • When onboarding to an unfamiliar codebase to understand its weak spots
  • Any time the user invokes /techdebt with an optional target

When NOT to Use

  • During active feature development (use /tdd instead)
  • For security-specific audits (use SecOps agent directly)
  • For design/architecture review (use Architect agent or /team)

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.