hassio-addons/.claude/skills/hassio-addon-workflow/references/simplify.md

Simplify — case studies

Evidence for why the mechanism ladder in SKILL.md step 3 exists, and why levels 4-6 need a reason that survives being said out loud. In each case the simpler option existed and was skipped. Being able to build the complicated thing is not a reason to.

• A rejected PR spent a 388-line TCP proxy plus a 142-line monkeypatch of a private upstream method to reclaim 159 MB — placing custom transport code in the path of every API request. Both independent reviewers said close it rather than iterate on it.
• A ~180-line ctypes probe was written to decide whether to enable GPU flags. It worked perfectly, proved the driver was fine, and the change still did nothing, because the question it answered was not the question that mattered.
• A resolution cap shipped as a new init script writing an s6 envdir — the wrong mechanism entirely (ladder level 4). Renaming the option to the env var the service already reads (level 1) would have worked, and the new script did not.
• A calibre-web trusted-ips fix injected the add-on's per-boot IP, which forced a rewrite-every-boot design that erased user entries; preserving them then needed merge logic plus a state file recording what was injected (+34 lines, PR #3009 — closed unmerged). Asking "is there a constant that makes the rewrite unnecessary?" gave the shipped fix: trust the static supervisor range 172.30.32.0/23, one idempotent statement, net −6 lines (PR #3010). Complexity spent working around a changing value is a sign to hunt for the constant instead.
• A .templates/ha_entrypoint.sh fix went to review at 25 lines of code and merged at 10. Two sources of the excess, and neither was caught by the loop: a pure-bash fallback written at implement time for images shipping with-contenv but not s6-dumpenv — reasoned from the two binaries living in different s6 packages, never demonstrated on any real image, and the case it defended would have degraded to the pre-fix behaviour anyway — and a helper function plus a second reset that existed only to serve that fallback. Deleting the fallback deleted all of it. The rest of the review's objections were correct and cost two tokens on an existing line. It took the maintainer asking "is this the simplest way possible?" to run the pass that step 6 now requires.

Checks worth running against your own diff

• Did the diff stay at the ladder level chosen in step 3? If it crept up a level, either justify that out loud or redo it at the level you chose.
• Can this be solved by deleting instead of adding? A flag that shouldn't be passed, a process that shouldn't start, a registration that shouldn't be duplicated. Deleting usually shrinks the regression surface — but not always: the /dev/shm case in references/evidence.md is a removal that reintroduced a crash loop on hosts unlike this one. A removal that depends on a host default still needs the same verification as an addition.
• Is the fix bigger than the thing it fixes? That is a smell, not a rule — but it usually means the problem was framed one level too deep.
• For each defensive branch: what input reaches it, on which image or host? Go and check, the way you would check a measurement. The bar is being able to name the case, not to reproduce it here: Docker's 64 MB /dev/shm default is documented behaviour that HA does not override, so the bullet above keeps that guard even though this host measured 7.7 GB. Nobody could name a single image shipping with-contenv without s6-dumpenv, so that fallback went. If you cannot name the case, delete the branch — the situation then fails the way it already fails today, visibly, instead of through a second path that is never exercised and silently rots as the base images move. Weigh the cost too: a one-flag guard against a crash you cannot rule out is cheap, a second code path that degrades to the pre-fix behaviour anyway is not. Write down in the PR body what you cut and why, so the next person does not re-add it from the same reasoning.
• How does this fail in three years, when the base image, Electron, or upstream has moved? Code that reads a documented knob keeps working. Code that reaches into private internals does not.