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 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.