Husbandry

husbandry

!checklist init ${CLAUDE_SKILL_DIR} --force

Maintenance is the most undervalued and most expensive part of the whole lifecycle: empirically it is 60–80% of a system's total cost. Everything the earlier stages bought — requirements, architecture, tests, process, operations — was really a down-payment on one fact: this thing will be changed, over and over, for years. So the governing mindset of this skill is that software is not a building you finish and walk away from; it is a living thing that needs continuous care, and its long-run value is decided less by the features it shipped with than by how cheaply it can absorb the next change. This skill is the discipline of keeping a system cheaply changeable across its whole life — debt, refactoring, defects, version/dependency evolution, legacy, and retirement — across six gated stages, and it will not advance past a GATE until the checklist tool clears it.

Maintenance is where the agent era bites in a particular way, because the agent's instincts are precisely the ones that make a system un-maintainable over time:

• The agent reaches for the rewrite. "This code is bad, let me rewrite it" is its single most dangerous reflex — it can generate a lot of plausible code fast, and it feels none of the loss of the implicit knowledge, the hard-won edge-case fixes, and the years of bug-patches baked into the old code. A rewrite throws all of that away and almost always costs far more than it looks. Incremental refactoring beats the big rewrite in nearly every case — and the agent must be steered there.
• The agent incurs debt invisibly and never repays it. It takes the cheapest path to a green result, leaving shortcuts behind, and has no instinct to "leave it cleaner than you found it." Debt only added and never paid compounds until the system ossifies.
• The agent refactors without the safety net. Asked to "clean this up," it will change behavior while believing it preserved it — because only a test can tell the difference, and the agent has no felt fear of the silent regression.
• The agent whack-a-moles bugs — it suppresses the symptom that turned the dashboard red rather than chasing the root cause, so the defect recurs.
• The agent rots the docs and then trusts them. It changes code and leaves the doc stale, and the next stateless session reads that stale doc as truth and is actively misled. A wrong doc is worse than no doc.

So the rule that governs this skill is: software is read and changed far more than it is written — optimize for the next change, not this one — and that is a property you must engineer and enforce, because the most prolific maintainer is now an agent that optimizes the opposite way.

Discipline: finish every GATE before the next stage. GATEs are hard — never skip, batch past, or self-certify a stage you have not done. The checklist tool enforces the order; let it. Commands address stages by name.

Read [references/agent-era-shifts.md](references/agent-era-shifts.md) first — it is the heart: what each maintenance practice becomes once the maintainer is something that loves a rewrite, banks debt without a ledger, cannot feel a silent regression, and leaves the docs to rot for its own next session. If $ARGUMENTS is a throwaway you will never touch again, this machinery is overkill — say so. The leanest sufficient care for a system's stage of life is the goal, not maximum ceremony.

Speak the user's language, or the maintenance bargain gets struck blind. This skill commits the user to ongoing trade-offs only they can price: how much debt to carry vs pay down, whether a system is worth maintaining or should be retired, what an API break costs their callers. Read their fluency and gloss a term on first use (technical debt, refactoring vs rewrite, semver, deprecation, characterization test, the strangler-fig pattern, bus factor, EOL). A user who signs off on "we'll carry this debt" or "let's retire it" in words they never parsed has not made the call — and the FRAME, DEBT, and CONTINUITY judgments this skill leans on them for are then hollow.

The reference library

The depth lives in references/. Open each when a stage sends you there — not all upfront. Eight references back the six stages:

• [references/decision-tree.md](references/decision-tree.md) — the engine. Sizing maintenance investment by the system's stage of life, the debt-quadrant router (which debt is fine, which is fatal), the refactor-vs-rewrite decision, the deprecate/EOL router, and the keep-vs-retire call. Open it at the start.
• [references/agent-era-shifts.md](references/agent-era-shifts.md) — the must-be-told reference: how each maintenance practice changes when an agent does the maintaining. Load at the start, re-check at every gate.
• [references/maintenance-types-and-stance.md](references/maintenance-types-and-stance.md) — the four kinds of maintenance (corrective, adaptive, perfective, preventive) and why the big two aren't bug-fixing; the organism mindset; designing for change (readability over cleverness, cohesion/coupling, no over-engineering).
• [references/technical-debt.md](references/technical-debt.md) — Fowler's deliberate/inadvertent × prudent/reckless quadrant, making debt visible and quantified, paying it down on a fixed budget, and why the impulsive big rewrite is the most seductive trap.
• [references/refactoring.md](references/refactoring.md) — behavior-preserving restructuring under a test safety net, the boy-scout small-and-continuous rule, separating refactor commits from feature commits, and characterization tests for code with no tests.
• [references/defect-management.md](references/defect-management.md) — triage by severity, the reproduce-it-with-a-failing-test-first rule, root-cause analysis (5 Whys) over whack-a-mole, and proactive discovery via error monitoring.
• [references/versioning-and-dependencies.md](references/versioning-and-dependencies.md) — semantic versioning, backward compatibility and graceful deprecation with a migration path, and keeping dependencies continuously current instead of hitting an EOL wall.
• [references/knowledge-legacy-and-retirement.md](references/knowledge-legacy-and-retirement.md) — lowering the bus factor, living documentation (stale docs are worse than none), working legacy code with characterization tests, the strangler-fig migration, and planned retirement.

