Packs / Bitter Pill Audit
Bitter Pill Audit
Skillv1.0.0Audits a CLAUDE.md or instructions file for redundant, vague and contradictory rules with keep / cut / sharpen verdicts and token estimates.
Install
# once per machine curl -fsSL https://hookcrate.com/install | bash # then hookcrate install bitter-pill-audit
Get access
One license covers all packs.
What it does
Every rule in an instructions file competes for the model's attention. This skill reads a CLAUDE.md (or any system-prompt-style file), splits it into individual rules, and scores each for vagueness (hedge words, no observable behaviour), redundancy (near-duplicate of another rule), default behaviour (a capable model already does this), and contradiction. audit.ts produces the mechanical pass — rule table, token estimate per rule, projected savings — and SKILL.md guides the judgement pass where Claude decides KEEP / CUT / SHARPEN / MERGE and rewrites the sharpened ones.
Usage: bun .claude/skills/bitter-pill-audit/scripts/audit.ts CLAUDE.md
When to use this
Use Bitter Pill Audit when your CLAUDE.md has grown past the point where you can hold it in your head — typically somewhere between 100 and 300 lines — and the agent has started ignoring parts of it. Instruction files accrete: every incident adds a rule, nobody removes one, and after a few months the file contains rules the model already follows, rules that say the same thing twice, and at least one pair that contradict each other. Each rule competes for the model's attention; the vague ones dilute the sharp ones. The skill runs a mechanical pass first — audit.ts splits the file into individual rules, estimates tokens per rule, and flags hedge words, default behaviour, near-duplicates and conflicting always/never pairs — then a judgement pass where each rule gets a KEEP, CUT, SHARPEN or MERGE verdict and the sharpened ones are rewritten shorter. Run it quarterly, after onboarding a new team member who inherited the file, or whenever a rule you care about stops being followed. It is read-only by design: the proposed file is shown, the original is never overwritten without a separate instruction. Expect to cut a third to a half of most files that have never been audited.
When it triggers
- User asks to audit, trim, clean up, simplify or review a CLAUDE.md, system prompt, AGENTS.md or rules file
- User invokes /bitter-pill-audit <file>
Preview — a sample session
Illustrative transcript showing the pack in use.
User: My CLAUDE.md has grown to 300 lines and Claude seems to ignore half of it. Audit it.
Claude: Running the mechanical pass first, then judging each rule against the five questions.
● Bash(bun .claude/skills/bitter-pill-audit/scripts/audit.ts CLAUDE.md)
⎿ # Bitter Pill audit (mechanical pass): CLAUDE.md
Rules: 87 Tokens: ~2140 → ~1180 if suggestions applied (−45%)
Suggested: KEEP 31 · CUT 19 · SHARPEN 28 · MERGE 9
| # | line | section | rule | tokens | flags | suggested |
| 3 | 9 | Principles | Always write clean, maintainable code following best practices | 16 | default vague | CUT |
| 7 | 15 | Principles | Be careful and think step by step before making changes | 14 | default | CUT |
| 12 | 24 | Tooling | Use bun, never npm or npx | 7 | - | KEEP |
| 13 | 25 | Tooling | Prefer bun over npm where possible | 8 | vague dup:12 | MERGE |
| 41 | 88 | Testing | Make sure tests are run appropriately before finishing | 12 | vague | SHARPEN |
| 42 | 89 | Testing | Never claim a task is done without running the test suite | 13 | - | KEEP |
| 58 | 131 | Git | Always commit directly to main | 7 | conflict?:61 | SHARPEN |
| 61 | 137 | Git | Never commit to main without a PR | 9 | conflict?:58 | SHARPEN |
…Claude: Judgement pass on the flagged ones:
- #3, #7 — a capable model already does both. CUT.
- #12 + #13 — same rule twice, the second hedged. MERGE into #12.
- #41 + #42 — #42 is the sharp version; #41 adds nothing. CUT #41, KEEP #42.
- #58 vs #61 — a real contradiction: one section says commit to main, another forbids it. Reading the context: #58 sits under "Personal repos", #61 under "Work repos". RESOLVE by scoping both:
Personal repos (~/code/me/*): commit to main directly. Work repos: branch + PR, never main. - 14 more SHARPEN rules rewritten as
TRIGGER: DO — not THATlines; each rewrite is shorter than the original.
# Audit: CLAUDE.md
Rules: 87 Tokens: ~2140 → ~1050 (−51%)
Verdicts: KEEP 34 · CUT 27 · SHARPEN 18 · MERGE 8
## Proposed file
(rewritten, 141 lines)Claude: The proposed file is in my reply above — I have not touched CLAUDE.md. The two changes with the biggest effect: resolving the main-branch contradiction (Claude was picking one at random) and cutting 27 rules that restated default behaviour and diluted the 34 that matter. Say the word and I'll write it in.
FAQ
Why would cutting rules make the agent follow the rest better?
Attention is finite. A rule that restates default behaviour or hedges with "where appropriate" still costs tokens and focus, and when two rules conflict the model picks one at random. Fewer, sharper rules get followed more reliably.
How accurate is the token estimate?
It uses roughly four characters per token, which is within about 10% for English prose. The number is for comparing before and after, not for billing.
Will it rewrite my file?
Not unless you ask. The skill produces a report and a proposed file in the reply and stops. Your instructions file is your written content; applying the changes is a separate, explicit step.