On this page
- What does declining code health look like?
- How to detect a code health trend
- Which signals predict a decline?
- Hotspot health falling
- The worst file in a module
- Untested hotspots
- How should you alert on a decline?
- A monthly review that turns the trend into work
- What a 90-day decline looks like
- Why this matters for AI-assisted development
- FAQ
To spot declining code health early, record a health score for every file on each release or update and alert on the slope, not the level: a fall of 0.5 or more against five snapshots back, or three falls in a row. A single bad score is a known problem. A score that keeps falling in code people keep changing is the one that becomes an incident.
Part of the code health guide. The full model is in the complete code-health guide.
What does declining code health look like?
Declining code health is a downward series of scores, not a low score. Teams feel it as "everything takes longer" before any test fails. The shape of the series tells you what to do:
| Pattern | What it means | Response |
|---|---|---|
| Flat and low | A known ugly area that is stable | Leave it, unless you must change it |
| Slow decline | Structure is worsening under active change | The early-warning case: act now |
| Sharp drop after a feature burst | New work landed without cleanup | Review that change set |
| Volatile | Repeated redesign or ownership churn | Settle ownership before refactoring |
Scroll the table sideways to see every column.
Four axes make a decline actionable: the level of the score, its slope over snapshots, its breadth (how many files or modules) and its exposure (how many files depend on it). A declining file with no dependents can wait. One on the main request path cannot.
Hotspot-based methods keep showing up in this research for a reason: change concentrates in a few files. CodeScene defines hotspots as the most frequently modified files and pairs them with code health to rank improvement work, and it alerts on "declining code health" and "predicted decline" in the same spirit as below. The 2024 systematic literature review on technical debt forecasting by Ajibode, Apedo and Ajibode finds the field still young, with random forests and temporal convolutional networks performing best among the studied methods. The practical move needs no model: compare snapshots you already have.
How to detect a code health trend
Take a snapshot of per-file scores on every init, update or release, then compare each file against its own recent past. repowise does this for you. Every repowise init, repowise update and repowise health --recompute stores a snapshot (the last 50 per repository), and three alerts run over them:
| Alert | Fires when | Use it for |
|---|---|---|
| Declining | The score fell 0.5 or more against five snapshots back | Steady drift |
| Predicted decline | Three falls in a row | The early warning |
| History drag | Either of the above, but only the git-history half of the score moved | Telling churn from code you can act on |
Scroll the table sideways to see every column.
The last one matters. A file's score combines what the code looks like with how it has been changing, and history only amplifies code risk. History drag marks the declines where the code itself did not get worse, so there is nothing to refactor and you can skip it. Details are in the code health layer doc.
repowise update # stores a new snapshot
repowise health --trend # prints the last 10
Agents read the same series through the get_health MCP tool with include=["trend"]. With no arguments it returns a dashboard led by one ranked queue of what to fix first.
Which signals predict a decline?
Three signals predict trouble best: a falling hotspot, a worst file that keeps worsening, and a hotspot with no tests. Each comes from data you already have, and the best alerts need two of them to agree.
Hotspot health falling
A hotspot is a file that changes often and is already hard to understand. When its score falls for several snapshots running, maintenance cost is accumulating where you spend the most time. Watch for churn rising while complexity stays flat, the same file appearing in PRs from different engineers, and the file gaining dependents without a cleanup pass. repowise lists hotspots with change frequency, bug-fix counts, bus factor and trend for each file on its code health page.
The worst file in a module
The lowest-scoring file in a module is usually the canary. If it is falling faster than the module average, treat that as a leading indicator even while the average still looks fine. Track the bottom 10% per module and the count of files crossing below your threshold each month.
Untested hotspots
A hotspot with weak tests costs more than the same hotspot with strong coverage, and it declines more quietly. repowise's untested_hotspot marker runs even without a coverage report, and repowise coverage add coverage.lcov adds the line-level view (LCOV, Cobertura, Clover, JaCoCo, Go coverprofile). The chart below plots every instrumented file by health and coverage: the bottom-left quadrant is code scored as weak with no test watching it.
How should you alert on a decline?
Alert on direction and exposure, and require the trend to repeat. A threshold says a file is bad. A trend alert says it is getting bad.
- Slope alert: a drop of 0.5 or more over five snapshots, or three falls in a row (repowise's two built-in alerts).
- Rank alert: a file enters your worst decile or falls below its module median.
- Exposure alert: the declining file has many dependents or sits on a critical path.
get_contextandget_riskshow the dependents and the change history around a file.
Two rules keep the list short: ignore files with no recent commits, and escalate only when a decline coincides with stagnant tests or a large dependent set. For pull requests, get_change_risk returns a health_delta listing the findings a change introduced, worsened and resolved, so a decline is caught in review instead of next month.
A monthly review that turns the trend into work
Use the same six-step review every month; consistency is what makes a trend real.
- List the modules whose health fell the most in the last 30 days (
repowise health --trend). - Check whether churn is concentrating in fewer files.
- Open the bottom ten files and look for repeated edits, branching and missing tests.
- Mark declining files that sit upstream of many dependents.
- Compare with last month's action list. Files still red mean the fix was too small.
- Pick one cleanup per module.
repowise health --refactoring-targetsprints the stored queue, ranked by impact per effort.
| Module | Trend | Hotspot | Tests | Dependents | Action |
|---|---|---|---|---|---|
| auth | falling | yes | low | high | split validator, add tests |
| billing | flat | yes | medium | high | leave alone |
| jobs | falling | no | low | medium | inspect coupling |
| docs | rising | no | high | low | none |
Scroll the table sideways to see every column.
What a 90-day decline looks like
The decline is local for the first month and structural by the third. In days 0 to 30 the module looks fine on average while one hotspot is already low. In days 31 to 60 that hotspot lands in three PRs, churn rises, its score slips and tests stay flat, but the module average barely moves. By days 61 to 90 a neighbour in the same dependency cluster starts to slide and bug fixes appear in adjacent code.
A predicted-decline alert fires in the second window, when the fix is still one file. You can explore this on a public codebase: the FastAPI code health view shows hotspots and per-file scores for a real repository.
Why this matters for AI-assisted development
Agents raise the rate of change, so they raise the rate at which unhealthy code gets touched. An agent needs more than file text to avoid making a falling hotspot worse: change history, dependents, decision records and risk. repowise serves these through ten MCP tools. Before editing, get_risk reports the file's history and reach, and after editing, get_health(targets=[...]) shows whether the file got healthier or worse.
FAQ
- What is declining code health?
- It is a downward trend in maintainability and defect-risk signals over time. A codebase can compile and pass tests while its health declines. The early signs are rising churn, growing hotspot concentration, more complex edits and weak tests in critical areas.
- How do I detect a code health trend early?
- Store a score snapshot per release or update and compare slope, not level. In repowise, a decline alert fires when a file falls 0.5 or more against five snapshots back, and a predicted decline fires after three falls in a row.
- What is code regression detection in practice?
- It is flagging structural backsliding, not only failing tests: a file that becomes harder to change, a module that gathers hidden coupling, or a hotspot whose score drops after each PR. Per-PR tools such as
get_change_riskreport the findings a change introduced or worsened. - Can code quality monitoring predict a decline?
- Yes, when it watches direction as well as thresholds. A threshold says "bad"; three consecutive falls say "getting worse", which is enough to act on before the team feels it. Forecasting research supports the direction, though the literature is still small.
- What is history drag?
- It is a decline where only the git-history half of the score moved, so the code itself did not worsen. repowise labels these so you do not refactor a file that merely changed often.
- How often should I review code health?
- Monthly suits most teams, and weekly suits fast-moving systems. A fixed interval lets you compare slopes instead of snapshots.