---

STAGE 0 — Frame (fund the care, set the lifecycle stance)

Maintenance investment must match the system's stage of life and worth — 够用就好; a 24/7 revenue system earns continuous debt paydown and living docs, a soon-to-retire internal tool does not. Open [references/decision-tree.md](references/decision-tree.md) and place the system on its life arc — actively growing, steady-state maintenance, legacy (kept alive, little changed), or sunsetting — and size the rigor to that and to blast radius. Internalize the governing fact: **software is read and changed far more than it is written, so every change is judged by the cost of the next change, not just by whether it works now.** That reframes "design for change" from a virtue into the gate: readability over cleverness (the next maintainer is very likely future-you with no memory), high cohesion and low coupling so a change doesn't ripple, and no speculative over-engineering — a structure built for an imagined future is itself future maintenance burden.

Decide the mode: SETUP or AUDIT. SETUP is rare here (a greenfield system you are building maintainability into from day one — wire the practices in). AUDIT is the common case: an existing system whose maintenance health you assess capability by capability (is debt tracked? do refactors have a net? are deps current? are docs live?), with evidence, then fix the gaps — never reporting a practice healthy because it is named rather than running.

GATE — clear before DEBT

1. checklist check frame maintenance-stance-set
2. checklist verify frame

---

STAGE 1 — Debt (make it visible, pay it down, don't rewrite on impulse)

Open [references/technical-debt.md](references/technical-debt.md). Technical debt is the apt metaphor: a shortcut taken for speed is a loan whose principal (the rough code) keeps charging interest (every later change is slower, harder, riskier).

• **Debt is not all bad — but it must be acknowledged.** Fowler's quadrant splits it on deliberate/inadvertent × prudent/reckless. Deliberate-and-prudent debt — knowingly taking a shortcut to hit a deadline, intending to repay — is a legitimate engineering choice. The fatal quadrant is inadvertent-and-reckless: the team doesn't even know it's borrowing. The agent lives in that corner by default.
• Manage debt, don't fantasize about zero. The goal is not a debt-free codebase; it is debt that is visible (logged in a register, quantified by its interest) and paid down on a fixed per-iteration budget — not "when we have time," which never comes. Debt only borrowed, never repaid, compounds until the system is too rigid for anyone to touch.
• Resist the impulsive big rewrite. "It's too messy, let's start over" is the most seductive and most dangerous move — a rewrite is almost always far harder than it looks and discards the implicit knowledge and the thousands of edge-case fixes the old system accreted. Default to incremental refactoring (STAGE 2); reserve a rewrite for a genuinely, documented, exceptional case.

GATE — clear before REFACTOR

1. checklist check debt debt-tracked-and-budgeted
2. checklist check debt no-reckless-rewrite
3. checklist verify debt

---

STAGE 2 — Refactor (improve structure without a behavior change — under a net)

Open [references/refactoring.md](references/refactoring.md). Refactoring is, by definition, improving internal structure without changing external behavior. Two iron rules and a commit discipline:

• Refactoring requires a test safety net. Without tests proving behavior is unchanged, you are not refactoring — you are rewriting blind and hoping. Tests are the safety net that makes refactoring possible (the assay skill designs them); for legacy code that has none, write characterization tests that pin current behavior first, then change. This is the gate the agent most needs, because it cannot feel the regression a missing test would have caught.
• "Behavior-preserving" includes the error path and side-effect ordering — not just equal outputs. The dangerous refactor is the one that's identical on the happy path and different when something fails: reorder a side-effect relative to a state mutation — refund() then set_cancelled() vs the reverse — and the outputs match every green test, but when the refund throws, one version leaves the order recoverable and the other strands it cancelled-but-unrefunded. The order of a side-effect relative to a state change is behavior, not style. So the net must pin the failure path, and "I just cleaned it up" is not evidence it was preserved.
• Small and continuous, not a big-bang refactor. Follow the boy-scout rule — leave each piece of code a little cleaner than you found it — instead of hoarding a giant risky restructuring. Small steps stay reviewable and reversible.
• Separate refactoring commits from feature commits — and treat "顺手 / while I was here" as a trigger. Never mix "I changed the structure" with "I changed the behavior" in one diff, or a regression can't be attributed and review can't tell what actually changed. The narration that a change was incidental cleanup is precisely the cue to diff behavior, not trust the label — and if a "refactor" can't be cleanly split from its behavior change, it was never a pure refactor.

GATE — clear before DEFECTS

1. checklist check refactor refactor-under-test
2. checklist check refactor small-and-separated
3. checklist verify refactor

---

STAGE 3 — Defects (triage, reproduce, fix the root — not the symptom)

Open [references/defect-management.md](references/defect-management.md). Bug-fixing is only one slice of maintenance, but it has its own discipline that an agent skips by default.

• Triage, don't fix first-come-first-served. Sort incoming defects by severity and priority; spend the fix effort where the impact and risk are, and record an explicit won't-fix the way the rest of the suite records a deliberate skip.
• **Reproduce every bug with a failing test first.** Before fixing, write a test that fails on the buggy code — it confirms you understood the bug, proves the fix works, and stands as a regression guard forever (the same fail-first discipline the assay skill enforces).
• Chase the root cause; don't play whack-a-mole. Use a method like the 5 Whys to reach the underlying cause. Suppressing the symptom — the agent's cheapest path to a green dashboard — leaves the real fault in place to recur. A bug "fixed" without a root cause is a bug deferred.
• Find defects proactively, not only when a user reports them: wire the error monitoring and observability from the stationkeeping skill back into the maintenance loop so production failures surface as tracked defects.

GATE — clear before EVOLVE

1. checklist check defects triage-and-regression-first
2. checklist check defects root-cause-fixed
3. checklist verify defects

---

STAGE 4 — Evolve (change versions, APIs, and dependencies without breaking the world)

Open [references/versioning-and-dependencies.md](references/versioning-and-dependencies.md). A living system's interfaces and dependencies must change without stranding the people and code that depend on them.

• Communicate compatibility with semantic versioning (major.minor.patch): a breaking change is a major bump, and the version number itself tells a consumer what upgrading will cost.
• Keep public APIs backward-compatible, and deprecate gracefully. Don't delete an interface out from under its callers. To remove something, deprecate it with a transition window and a migration path, then remove it later — a sudden break is the agent's default move because it has no felt obligation to callers it can't see.
• Upgrade dependencies continuously, in small steps. Frequent small bumps (backed by the test suite, a chore an agent does well) are far cheaper than a deferred giant upgrade — and never let a load-bearing framework sit untouched until it reaches EOL (end-of-life, no more security support) and forces an expensive emergency migration. Dependency currency is a continuous tax, not a someday project.

GATE — clear before CONTINUITY

1. checklist check evolve versioning-and-compatibility
2. checklist check evolve dependencies-kept-current
3. checklist verify evolve

---

STAGE 5 — Continuity (keep the knowledge alive, handle legacy, retire on purpose)

Open [references/knowledge-legacy-and-retirement.md](references/knowledge-legacy-and-retirement.md). A system outlives the people and sessions that built it; its knowledge and its end-of-life must be managed deliberately.

• Lower the bus factor. Turnover (of people, and of stateless agent sessions) is the norm, so a system's knowledge must not live in one head. Pairing, rotation, ADRs, and docs spread it — and for an agent with no memory between sessions, the externalized artifacts are the only continuity there is.
• Keep documentation alive — stale docs are worse than none. Out-of-date docs actively mislead the next maintainer (very often the next agent session, which trusts them as truth), so the aim is lightweight, living documentation kept in sync with the system, not a comprehensive manual that rots.
• Work legacy code safely. For a valuable system with no tests and an old stack: pin current behavior with characterization tests be

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: IamK77
• Source: IamK77/Skill
• License: Apache-2.0
• Homepage: https://www.npmjs.com/package/@iamk77/skill-checklist

Install and usage instructions live in the source repository linked above.