Skip to content

chore(context): cut 7.6K chars of always-on rules - #245

Merged
paveg merged 6 commits into
mainfrom
chore/context-diet-rules
Sep 14, 2026
Merged

paveg merged 6 commits into
mainfrom
chore/context-diet-rules

Conversation

@paveg

@paveg paveg commented Sep 14, 2026

Copy link
Copy Markdown
Owner

Summary

Second pass of the context-diet skill, this time on the always-on rules (the first pass, #244, covered skills and agent definitions). Effective always-on cost, after subtracting what the measure script cannot see (claudeMdExcludes, skillOverrides: off):

Class Before After
rules 26,215 18,613
skill descriptions 6,351 6,351
total chars per turn 32,566 24,964

Rules outweighed skill descriptions 4:1, so descriptions were left alone; the top three would save a few hundred chars for a full verification pass each.

Batches (one commit each, bisectable)

Batch Before After What changed
zero-cost-scaling.md 1,749 0 Orphan. The rule became a skill in #212 but the deployed copy survived because deleting a source only makes chezmoi forget it. Added to .chezmoiremove; the skill body is byte-identical
workflow.md 7,154 3,617 Removed sections that restate development-principles.md, the paths-scoped tdd.md, agent frontmatter, or harness defaults. The 114K-token measurement and every worktree constraint stay verbatim
harness-engineering.md 3,078 1,962 The harness-vs-guardrail taxonomy is maintenance guidance, so it moved to harness-meta.md (paths-scoped to .claude/**). Every constraint survives, reworded
db-safety.md 1,560 1,319 Kept only the judgment the hook cannot make; dropped explanations of hook internals
markdown-formatting.md 2,913 2,027 Rationale paragraphs became one clause per bullet. The "When to diagram" table is unchanged because tests/writing-bench/rubric.md references it by name

Verification

  • just test passes (lint, profile rendering, format, hook and skill-script tests).
  • A skeptic subagent tried to refute the claim that every removed instruction is covered elsewhere. It found one factual regression (the hook description understated the quote/backslash normalization it performs) and two cross-references to a folded-away "Authoring rules" heading. Both are fixed in the last commit.
  • chezmoi apply on this machine removed the orphan and deployed the new rules; chezmoi diff ~/.claude/rules is empty.
  • Behavioral tests in fresh sessions were not run. The named-failure table for each cut lives in the local .ai/ note and is the regression list if something surfaces later.

Deliberately dropped, with no restatement anywhere

The skeptic flagged these five lines from workflow.md as lost. Each was cut on purpose because no concrete failure could be named for it, or because the harness already enforces it. Reviewers who want any of them back should say so here.

  • "Use plan mode for verification steps, not just building"
  • "Write detailed specs upfront to reduce ambiguity"
  • The Demand Elegance re-prompt phrase ("Knowing everything I know now, implement the elegant solution"); the outcome is covered by the Simplicity ladder in development-principles.md
  • "Track multi-step work with the harness Task tools; check in before starting implementation"; plan-mode approval already gates implementation
  • The main session's own model tier ("opus; fable for the hardest"); this is session config, not something the agent acts on

🤖 Generated with Claude Code

paveg and others added 6 commits September 14, 2026 17:54
…targets

The rule was converted to a skill of the same name, but the source deletion
only made chezmoi forget the entry; ~/.claude/rules/zero-cost-scaling.md stayed
deployed and billed 1,749 always-on chars per turn. The skill body is
byte-identical, so nothing is lost. Same gap .chezmoiremove already closes for
the superseded writing skills.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Every removed line had a home elsewhere in the always-on set or in a
deterministically loaded rule:

- "Demand Elegance" and "Systematic Bug Fixing" restate the Simplicity
  ladder and "bug fix = root cause" in development-principles.md; the
  failing-test-first line lives in the paths:-scoped tdd.md, which fires at
  the moment code is edited
- "Task Management" restated harness defaults (task tracking, plan approval);
  the one line with no other home (capture corrections in memory) moved to
  Planning
- The model-tier table duplicated the agent frontmatter and the agent list the
  harness already injects; what the table added that nothing else carries
  (haiku override, advisor limits, sonnet[1m] billing, the
  CLAUDE_CODE_SUBAGENT_MODEL precondition) survives as bullets
- Worktree-location rationale compressed to one clause; the constraint and
  the 114K-token measurement stay verbatim

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
The taxonomy explaining why sections are tagged [Harness] or [Guardrail] is
guidance for maintaining the rule set, not for acting on it. It now lives in
harness-meta.md, which is paths:-scoped to .claude/** and CLAUDE.md, replacing
the cross-reference that pointed back at the preamble. Every constraint in
harness-engineering.md stays; wording is compressed. 3.1K to 2.0K chars.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
… make

The hook enforces the literal patterns; the prose only needs the cases it
cannot see (recovering from transient errors, dynamic construction, false
positives on diagnostics, how to run one deliberately). Same five
constraints, 1.6K to 1.2K chars.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
… rule

The line-break section carried two paragraphs of CommonMark and CJK
rendering rationale per rule; each is now one clause on the bullet it
justifies. The "When to diagram" table stays intact because the
writing-bench rubric references it by name. 2.9K to 2.0K chars.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
Skeptic review of the diet found two regressions: db-safety.md understated
the hook (it normalizes quote/backslash concatenation before matching, per
its own header comment), and gh-pr-body.md plus writing/references/technical.md
still point at a "Authoring rules" heading in markdown-formatting.md that the
compression had folded away. Both restored at a cost of 60 chars.

Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com>
@paveg
paveg merged commit db296b7 into main Sep 14, 2026
12 checks passed
@paveg
paveg deleted the chore/context-diet-rules branch September 14, 2026 10:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant