Text Optimizer

sonnet 5 modes owned edits only

Quick reference

Field	Value
Agent	brewtools:text-optimizer
Triggers	optimize prompt, reduce tokens, compress
Tools	Read, Write, Edit, Glob, Grep, Bash, WebFetch
Main-session entry	text-optimize
Output	Per-file measured size changes, semantic checks, rule ids, and report path

What it does

Compress text while preserving the facts and behavior that make it useful. The optimizer removes repetition, tightens wording, and applies the selected mode’s transformations. Numbers, names, dates, paths, versions, examples, negations, and scope qualifiers remain protected. Authorized factual replacements are recorded separately from loss.

Use the text-optimize skill to coordinate snapshots and acceptance. The writer owns a bounded file edit; it does not re-delegate, change Git, or accept its own optimization.

When to use

• Tighten agent, skill, or rule instructions without weakening scope or safety conditions.
• Remove accidental duplicate facts within a document.
• Keep README and documentation readable while reducing verbosity.
• Compare compression against an explicit fact inventory and actual size measurements.

Example

/brewtools:text-optimize -s README.md
/brewtools:text-optimize -l .claude/rules/project.md
/brewtools:text-optimize -d .claude/agents/domain-expert.md

The main skill snapshots the original before delegating the file. Expect an edited file and a compact report with measured words/characters, verification evidence, and unresolved losses. An unverified result is not accepted merely because it is shorter.

Modes

Mode	Behavior
Light	Limited cleanup; only exact-duplicate D.1 removal, without restructuring
Medium	General compression with a zero-loss fact self-check
Standard	Human-readable compression and independent semantic review
Deep	Dense instruction compression with explicit ledgers and semantic review
Max	Explicit opt-in only; deep techniques plus atomic claims and two verification methods

Without a flag, LLM instruction files default to deep, human-facing docs to standard, and unknown content to medium. Max is never auto-selected. Prompt-quality rewriting applies only to prompt-shaped content at medium or above, never to light.

Mode targets are guidance, not promised savings. Report this file’s measured result instead of presenting reference-example ratios as its outcome.

Workflow

Snapshots and safe recovery

Original evidence is immutable; current drafts need ownership proof.

The pre-edit original lives under <RUN_DIR>/orig/<repo-relative-path>. Read it for comparison; do not edit, delete, or recreate it. Progress reports are not backups. The writer checkpoints each known owned draft immediately after its edit, including an owned deletion or repair.

The mechanical guard uses verify --no-restore: failures preserve current bytes and print evidence for classification. A mechanical pass cannot prove semantic equivalence. Missing state or snapshots prevents acceptance.

Full restoration requires authorization and an already recorded checkpoint matching current bytes. Missing proof or intervening changes produces RESTORE_REFUSED and leaves the file untouched. Creating a checkpoint at failure or restore time cannot manufacture ownership. Targeted repairs also require checking current bytes against the last known draft.

Semantic acceptance

Mode	Required checks
Every mode	Mechanical sub-gate and skill-owned acceptance
Light	No semantic agent round
Medium	Writer fact self-check plus skill review; zero loss
Standard	Independent fact review; at least 98% kept/merged
Deep	Independent fact review; at least 95%; repair and recheck failed gates
Max	At least 95%, plus mandatory second independent method: original-derived self-QA

Standard, deep, and max also require 100% preservation of numbers, names, negations, and scope qualifiers. Mode percentages never authorize deleting project-specific obligations. Merged duplicate facts and faithful paraphrases count as preserved. Known-fact elisions are ledgered and count as loss; a word drop that distorts a fact fails that fact’s check. Unresolved confirmed loss blocks acceptance rather than shipping with a caveat.

Measurement and reports

Use wc -w for words, wc -c for bytes, and wc -m for characters. These are different measurements. Token counts require a named tokenizer and encoding. Characters divided by four is only a rough proxy; it is not measured tokens or proof of token savings.

The final return is verdict-first and compact: file paths, before/after sizes, counting method, change/ratio, semantic match, rule ids, verification verdict, and dedup summary. Fact inventories, loss/dedup ledgers, and detailed evidence stay in report files. Finished-file checkpoints and progress are recorded as work proceeds so interrupted work can resume from evidence.

Related