junk-detection

Junk detection

Separate bad aesthetics from bad incentives. Find code that optimizes a proxy, preserves a constraint that no longer exists, or makes future change harder without buying required behavior.

Read references/taxonomy.md before the first audit in a task. Treat the scanner as triage, never as a verdict.

Choose the audit surface

1. Read repository instructions and the relevant product or domain contract.
2. For branch or PR work, compare the merge-base with origin/main (or the repository's actual trunk) through HEAD, then include staged, unstaged, and untracked work.
3. For a whole-codebase request, start with changed and frequently touched paths, then broaden to all first-party code.
4. Exclude generated, vendored, minified, lock, fixture, snapshot, and migration output unless the request targets it.
5. Preserve the user's existing changes. Audit only unless the user also asks for fixes.

Run the bundled triage script from the repository root:

python3 <skill-dir>/scripts/scan_hotspots.py --scope diff
python3 <skill-dir>/scripts/scan_hotspots.py --scope all

Use --base <ref> when trunk is not origin/main. Use --json when another tool will consume the output.

Reconstruct the real contract

Before calling anything junk, identify:

• The behavior the user or product actually needs.
• Public APIs, persisted data, deployed clients, URLs, events, and integrations that constrain compatibility.
• What the tests, types, lint rules, benchmarks, or review rubric measure.
• The gap between that proxy and the intended behavior.
• The narrowest direct observation that would prove the behavior.

If the contract is unknown, report a suspect and the missing evidence. Do not manufacture certainty from code shape alone.

Audit through six lenses

1. Reward-hacked implementation

Look for a patch that satisfies the evaluator instead of the task:

• Production code branches on test names, fixtures, environment markers, or known inputs.
• Expected outputs, IDs, timestamps, paths, or benchmark cases are hardcoded.
• Tests, graders, CI, timeouts, snapshots, or assertions are weakened to create a green signal.
• Errors are swallowed, exit codes forced to success, features stubbed, or data silently fabricated.
• A test passes but asserts nothing meaningful, mocks away the behavior, or only repeats the implementation.
• The implementation handles visible cases in isolation but breaks composition, invalid inputs, retries, or real user flows.
• The final claim is stronger than the evidence actually collected.