"Flag every rule that boxes you in without adding real information, and rewrite the keepers as judgement calls instead of bans." Applied to src/skills and src/agents, which the CLAUDE.md pass never touched.
For comparison, .claude/rules/ has 1 NEVER and 1 MUST in total. The rules directory is already clean. All of the debt is in the skills.
One question per line, and it is not "is this a ban" but "does it carry information the model does not already have".
The ban names the failure that produced it. Deleting it deletes the reason.
Real repo-specific content wearing a ban. Keep the fact, drop the shouting.
General good practice restated as a prohibition. Zero information for Opus 5.
The same file states the rule 135 lines earlier. Verbatim, CONTRIBUTING-SKILLS.md:530:
If you find yourself writing ALWAYS or NEVER in all caps, that's a yellow flag. Today's LLMs are smart, they have good theory of mind and when given a clear explanation of *why* something matters, they go beyond rote instructions. Reframe heavy-handed rules into reasoning
The guidance is already correct and already written down. It was never applied to the boilerplate the same document hands out, which is why the practice never propagated.
- **NEVER `dontAsk`** — it silently REFUSES permission-requiring tools (including Bash), so every analysis returns empty output with no error (#1862 Bug C).
This is the shape to aim for, and it is why blanket conversion would be vandalism. It carries four things a model cannot derive: the specific flag, the mechanism (silently refuses), the observable symptom (empty output, no error), and the incident (#1862 Bug C). The word NEVER is the least important part of the sentence. Leave it exactly as is.
- **NEVER** freehand shadow/gradient/blur values when a recipe exists — that defeats the catalog
- The catalog exists so these values stay consistent across sessions. Freehanding a shadow, gradient or blur that already has a recipe re-introduces the drift the catalog removed, so paste the recipe.
The fact survives (recipes exist, use them). What changes is that the model is told what goes wrong instead of being forbidden, so it can reason about the edge case the ban never anticipated: a value the catalog does not cover.
## CRITICAL: Task Tracking
## Task tracking
CRITICAL: appears 47 times across the tree. When 47 things are critical, none are: the word stops marking priority and becomes visual noise the model learns to skip. Nothing about the section changes if it goes. This is the single highest-count, lowest-risk edit in the whole pass.
| Wave | Scope | Lines | Risk | Why this order |
|---|---|---|---|---|
| A | Fix the template at CONTRIBUTING-SKILLS.md:665, then the 13 copied headers |
~13 | low | Stops the pattern reproducing. Everything after this is finite. |
| B | Drop the CRITICAL: prefix everywhere it is not a log level |
~47 | low | Mechanical, no information can be lost by deleting an adjective. |
| C | Convert the 94 artifact-bearing bans to judgement-voice | ~94 | med | Needs per-line reading. The artifact must survive verbatim. |
| D | Delete bare assertions after confirming each names nothing | ~300 | med | Biggest bucket, but every line needs a human-grade check first. |
A and B are ~60 lines and carry essentially no risk of information loss. C and D are the real work and are where an over-eager sweep would delete wiring, which is exactly the failure mode the first audit's adversarial pass caught when a fabricated finding would have deleted 30 statically wired skills.
| Claim | Honest answer |
|---|---|
| Token savings | Near zero for the index. Skill bodies load only on invoke, and they are not in the always-loaded 5,830-token index. This pass is not a token optimisation and should not be sold as one. |
| Then why do it | Same reason the CLAUDE.md pass paid: a ban with no reason cannot be reasoned about at the edge case, and inflation trains the model to skip emphasis. The measured win is fewer wrong calls in situations the rule never anticipated. |
| Biggest risk | Deleting a line that names non-derivable wiring. Mitigated by doing A and B first, and by requiring that every C/D edit preserves the named artifact verbatim. |
Measured on branch chore/opus5-trim-assessment · 2026-07-28
Companion: index.html (the Opus 5 trim assessment) · plan.md · before-after-exhibits.md