text-optimize — deep token optimization

Quick reference

Field	Value
Command	/brewtools:text-optimize
Arguments	[-l|-s|-d|-x|--max] [file|folder|path1,path2]
Model	sonnet
Context	session
Tools	Read, Write, Edit, Bash, Grep, Glob, Task, AskUserQuestion

When to use

• Shrink CLAUDE.md — deep mode compresses with a DICT header; LLM-only output, 2-3x reduction
• Clean up agent/skill definitions — medium mode strips filler, converts prose to tables, merges redundant sections
• Prepare user-facing docs — standard mode targets 30-50% compression while staying human-readable
• Light pass on production prompts — -l removes filler and fixes tone; structure untouched, safe to apply without review

Modes

Mode	Flag	Target	Compression	Human-readable	Verification
Light	-l	Any file	Minimal	Yes	Sub-gate only
Medium	(default)	Any file	Moderate	Yes	Self-check (fact inventory)
Standard	-s	Docs, README	30-50%	Yes	1 round (≥98% match)
Deep	-d	CLAUDE.md, system prompts, agent/skill defs, KNOWLEDGE	2-3x	No — LLM-only	1-2 rounds (≥95% match)
Max	-x/--max	CLAUDE.md, system prompts, KNOWLEDGE	3-4x	No — LLM-only	2 mandatory rounds (≥95% + 100% sub-gate)

Auto-detection: when no flag is given, the skill reads the file path and header. CLAUDE.md, .claude/rules/*.md, KNOWLEDGE.* → deep candidate. README.md, docs/ → standard candidate. Ambiguous → asks via AskUserQuestion. Max is never auto-selected — requires an explicit -x/--max flag or an explicit max/extreme compress hint.

Every mode is guarded on disk. Before any file is touched, the skill snapshots each target byte-for-byte into a private run directory under .claude/reports/ — the git tree over the targets must be clean first, or the run refuses. After the optimization pass, a mechanical script diffs the snapshot against the result and checks that every number, version, file path, != prohibition, and ALL-CAPS modal keyword (NEVER, ALWAYS, MUST NOT, REQUIRED, MANDATORY) is still present. A single miss restores the file to its pre-edit bytes and reports exactly what vanished — this applies to every mode, light included, not just standard/deep/max. Standard, deep, and max additionally run an independent semantic gate on top (see Verification in the flow below).

Examples

# Single file, medium mode (default)
/brewtools:text-optimize CLAUDE.md

# Light mode — safe, minimal changes, no restructuring
/brewtools:text-optimize -l .claude/agents/reviewer.md

# Standard mode — 30-50% reduction, stays readable
/brewtools:text-optimize -s README.md

# Deep mode — max compression for CLAUDE.md, review diff after
/brewtools:text-optimize -d CLAUDE.md

# Max mode — 3-4x compression (opt-in)
/brewtools:text-optimize -x CLAUDE.md

# Multiple files in parallel
/brewtools:text-optimize agents/planner.md, agents/executor.md, CLAUDE.md

# All markdown files in a directory
/brewtools:text-optimize -d agents/

Natural language works as arguments after the command — the skill is user-invoked only and never fires on its own: /brewtools:text-optimize compress this for context → deep mode, /brewtools:text-optimize slim down the README → standard mode.

Flow

Delegation

Every spawn prompt carries six fields. A bare one-line task is never enough:

Field	Content
GOAL	cut token cost across the run without losing meaning; this agent owns one file
ROLE	optimize that file in place — no behavior change, no dropped names, numbers, paths, versions, prohibitions
SCOPE	in — the one file; out — every other path, references/ are read-only inputs
CONTEXT	mode already chosen, Phase 1 Explore findings supplied, siblings hold the other files
CONSUMER	the skill merges every Optimization Report into one summary; other files still link to this file’s headings
DONE	dedup pass (D.1-D.6) → transformations → ref checks (R.1-R.3) → mode verification → Optimization Report

The CONSUMER field is what keeps a parallel run coherent: a heading renamed without care breaks a sibling agent’s cross-reference in the same batch.

Rule categories (52 rules)

Category	Rule IDs	Scope
Claude behavior	C.1-C.8	Literal following, avoid “think”, positive framing, match style, descriptive instructions, overengineering, avoid ALL-CAPS, prompt format
Token efficiency	T.1-T.8, T.10	Tables, bullets, one-liners, inline code, abbreviations, filler, comma lists, arrows, strip whitespace
Structure	S.1-S.8	XML tags, imperative, single source, context/motivation, blockquotes, progressive disclosure, consistent terminology, ref depth
Deduplication	D.1-D.6	Exact-duplicate merge, near-duplicate merge (most specific variant wins), cross-format duplicate (prose vs table), emphasis cap ≤2/doc, cross-file dedup (canonical location + pointer), wrong-merge guard
Reference integrity	R.1-R.3	Verify file paths, check URLs, linearize circular refs
Perception	P.1-P.6	Examples near rules, hierarchy, bold keywords, standard symbols, instruction order, default over options
LLM Comprehension	L.1-L.8	Critical info position, documents-first, conciseness, quote-first, add WHY, reiterate constraint, prompt repetition, preserve scope qualifiers
Aggressive lossy	A.1-A.4	Line fusion, low-value word drop, aggressive paraphrase, known-fact elision (deep/max only)

A dedup pass runs in every mode during analysis, before compression. Dedup-merged facts count as preserved: match % = (kept + merged) / total.

Mode-to-rules mapping:

Mode	Applies	Notes
Light	C.1-C.8, T.6, D.1, R.1-R.3, P.1-P.4, L.1-L.8	Text cleanup only — no restructuring
Medium	All rules (C + T + S + D + R + P + L)	Balanced transformations
Standard	All rules + standard-compression.md	30-50% compression, 1 verification round
Deep	All rules + A.1-A.4 + deep-compression.md	DICT header, symbol substitutions, aggressive lossy pass, 1-2 verification rounds
Max	All rules + A.1-A.4 + deep-compression.md + max-compression.md (opt-in)	3-4x compression, 2 mandatory verification rounds + 100% sub-gate