Broken Windows Hunt

What This Skill Does

Scans the codebase for signs of accumulated technical neglect -- the "broken windows" that signal declining quality and invite further shortcuts. Each finding is a small fix that prevents larger decay.

Detected signal categories:

• Stale TODOs: TODO/FIXME/HACK/XXX comments with no linked issue or with dates older than 90 days.
• Disabled tests: tests marked skip, pending, xfail, or commented out.
• Lint suppressions: inline ignores, nolint, eslint-disable, type: ignore, and similar markers.
• Commented-out code: blocks of commented code longer than 3 lines that are clearly executable code, not documentation.
• Dead imports: imported symbols that are not referenced in the file.
• Empty catch/except blocks: error handlers that silently swallow exceptions.
• Deprecated API usage: calls to functions or methods marked deprecated via language-standard annotations or doc comments.

When To Use

• Daily scheduled sweep to catch new entropy before it compounds.
• After a sprint or release to assess accumulated shortcuts.
• When joining a new codebase to gauge maintenance health.

Do Not Use

• For feature development or refactoring planning (use other skills).
• For security vulnerability scanning (use a security tool).
• For style or formatting issues (use a linter).
• For deep architectural analysis (use intent-clarity-audit or naming-specificity-audit).

Inputs To Confirm

1. Scope -- which directories or file patterns to scan (default: entire repo, excluding vendored/generated code).
2. TODO age threshold -- how old a TODO must be to count as stale (default: 90 days, inferred from git blame).
3. Categories to include -- which signal categories to check (default: all).

Instructions

1. Identify the repository root and enumerate source files, excluding vendored directories (

   vendor/

   ,

   node_modules/

   ,

   .git/

   ,

   third_party/

   ), generated files, lock files, and binary assets.
2. Stale TODOs: search for TODO, FIXME, HACK, and XXX comments. For each, check:
   • Is there a linked issue number or URL? If yes, note it but still flag if the issue is closed or the comment is very old.
   • Use

     git blame

     on the line to determine age. Flag if older than the configured threshold.
   • Record the comment text, file path, line number, and age.
3. Disabled tests: search for test-disabling patterns across languages:
   • JavaScript/TypeScript:

     it.skip

     ,

     describe.skip

     ,

     xit

     ,

     xdescribe

     ,

     test.skip

     .
   • Python:

     @pytest.mark.skip

     ,

     @unittest.skip

     ,

     @pytest.mark.xfail

     .
   • Ruby:

     skip

     ,

     pending

     ,

     xit

     .
   • Go:

     t.Skip()

     .
   • Java:

     @Disabled

     ,

     @Ignore

     .
   • Also detect fully commented-out test functions.
4. Lint suppressions: search for inline suppression markers:

   • eslint-disable

     ,

     @ts-ignore

     ,

     @ts-expect-error

     ,

     nolint

     ,

     noqa

     ,

     type: ignore

     ,

     rubocop:disable

     ,

     // noinspection

     ,

     @SuppressWarnings

     ,

     #pragma

     ,

     NOLINT

     .
   • Record the rule being suppressed if specified.
5. Commented-out code: identify blocks of 3+ consecutive commented lines that parse as valid code in the file's language. Exclude license headers, documentation blocks, and ASCII art.
6. Dead imports: for each file, extract import/require/use statements and check whether the imported symbol appears elsewhere in the file. Flag unused imports.
7. Empty catch blocks: find try/catch, try/except, rescue, or equivalent blocks where the error handler body is empty or contains only a comment.
8. Deprecated API usage: search for deprecation annotations (

   @deprecated

   ,

   @Deprecated

   ,

   DeprecationWarning

   ,

   [[deprecated]]

   ) in the codebase, then find call sites of those deprecated symbols.
9. For each finding, record:
   • Category (one of the seven above).
   • File path and line number.
   • The offending code snippet (1-3 lines).
   • Severity:

     high

     (disabled tests, empty catches),

     medium

     (stale TODOs, lint suppressions, deprecated usage),

     low

     (dead imports, short commented-out code).
   • Suggested fix (e.g., "remove dead import", "add error logging to catch block", "convert TODO to issue #N or delete").
10. Produce the output report.

Output Requirements

Produce a Markdown report with:

• Health summary: a one-paragraph assessment of the codebase's entropy level with total finding count and breakdown by category.
• Findings by category: one section per category with a table of findings (file, line, snippet, severity, suggested fix).
• Trend indicators: if this is not the first run, note whether entropy is increasing, stable, or decreasing (based on finding count vs. previous run if available; otherwise note this is a baseline).
• Quick wins: the top 5 findings that can be fixed in under 5 minutes each.

Quality Bar

• Every finding must include a file path, line number, and code snippet.
• Stale TODO age must be derived from git blame, not guessed.
• Disabled tests must be distinguished from conditionally skipped tests (e.g., platform-specific skips with a reason are lower severity than bare

  skip

  calls).
• Commented-out code detection must not flag license headers or documentation blocks.
• The report must be actionable as a daily cleanup checklist.