Text Optimize

sonnet 5 modes user-invoked

Quick reference

Field	Value
Command	/brewtools:text-optimize
Input	Free-text prompt, optional depth flag, and file/folder/comma-separated targets
Tools	Read, Write, Edit, Bash, Grep, Glob, Agent, AskUserQuestion
Mutation	Every mode edits files in place after pre-edit snapshot
Output	Edited targets, measured size changes, acceptance verdicts, and evidence paths

What it does

Reduce repetition and wording overhead in instructions or documents while preserving their behavior and protected facts. The skill coordinates one file owner per target, snapshots original bytes before edits, checks the draft mechanically, and applies mode-specific semantic acceptance. A shorter file is not accepted solely because it is shorter.

Use it for agent/skill instructions, rules, README files, and documentation. Numbers, names, examples, negations, scope, paths, versions, flags, and conditions remain protected. Record explicitly authorized factual replacements separately from optimization loss.

Examples

/brewtools:text-optimize -l .claude/rules/project.md
/brewtools:text-optimize -s README.md
/brewtools:text-optimize -d CLAUDE.md
/brewtools:text-optimize -x .claude/agents/domain-expert.md
/brewtools:text-optimize -s README.md,docs/guide.md

Natural-language instructions go after the command. Flags and paths can appear within the prompt; explicit depth flags win. Ambiguous scope receives one scoping question.

Modes and acceptance

Mode	Flag	Transformation	Required review
Light	-l	Minimal cleanup, exact-duplicate D.1 only, no restructuring	Mechanical sub-gate; no semantic agent
Medium	Default or detected	General compression	Zero-loss fact self-check and skill review
Standard	-s	Human-readable compression	Fresh independent review; at least 98% kept/merged
Deep	-d	Dense instruction rewriting with ledgers	Fresh independent review; at least 95%; repair failed gates
Max	-x / --max	Opt-in atomic claims and deep techniques	At least 95% plus mandatory second independent self-QA method

All modes run the mechanical gate. Standard, deep, and max additionally require 100% preservation of numbers, names, negations, and scope qualifiers. A percentage threshold does not authorize removing project-specific obligations. Confirmed loss blocks acceptance.

Without an explicit flag, instruction files can select deep, human-facing docs standard, and unknown content medium. Max requires explicit opt-in through a flag or maximum/extreme-compression intent; it is never silently selected by file type.

Workflow

Original snapshots and safe recovery

A failed check preserves current bytes.

Originals live under <RUN_DIR>/orig/<repo-relative-path>. They remain immutable but readable: writers and reviewers can compare against them, but must not rewrite, delete, or recreate them. Keep the run directory and name it in the report for later user inspection.

The guard’s verify --no-restore reports missing protected tokens while retaining the current file. A mechanical pass alone does not establish semantic equivalence. Missing snapshot/state prevents acceptance.

Full snapshot restoration needs authorization and a previously recorded owned-draft checkpoint matching current bytes. Missing proof or intervening changes causes RESTORE_REFUSED; preserve the file and report the gap. Never create a checkpoint at failure or restore time to bypass this check. Before targeted repair, compare current bytes with the last known owned draft.

Deduplication and verification

Same-file dedup preserves each distinct fact once. Different numbers, conditions, or scope are different facts. Outside light mode, intentional emphasis is limited according to the ruleset. Cross-file dedup belongs to the main coordinator: specify the canonical owner and a summary pointer explicitly. A writer applies only assigned decisions; unassigned redundancies remain suggestions.

Faithful fusions and paraphrases count as kept/merged. Known-fact elisions are recorded as elided-known and count against deep/max’s loss gate. Word drops that distort meaning fail the fact check. Max also uses original-derived questions answered from compressed text only, including a critical-fact sub-gate.

Stop when further cuts threaten protected facts or the selected mode’s stopping rules. Reference compression targets are guidance, not required or guaranteed savings.

Measured results

Report words, bytes, and characters with their counting methods. wc -w, wc -c, and wc -m measure different things. Token counts require a named tokenizer/encoding. Characters divided by four is a rough proxy, never measured tokens or proven savings.

Reports include before/after measurements, change and ratio, semantic match, rule ids, verification verdict, and dedup summary. Full inventories and loss/dedup ledgers belong in report files. The skill accepts only results that pass its mechanical and mode-specific checks; failed runs report exact losses and can recommend a lighter mode.

Related