mirror of
https://github.com/alexbelgium/hassio-addons.git
synced 2026-08-25 14:23:33 +02:00
3e561a3f9f
* refactor(skill): shorten hassio-addon-workflow via progressive disclosure SKILL.md was 365 lines, loaded in full on every add-on task. Split it per Anthropic's Agent Skills best practices: keep steps, completion criteria, and the mechanism ladder inline; push rationale, war-story examples, and Codex CLI invocation details into reference files loaded only when that branch is taken. - SKILL.md: 365 -> 171 lines. The "ship the simplest solution" rule was stated three times; now once. Steps 3/6/9 keep their load-bearing checklist but point to detail files instead of inlining it. - references/evidence.md (new): measurement methodology, the host-generalization failure examples, the merged-and-inert case studies - references/codex-review.md (new): CLI invocation, prompt guidance, plan-attack checklist - references/simplify.md (new): mechanism-ladder case studies Also replaces the old "Token efficiency" section (which named this maintainer's personal MCP tools - rtk/headroom/tokensave - not guaranteed present for CI agents or other collaborators using the checked-in copy) with a subagent-delegation instruction: Codex's plan/code review and PR-comment triage on >5 threads should run in a subagent that returns a condensed summary, not raw output, into the calling session. * fix(skill): address PR review feedback - SKILL.md: define $SKILL once and state that all scripts/ and references/ shorthand paths are relative to it — they read as repo-root-relative otherwise and don't resolve from an add-on directory - codex-review.md: drop the reference to a "global CLAUDE.md note" that isn't in this repo's CLAUDE.md; describe --sandbox read-only accurately (reads allowed, writes/exec blocked, approvals disabled) instead of "cannot run anything"; add the missing & so the example is actually backgrounded as the prose claims - evidence.md: use smaps_rollup for process RSS — plain smaps prints one Rss: line per mapping (47 for a trivial process here), not a total - simplify.md: drop the absolute "removals cannot regress" claim, which contradicted the /dev/shm case study in evidence.md * refactor(skill): apply independent quality-review findings From an independent model review of the skill against the Agent Skills best-practice guides: - traps.md: CHANGELOG was described as "the only hard gate", contradicting SKILL.md — the HA add-on linter and the image build also block PRs (verified against onpr_check-pr.yaml). Gates list corrected. - codex-review.md: the "attack your own plan" checklist is run by the main agent, but lived in the file whose stated consumer is the delegated subagent — an agent that delegates correctly would never see it. Moved inline into SKILL.md step 3. - SKILL.md: delegation instruction now says exactly what to do (spawn a subagent whose prompt includes references/codex-review.md and follows its invocation) instead of "delegated per the rule above". - SKILL.md: traps.md is no longer mandatory reading on the light path — the light-path facts it holds (versioning, CHANGELOG format) are inline in step 7; it stays required when touching scripts/Dockerfiles/env. - SKILL.md: dropped the bundled-files table (every row already cited at point of use) and the "read the script when you use it" anti-instruction — scripts are run, not read. 177 -> 167 lines. - description: 982 -> 550 chars; removed workflow narrative that does nothing for skill selection and the stale-prone model name, kept all trigger terms. * fix(skill): note that CI hard gates skip on non-addon PRs The three hard gates in onpr_check-pr.yaml (changelog check, addon-linter, check-build) are each matrixed over check-addon-changes.outputs.changedAddons and if:-skipped when it is '[]'. A PR touching only docs, .github/ or .claude/ therefore shows them as "skipping" rather than passing — which should not be read as a green build. Verified against onpr_check-pr.yaml lines 64, 83, 101 and against this PR's own check output.
31 lines
2.0 KiB
Markdown
31 lines
2.0 KiB
Markdown
# 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 all three cases 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.
|
|
|
|
## 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.
|
|
- **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.
|