plumb

plumb

!checklist init ${CLAUDE_SKILL_DIR} --force

The goal of good code is not "it runs" — it is staying cheap to read and change, which is the same as managing complexity. That picks up the number the husbandry skill leaves you with: maintenance is 60–80% of cost, and nearly all of it is spent reading and changing code. So the one sentence under everything here is the oldest one in the craft: code is written for humans to read, and only incidentally for a machine to run. Every technique below — naming, function shape, abstraction, the trust-chain discipline, smell-hunting — serves legibility and changeability, nothing else. This skill is the plumb line you hold against code to see whether it is true: it audits code for craft (and guides you to write it craft-grade) across six gated stages, and it will not advance past a GATE until the checklist tool clears it.

One stance first, because it governs every judgment downstream: these are guidance, not dogma. Clean Code, SOLID, the design patterns — each has supporters and critics, and over-applying any one of them is its own defect. The craft is judgment, not rule-recitation: the test for every technique is always the same — does this make the code clearer and cheaper to change, or just more rule-compliant? A codebase contorted to satisfy SOLID, or drowned in patterns it didn't need, is worse than the plain version it replaced. This is the suite's recurring "X is a means, not an end," aimed at code itself.

Craft is where the agent era bites in a quiet, compounding way:

• The agent writes clever, not clear. It produces plausible, dense, "elegant" code by default — and feels no cost reading it back, because it re-reads anything instantly. So nothing in its instinct steers toward the boring, obvious version the next reader needs. Boring is the goal: simple, clear, predictable, legible at a glance — not clever.
• The agent is now the next reader. The default reader of this code is a fresh agent session (or future-you) with no context — only the source and the docs. Cleverness, a vague name, a stale comment, a sprawling function each tax that reader directly, and the agent that wrote them felt none of it.
• The agent over-abstracts and under-names. It reaches for a premature abstraction, a pattern, a SOLID-shaped split because it pattern-matches "good engineering" — and names things data, handle, process, tmp because a precise name earns no green. Both make the code harder to read while looking sophisticated.
• The agent leaves the trust-chain escape hatches. Any, cast, isinstance, getattr (and their cross-language family) are where a static guarantee the tool could have proven gets downgraded to "trust me" or "decide at runtime" — and the agent scatters them through core logic because each one makes the immediate thing work. They are its tells.

So the rule that governs this skill: optimize for the next reader, not the machine and not your own cleverness — and prove craft by judgment, not by rule-compliance.

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 craft practice becomes once the code is written by something that writes clever-not-clear, over-abstracts, names vaguely, and reads its own output back for free. If $ARGUMENTS is a genuine throwaway, this machinery is overkill — say so; the craft bar is sized to how long the code must stay legible.

Speak the user's language. Craft judgments are trade-offs the user often owns (is this abstraction worth it, is this clever line acceptable here, is this debt we accept). Read their fluency and gloss a term on first use (code smell, DRY/AHA, SOLID, a design pattern, parse-don't-validate, primitive obsession). A craft "finding" the user can't evaluate is a style opinion imposed, not a judgment shared.