analyze_hotspots

The Formula

Bug density correlates with two factors: how complex a file is, and how often it changes. A complex file that nobody touches is stable. A simple file that changes daily is manageable. A complex file that changes frequently is where bugs live.

analyze_hotspots computes this by combining git commit frequency (churn) with cognitive complexity scores from the index. The result is a ranked list of files ordered by combined risk, not just one dimension.

Why Native Approaches Fall Short

The native way to approximate this is git log --numstat piped through awk to count changes per file, then manually cross-referencing with complexity data (which you have to gather separately). The git log output alone produces hundreds of lines of commit-level statistics that need aggregation. Even after processing, you only have churn data — complexity is a separate exercise entirely.

analyze_hotspots returns a ranked list with both dimensions already combined, scored, and sorted. The 96% token reduction reflects the difference between raw git log output and a pre-computed risk ranking.

The since_days Parameter

By default, analyze_hotspots looks at the last 90 days of git history. This window is configurable with the since_days parameter. A shorter window (30 days) shows recent activity hotspots — useful for sprint retrospectives. A longer window (180 days or more) shows chronic hotspots — useful for strategic refactoring decisions.

analyze_hotspots(repo="local/my-project", since_days=30)

What the Output Contains

Each entry includes:

• File path — the file ranked by combined risk
• Churn count — number of commits touching this file in the window
• Complexity score — aggregate cognitive complexity of the file’s functions
• Risk rank — the combined score that determines ordering

Files that rank high on both dimensions are the ones where investment in refactoring, testing, or documentation will have the highest return.

When to Use It

This is a planning tool, not a daily workflow tool. Use it when:

• You have time allocated for tech debt and need to decide where to spend it. The top 5 hotspots are your highest-leverage targets.
• A retrospective reveals a pattern of bugs in certain areas. Hotspot analysis can confirm whether the problem is structural (complex + churning) or incidental.
• You are building a case for refactoring investment. Hotspot data quantifies the claim that “this module causes most of our bugs.”
• Sprint planning: if a feature touches a hotspot file, allocate extra review time.

Pair with analyze_complexity for function-level detail within the hottest files, and impact_analysis to understand the blast radius of changes to those files.