Harness Hotspot Detector

# Harness Hotspot Detector

> Identify modules that represent structural risk via co-change and churn analysis.

## When to Use

- Weekly scheduled analysis to track codebase risk
- Before major refactoring — find the riskiest areas
- When investigating why changes keep breaking unrelated features
- NOT for finding dead code (use cleanup-dead-code)
- NOT for checking architecture rules (use enforce-architecture)

## Prerequisites

A knowledge graph at `.harness/graph/` with git history enables full analysis. If no graph exists,
the skill uses static analysis fallbacks (see Graph Availability section).
Run `harness scan` to enable graph-enhanced analysis.

### Graph Availability

Before starting, check if `.harness/graph/graph.json` exists.

**If graph exists:** Use graph tools as primary strategy. (Staleness sensitivity: **Low** — never auto-refresh.
Git-based churn data in the graph remains useful even when slightly stale.)

**If graph exists and is fresh (or refreshed):** Use graph tools as primary strategy.

**If no graph exists:** Output "Running without graph (run `harness scan` to
enable full analysis)" and use fallback strategies for all subsequent steps.

## Process

### Phase 1: CO-CHANGE — Analyze Co-Change Patterns

Query the graph for `co_changes_with` edges (created by GitIngestor):

```
query_graph(rootNodeIds=[all file nodes], includeEdges=["co_changes_with"])
```

Identify file pairs that frequently change together:

- **Co-located pairs** (same directory): Normal — they share a concern.
- **Distant pairs** (different modules): Suspicious — may indicate hidden coupling.

Flag distant co-change pairs as potential hotspots.

### Phase 2: CHURN — Identify High-Churn Files

Query commit nodes to find files with the highest change frequency:

```
query_graph(rootNodeIds=[commit nodes], includeTypes=["commit", "file"], includeEdges=["co_changes_with"])
```

Rank files by:

- Total commit count touching the file
- Recent velocity (commits in last 30 days vs prior 30 days)
- Change size (total lines added + deleted)

High churn in shared utilities or core modules = high risk.

#### Fallback (without graph)

When no graph is available, git log provides nearly all the data needed (~90% completeness):

1. **Per-file churn**: `git log --format="%H" -- <file>` for each source file (use glob to enumerate). Count commits per file. Sort descending to rank by churn.
2. **Recent velocity**: `git log --since="30 days ago" --format="%H" -- <file>` vs `git log --since="60 days ago" --until="30 days ago" --format="%H" -- <file>` to compare recent vs prior 30-day windows.
3. **Co-change detection**: `git log --format="%H %n" --name-only` to build a map of which files changed together in the same commit. File pairs that appear together in >3 commits are co-change candidates.
4. **Distant co-change identification**: For co-change pairs, check if they share a parent directory (co-located = normal) or are in different modules (distant = suspicious).
5. **Complexity proxy**: Use line count (`wc -l`) as a rough proxy for complexity when graph complexity metrics are unavailable.
6. **Hidden dependency detection**: Cross-reference co-change pairs against import parsing (grep for import statements). Co-change pairs with no import relationship indicate hidden dependencies.

> Fallback completeness: ~90% — git log provides nearly all the data the graph stores for this use case.

### Phase 3: COUPLING — Detect Hidden Dependencies

Cross-reference co-change data with structural data:

1. **High logical coupling, low structural coupling**: Files that always change together but have no `imports` edge between them. This indicates a hidden dependency — changing one requires changing the other, but the code doesn't express this relationship.

2. **High structural coupling, low logical coupling**: Files with `imports` edges but that rarely change together. This may indicate over-coupling — the import exists but the relationship is weak.

Use `get_relationships` to check structural edges between co-change pairs.

### Phase 4: REPORT — Generate Ranked Hotspot Report

```
## Hotspot Analysis Report

### Risk Hotspots (ranked by risk score)

1. **src/services/billing.ts** — Risk: HIGH
   - Churn: 23 commits (last 30 days: 8)
   - Co-changes with: src/types/invoice.ts (distant, 15 co-changes)
   - Hidden dependency: no imports edge to invoice.ts
   - Recommendation: Extract shared billing types or add explicit dependency

2. **src/utils/helpers.ts** — Risk: HIGH
   - Churn: 45 commits (highest in codebase)
   - Co-changes with: 12 different files across 4 modules
   - Recommendation: Split into domain-specific utilities to reduce blast radius

3. **src/middleware/auth.ts** — Risk: MEDIUM
   - Churn: 15 commits
   - Co-changes with: src/routes/login.ts (co-located, expected)
   - No hidden dependencies detected

### Summary
- Total hotspots detected: 5
- High risk: 2
- Medium risk: 3
- Hidden dependencies: 1
```

## Harness Integration

- **`harness scan`** — Recommended before this skill for full graph-enhanced analysis. If graph is missing, skill uses git log fallbacks.
- **`harness validate`** — Run after acting on findings to verify project health.
- **Graph tools** — This skill uses `query_graph`, `get_impact`, and `get_relationships` MCP tools.

## Success Criteria

- Hotspots ranked by composite risk score (churn + coupling)
- Hidden dependencies identified (high co-change, no structural edge)
- Co-change patterns detected and classified (co-located vs distant)
- Report follows the structured output format
- All findings are backed by graph query evidence (with graph) or git log analysis (without graph)

## Rationalizations to Reject

These are common rationalizations that sound reasonable but lead to incorrect results. When you catch yourself thinking any of these, stop and follow the documented process instead.

| Rationalization                                                                                                          | Why It Is Wrong                                                                                                                                         |
| ------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| "High churn just means the file is actively developed, not that it is risky"                                             | High churn in shared utilities specifically equals high risk. A file with 45 commits that co-changes with 12 different files indicates hidden coupling. |
| "The co-change pair is between two files in different modules, but they probably just happen to change at the same time" | Distant co-change pairs are flagged as suspicious precisely because they indicate hidden coupling.                                                      |
| "No graph exists so the analysis will be too incomplete to be useful"                                                    | Git log provides ~90% of the data needed for hotspot detection. The fallback is the highest-completeness fallback across all graph-enhanced skills.     |

## Examples

### Example: Detecting Hotspots in a Growing Codebase

```
Input: Scheduled weekly analysis on project root

1. CO-CHANGE — query_graph for co_changes_with edges
               Found 4 distant co-change pairs
2. CHURN     — Ranked files by commit frequency
               billing.ts: 23 commits, helpers.ts: 45 commits
3. COUPLING  — Cross-referenced co-change vs imports edges
               billing.ts <-> invoice.ts: 15 co-changes, no imports edge
               (hidden dependency detected)
4. REPORT    — Ranked hotspots by risk score

Output:
  Hotspots: 5 total (2 high, 3 medium)
  Hidden dependencies: 1 (billing.ts <-> invoice.ts)
  Top recommendation: Extract shared billing types
```

## Gates

- **Graph preferred, fallback available.** If no graph exists, use git log for churn and co-change analysis. Do not stop — git log provides ~90% of the data needed.
- **Systematic analysis required.** Use graph `co_changes_with` edges when available; use `git log` commit analysis when not. Do not guess — parse actual git history.

## Escalation

- **When hidden dependencies found**: Recommend making the dependency explicit (add import) or extracting shared code.
- **When a single file has >30 commits**: Flag as critical hotspot requiring architectural attention.