hotmess

hotmess

Identifies clusters of high-churn code and explains why they're problematic — not just a ranked file list. The user wants insight: which areas of the codebase are unstable, why, and what to do.

When to use

Trigger phrases: "hotmess", "hotspots", "what's churning", "unstable code", "where's the technical debt", "what's a mess in X", "/hotmess ". Always invoke for these — even if the user gives no time window or extension, fall back to sensible defaults (30 days, auto code detection).

How to run

Always invoke this skill's bundled analyzer (scripts/analyze.py, in this skill's base directory), which emits structured JSON with four signal sets. Do not reimplement git log parsing inline.

"<SKILL_DIR>/scripts/analyze.py" <path> --since "<expr>" [--ext .go,.ts] [--top N] [--html /tmp/hotmess.html] [--quiet]

<SKILL_DIR> is the "Base directory for this skill" path provided when the skill is invoked. Run from inside the target git repo (or pass an absolute path; git resolves it).

Defaults: --since "30 days ago", --top 30, auto-detected code extensions.

If the user asks for a visualization, diagram, picture, "show me", chart, or graph — also pass --html /tmp/hotmess.html and then open /tmp/hotmess.html. Use --quiet together with --html if you don't need the JSON in the same call. The HTML page contains a Mermaid module map (modules colored by classification, edges = cross-directory co-change), plus collapsible tables for stems and co-change pairs.

Requires Python 3.8+ (stdlib only) and git on PATH.

Period shorthand to translate before passing to --since:

• 7d → "7 days ago", 2w → "2 weeks ago", 1m → "1 month ago"
• ISO date (2026-04-01) → pass through unchanged

What the JSON contains

scope        { path, since, ext, recent_window_days }
totals       { commits, files, add, del }
files[]      per file: commits, add, del, last, authors, recent_commits_7d, is_test
directories[]  aggregated per parent dir (depth 1..3): commits, add, del, files
stems[]      basename groups (foo.go + foo_test.go): members, commits, add, del, test_ratio
cochange[]   pairs of files often changed together: a, b, together, a_total, b_total, jaccard

recent_commits_7d lets you see if churn is concentrated now vs. spread across the window. test_ratio is the share of stem-group commits that hit test files. jaccard is overlap (1.0 = always change together).

How to analyze

Read the JSON and identify clusters. A cluster is a coherent group of files — usually a directory, a stem, or a co-change pair/triangle. For each meaningful cluster, classify it using the heuristics below, and explain why it matters.

Classification heuristics

Signal pattern	Likely classification	What it means
High commits, balanced add/del, multiple authors, sustained over window	Instabil / dåligt kravställd	Koden skrivs om i cykler — kraven eller designen är inte stabila
High commits, mostly + lines, recent burst, 1-2 authors	Under aktiv utveckling	Pågående feature-arbete, förväntat — flagga bara om det varat länge
High commits, small commits (low avg lines), same author repeatedly	Buggig	Många små fixar — symptom på instabil logik eller dålig täckning
Stem-grupp där test_ratio > 0.45	Specifikation flyttar sig	Testerna ändras nästan lika mycket som koden — kraven är inte fastlagda
Co-change-par med jaccard > 0.6	Tät logisk koppling	Två filer som "alltid" ändras ihop — kanske dålig separation eller borde slås ihop
Hela mappen het (>30% av totala commits)	Hotspot-modul	Arkitekturproblem snarare än enskilda filer — hela ansvarsområdet är instabilt
Recent burst (recent_commits_7d är majoriteten) i fil som inte är ny	Akut instabilitet	Något hände nyligen — incident, refaktor, eller problem

Multiple signals stack — a cluster can be both "spec shifting" and "tightly coupled". Say so.

Output format

Don't dump the JSON. Don't list every file. Produce a short narrative report:

# Hotmess: <path> (<since>, <ext>)

<one-line summary: total commits, files, period — and the headline finding>

## Cluster 1: <name>  —  <classification>
**Files:** `a.go`, `b.go`, `c.go`  (X commits combined)
**Signal:** <the specific numbers that triggered the classification — e.g. "test_ratio 0.51, jaccard with state.go 0.75">
**Why it's a problem:** <one or two sentences explaining the consequence>
**Suggested action:** <concrete next step — split, stabilise spec, add tests, refactor coupling, etc.>

## Cluster 2: ...

## Notable individual files
(only if a single file stands out and doesn't belong to a cluster — keep to 2-3 max)

## Co-change couplings worth knowing
(only the top 3-5 jaccard pairs that aren't already covered by clusters above)

Keep it concise — aim for 4-6 clusters max. Skip anything that's clearly normal activity. The goal is signal, not exhaustiveness.

What not to do

• Do not just print the JSON. The user asked for analysis.
• Do not list every file. Group into clusters first.
• Do not classify everything as "active development". That's the trivial answer — only use it when other signals don't apply.
• Do not invent root causes you can't see. If you don't know why a file is churning, say "look at git log for context" — don't speculate about specific bugs.
• Do not over-warn. A small new feature folder with a recent burst is fine; a long-stable file suddenly churning is not.

Why this design

• JSON over table: the LLM needs structured signals it can correlate (test_ratio + jaccard + recent burst) — a flat table forces re-extraction.
• Multiple signal sets: directory aggregation catches modular hotspots; stem grouping catches test/code drift; co-change catches hidden coupling. No single view sees all three.
• Heuristics in the skill, not the script: classification is judgment — keep it in the prompt so it can adapt and combine signals, instead of hardcoding rules in code.
• Excludes merges: merge commits inflate churn without representing real work.