Hill-climbing opportunities

# Hill-climbing opportunities

The repository’s reports are instruments, not a backlog and not a quality score. Their job is to reveal
where one coherent improvement could make many later changes safer, faster, or more truthful. A hill is
the underlying constraint; a metric is only a view of its slope.

## Start from independent signals

Do not promote a file because one chart places it at the top. Begin when at least two independent signals
point at the same mechanism, then inspect the contract itself.

| Signal intersection | Likely constraint to inspect | First evidence to read |
| --- | --- | --- |
| High churn + runtime-boundary debt | A module owns work belonging to another runtime role | [Hotspots](../../../generated/HOTSPOTS.md), [boundaries](../../../generated/BOUNDARIES.md), direct callers |
| Incident + an unguarded or untested write path | A failure mode can recur without a durable check | Incident record, canonical write seam, narrow regression test |
| Stale prose + moved implementation | A contributor’s mental model will select the wrong seam | [Staleness](../../../generated/STALENESS.md), the named source, owning hub |
| Large fan-out + repeated coupled changes | A contract is doing too much or lacks a stable adapter | [Quality worklog](../../../generated/QUALITY_WORKLOG.md), [hotspots](../../../generated/HOTSPOTS.md), direct imports |
| Complexity + effect-heavy tests | A deterministic decision is trapped inside I/O, time, randomness, or shared mutation | Largest decision block, direct effects, narrowest test |
| Repeated operational explanation + missing diagnostic | Operators cannot cheaply distinguish a healthy state from a failure | [Fleet operations](../FLEET_OPS.md), logs/diagnostics, the operating command |
| Repeated copy or terminology divergence | Meaning is distributed across implementation instead of a source contract | [Copy and localisation](../../conventions/COPY_AND_LOCALISATION.md), vocabulary, current components |

The generated [quality worklog](../../../generated/QUALITY_WORKLOG.md), produced by
`scripts/gen/quality-worklog.mjs`, is the first-pass intersection for static structure, history, and
knowledge drift. It is deliberately a triage queue, not an instruction to refactor.

## Promote only a falsifiable opportunity

Write the opportunity as a compact hypothesis before changing code:

> **Constraint:** what is making future work expensive or unsafe?
> **Evidence:** which independent signals agree, and what did the implementation confirm?
> **Move:** the smallest whole contract that would change the slope.
> **Proof:** the observable consequence that would distinguish improvement from cosmetic change.

For example, “remove eight boundary edges” is not a useful opportunity. “The client store owns transport
policy, so sync changes cross the client/server seam; extract one transport adapter and prove its callers
no longer import the wrong layer” is. The latter can be wrong, tested, and abandoned if inspection shows
the coupling is intentional.

## Prefer sensor-improving moves

The highest-yield maintenance often leaves the system better able to find its next improvement:

- a regression test turns a past incident into a future guard;
- a `read-*` diagnostic turns a support investigation into a cheap observation;
- a source anchor makes a prose claim measurable for staleness;
- a pure adapter lets a boundary report name a real responsibility leak;
- a canonical copy or vocabulary seam prevents semantic drift from multiplying.

This is internalisation: the next agent should need less inference, fewer broad searches, and less trust in
plausible output to reach the correct decision.

## Use functional design as a maintenance lens

Functional programming is useful here as a way to expose authority and effects, not as a syntax target.
The strongest candidates usually have one of four shapes:

- a deterministic decision is interleaved with I/O, time, randomness, logging, or persistence;
- a transform mutates data owned by its caller or relies on mutable module state;
- several callers encode the same policy with slightly different branches;
- optional fields and booleans permit states a discriminated union could rule out.

The smallest whole move is usually to pass data into a pure decision, return data or a typed result, and
let the existing shell apply effects through the canonical boundary. Preserve readable local mechanics:
a private accumulator that cannot escape is compatible with an immutable contract, and an explicit loop
may communicate a build more clearly than `reduce`. Judge the result by whether effects, ownership, and
invariants became easier to inspect and test—not by the density of functional syntax.

## Do not climb a false hill

Stop when inspection shows any of these:

- the coupling is a deliberate contract with clear callers and a sufficient focused test;
- a historical hotspot reflects a completed migration rather than live pressure;
- a report is counting generated, fixture, or test-only machinery rather than production risk;
- the proposed split merely lowers a metric without removing a responsibility or write path;
- the proposal trades an explicit exhaustive decision for generic indirection, or replaces readable local
  mechanics with a more "functional" spelling but no clearer contract;
- a live incident requires an external recovery decision rather than a code change.

In those cases, record the finding in the handoff and leave the system alone. The standard is not a greener
report. It is one more costly failure, ambiguity, or repeated explanation made less likely.

For an extended cleanup campaign, reassess after every coherent batch. Continue only when the next
candidate still has corroborating evidence and can name a contract-level gain: one fewer effectful seam,
invalid state, repeated policy, ownership ambiguity, or unguarded failure. When the remaining candidates
offer only line-count reduction or subjective stylistic uniformity, the hill has flattened; switch to
opportunistic cleanup alongside feature work.

Raw Markdown source