hone:broken-windows-hunt

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).

1. TODO age threshold -- how old a TODO must be to count as stale

(default: 90 days, inferred from git blame).

1. 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.

1. 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.

1. 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.

1. 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.

1. 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.

1. Dead imports: for each file, extract import/require/use

statements and check whether the imported symbol appears elsewhere in the file. Flag unused imports.

1. Empty catch blocks: find try/catch, try/except, rescue, or

equivalent blocks where the error handler body is empty or contains only a comment.

1. Deprecated API usage: search for deprecation annotations

(@deprecated, @Deprecated, DeprecationWarning, [[deprecated]]) in the codebase, then find call sites of those deprecated symbols.

1. 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").

1. 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.