| name | nw-hotspot |
| description | Git change frequency hotspot analysis — find the most-changed files in your codebase |
| user-invocable | true |
| argument-hint | [--top=N] [--since=6m] [--json] [--rank report.md] [--detail file] |
NW-HOTSPOT: Code Crime Scene Hotspot Lens
Wave: CROSS_WAVE
Execution: Inline (no agent — Claude executes git commands directly)
Inspiration: Adam Tornhill's "Your Code as a Crime Scene"
Overview
Analyze git change frequency to identify the most-changed files in a codebase. Pure git churn — no complexity metrics. Use as a pre-filter to scope analysis or a post-filter to prioritize existing findings.
How It Works
Run git log --name-only over the configured time period, count commits per file, rank by frequency.
Modes
1. Analyze (default)
Show the most-changed files in the repo. Output is inline only — no files persisted.
/nw-hotspot
/nw-hotspot --top=20
/nw-hotspot --since=12m
Steps:
- Run:
git log --since={since} --format=format: --name-only | sort | uniq -c | sort -rn
- Exclude deleted files (verify each file still exists with
test -f)
- For each file, get last changed date:
git log -1 --format="%ar" -- {file}
- Display ranked table (top N):
Rank │ Commits │ Last Changed │ File
──────┼─────────┼──────────────┼─────────────────────────
1 │ 87 │ 2 days ago │ src/services/payment.ts
2 │ 64 │ 1 week ago │ src/api/controllers/user.ts
3 │ 51 │ 3 days ago │ src/models/order.ts
- Show summary: total files changed in period, time period, top N shown
Defaults: --top: 15, --since: 6 months
2. Rank (post-filter)
Overlay churn data on an existing analysis report to prioritize findings.
/nw-hotspot --rank code-smell-detector-report.md
Steps:
- Run the same git churn analysis
- Read the specified report file
- Extract file paths mentioned in the report
- Annotate each file with its commit count
- Re-sort findings by churn (highest first). Findings without extractable file paths go at the bottom.
- Show noise reduction: "X of Y findings are in low-churn files (< 20 commits)"
3. Detail (deep-dive)
Deep-dive into a single file's change history.
/nw-hotspot --detail src/services/payment.ts
Steps:
- Monthly commit breakdown over the period
- Top contributors to the file
- Co-change coupling: top 5 files that frequently change alongside this one
- Last 10 commit messages for context
4. JSON export (pre-filter composition)
/nw-hotspot --top=10 --json
Output: [{"path": "src/services/payment.ts", "commits": 87, "last_changed": "2 days ago"}, ...]
Parameters
| Flag | Default | Description |
|---|
--top | 15 | Number of files to show |
--since | 6m | Time period (e.g., 3m, 12m, 2024-01-01) |
--json | false | Output as JSON array |
--rank | - | Path to existing report to re-rank by churn |
--detail | - | Path to single file for deep-dive |
Edge Cases
- No commits in period: Display "No commits found since {date}" rather than an empty table
- File renames: Counted as separate files (no
--follow; keeps it simple and fast)
- Empty repo / not a git repo: Display error and exit
Usage from Other Skills
Pre-filter (scope downstream analysis)
Run /nw-hotspot --top=10 --json first, then pass the file list to:
- code-smell-detector: "Analyze only these files: {hotspot list}"
- cognitive-load-analyzer: "Focus analysis on these files: {hotspot list}"
- refactoring-expert: "Prioritize recommendations for these files"
Post-filter (rank existing findings)
Run /nw-hotspot --rank {report.md} after any analysis to prioritize by churn.
In nWave workflows
- Before
/nw-refactor — identify which files to refactor first
- Before
/nw-review — focus review effort on high-churn areas
- Before
/nw-root-why — check if the problematic area is a known hotspot
Next Wave
Usage Context: Inline utility, composable with any analysis skill
Handoff To: Invoking context (no sequential handoff)
Examples
Example 1: Quick scan of a legacy codebase
/nw-hotspot
Example 2: Scope a code smell analysis to hotspots
/nw-hotspot --top=10 --json
Example 3: Prioritize an existing refactoring report
/nw-hotspot --rank code-refactoring-report.md
Example 4: Investigate a specific troubled file
/nw-hotspot --detail src/services/payment.ts
Expected Outputs
No persistent files. Output is displayed inline. JSON mode outputs a JSON array for composition with other tools.
