maintenance-pass

Maintenance Pass

Optimize For Maintenance Yield

Prioritize the safest change with the largest maintenance payoff. Delete or simplify code only when evidence supports it. Refactor only when it materially reduces duplication, clarifies ownership, removes a failed path, or protects an important contract. Do not move code around for aesthetics.

Use this rough ranking:

maintenance yield = impact * confidence * stale_touch_signal / blast_radius

Treat time since last git touch as a triage signal, not proof. The relevant metric is the most recent commit that changed a path, not when the file was created. Code whose latest git touch was a long time ago is more likely to be a vestige, duplicated old path, or stale interface, but stable core infrastructure can also be old and correct.

Start With Evidence

1. Read local repo instructions first: AGENTS.md, CLAUDE.md, README.md, nearby runbooks, and provenance notes tied to the target area.
2. Check the worktree: git status --short --untracked-files=all. Never revert unrelated user changes. Avoid destructive cleanup in a dirty worktree unless the user explicitly scopes it.
3. Establish stable baselines:

git ls-files '*.py' | wc -l
git ls-files '*.py' | xargs wc -l | tail -n 1

1. Build a least-recently-touched candidate list from tracked files before choosing a theme. Prefer files and directories whose most recent git commit touch is old, especially when they are scripts, one-off analyses, retired mechanism code, stale configs, duplicate helpers, or docs for old paths. Use git log -1 --format='%ct %cs %h' -- <path> or the inventory helper's least-recently-touched section. Do not use last-touch age alone to delete stable package owners, tests, schemas, or public APIs.
2. If the user gives a target LOC change, treat it as a stopping target, not a quota. Aim for the target with the safest high-yield changes first, but stop short when the next candidate has weak evidence or excessive blast radius. Do not pad the diff with formatting, moves, or speculative rewrites to hit the number.
3. Establish a pre-pass commit boundary before editing without creating empty commits. If the worktree is clean, record the current HEAD as the starting boundary instead of making an empty checkpoint. If the worktree is dirty, do not silently commit unrelated or user-owned changes; either commit only already-approved scoped changes as a real pre-pass checkpoint, or record the current HEAD plus the dirty status as the boundary. If the user explicitly asks for before/after commits but there is nothing real to checkpoint before the pass, report that the starting boundary is the existing HEAD; do not make an empty commit.
4. Optionally run the bundled inventory helper from the repo root: