Text & File Optimizer

Prompt contract

Position 1 of $ARGUMENTS is a free-form prompt (RU/EN) -- depth flags and paths are optional and may follow in any order. Nobody types keys: resolve the depth (mode) + scope FROM the prompt. The depth flags (-l/-s/-d/-x) ARE this skill's modes -- see the keyword-annotated Modes table below.

1. Strip flags (-l, -s, -d, -x, --light, --standard, --deep, --max). An explicit flag anywhere wins outright, no scoring.
2. Else score depths by distinct whole-word keyword hits (Modes table below / Context Hints table). Highest unique score wins; tie -> the keyword appearing first; all zero -> medium (Smart Auto-Detection then still applies file-type heuristics on top).
3. Empty arguments -> medium, or Smart Auto-Detection's per-file-type candidate when the input is an LLM-only or user-facing doc path; ask ONE scoping AskUserQuestion only when auto-detection is ambiguous (already Smart Auto-Detection step 4).
4. --max is opt-in only -- never auto-selected without an explicit -x/--max flag or an explicit maximum/extreme compress hint (unchanged rule, restated here for the contract).
5. Prose that is not a flag/depth keyword is still input: extract the target path(s) from it, never treat the first word of a sentence as a positional path.

Then print this block ONCE, before the first action:

PLAN — brewtools:text-optimize
INPUT:  <arguments verbatim, or "(empty)">
MODE:   <resolved depth> — <explicit flag | matched keyword: X | auto-detected | default>
SCOPE:  <resolved target paths, resolved depth>
DO:     <2-5 imperative bullets>
RESULT: <what the user ends up holding>

Labels are literal; values follow the conversation language. SCOPE MUST name the resolved target paths and the resolved depth. Print it once mode + target files are resolved (end of Input Parsing below), before Phase 1 Analysis spawns.

Step 0: Load Rules

REQUIRED: Read references/rules-review.md before ANY optimization. If file not found -> ERROR + STOP. Do not proceed without rules reference.

Modes

Parse $ARGUMENTS: -l/--light | -s/--standard | -d/--deep | -x/--max | no flag -> medium (default) or auto-detect.

Loss Budget per Mode

Content essence is untouchable at light/medium/standard; small deliberate loss is allowed only at deep/max — explicitly reported. Dedup-merged facts count as preserved, never as loss. Every mode mutates in place, so every mode goes through Phase 0 snapshot and the Phase 3 sub-gate.

The 100% sub-gate is a REFUSAL, not a warning: a sub-gate failure restores the snapshot and leaves the file at its pre-edit bytes (Phase 0/Phase 3 below). The >= 95% budget covers ordinary wording loss; a lost number, path, version, name, negation or scope qualifier is never inside that budget in any mode.

Smart Auto-Detection

When no flag provided AND input suggests compression (not just optimization):

1. Parse file path + content header
2. Classify:
   • LLM-only files (CLAUDE.md, .claude/rules/*.md, .claude/agents/*.md, .claude/skills/**/SKILL.md, KNOWLEDGE.*, system prompts) → deep candidate
   • README.md, docs/, API references, user-facing docs → standard candidate
   • Unknown / mixed → ask user via AskUserQuestion
3. If confident → tell user: "Selected mode: {mode} for {file} because {reason}"
4. If ambiguous → AskUserQuestion with mode options
5. User can override via flags regardless of auto-detection
6. Max is opt-in only — NEVER auto-selected without an explicit -x/--max flag or an explicit maximum/extreme compress hint

Context Hints from Prompt Text

Rule ID Quick Reference

Full per-ID definitions live in references/rules-review.md (loaded at Step 0) — do not restate them here.

Mode-to-Rules Mapping

D.5 (cross-file dedup) applies in ANY mode when processing multiple files or a folder. D.6 wrong-merge guard is mandatory wherever D.2/D.3/D.5 run. PQ (prompt-quality rewrite) applies at Medium mode and above, only when content type is a prompt-shaped target (system prompt/CLAUDE.md/agent def/skill doc) — never Light, never generic docs/README.

D.5 is decided by the orchestrator, never by a per-file agent

A per-file agent sees one file, so two agents can each judge the same fact redundant "because the other file keeps it" and delete it from both — and both report it merged, which counts as preserved, so no per-file gate can see the loss. D.5 therefore belongs to the skill, which already merges every report:

1. After Phase 1, the skill builds ONE cross-file duplicate list from the Explore findings: for each fact appearing in 2+ targets, name the SINGLE owning file and the pointer text every other file gets.
2. That list ships inside each Phase 2 spawn brief as a dedup decision list — the agent EXECUTES its own rows and makes no cross-file dedup judgement of its own.
3. A row absent from the list means "keep the fact where it is". An agent that believes a fact is cross-file redundant reports it to the skill and leaves the text alone.
4. Apply D.6 while BUILDING the list: differing scope/numbers/conditions are different facts.

Deduplication Pass (All Modes)

Runs during analysis, BEFORE compression:

1. Build fact inventory: one atomic fact per line, numbered
2. Flag facts appearing 2+ times (exact, reworded, or cross-format)
3. Classify each repeat: intentional emphasis (marked critical/blockquote, or start+end sandwich) vs accidental (everything else)
4. Accidental -> merge to single MOST SPECIFIC statement (D.1-D.3), best position wins
5. Intentional -> cap at 2: full form early + <=1-line echo at END (D.4)
6. Wrong-merge guard (D.6): differing scope/numbers/conditions = NOT duplicates — keep both
7. Deep/max: record merges in dedup ledger (kept <- dropped) for verification

Usage Examples

File Processing

Input Parsing

Once the target files and depth are resolved above, print the Prompt contract PLAN block now (SCOPE names the resolved paths + resolved depth), before Phase 1 Analysis spawns below.

Phased Execution

Orchestration: Phase 0-3 are executed by the SKILL in the main conversation (manager level). The text-optimizer agent handles single-file optimization only — it cannot spawn sub-agents, so it is never the gate on its own work.

Phase 0: Preconditions + Snapshot (MANDATORY, before ANY edit)

Every mode rewrites files IN PLACE. Preservation must live on DISK, not in a context window a compaction can drop. Before the first Phase 2 spawn, EXECUTE using Bash tool:

bash "$CLAUDE_PLUGIN_ROOT/skills/text-optimize/scripts/text-guard.sh" snapshot <file>... \
  && echo "✅" || echo "❌ FAILED"

STOP if ❌ — fix before continuing. Nothing is edited until this prints a RUN_DIR.

Capture the printed RUN_DIR: — Phase 3 needs it, and it is the same run directory the agents append their checkpoint report to. Exit codes: 0 ok, 2 usage/state error, 3 precondition refused (nothing written).

Delegation

A big task handed to one agent = an agent gone for an hour: you cannot observe it, cannot correct it, and it usually drifts off-target. One subagent = ONE bounded unit — ONE file, ~<=10 steps. A folder or multi-path run MUST be split one-file-per-agent, all spawned in ONE message.

Every spawn prompt MUST carry:

A bare one-line task is never enough.

Phase 1: Analysis — Parallel Explore agents

Task(subagent_type: "Explore", prompt: "Analyze {file}: structure, dependencies, cross-refs, redundancies")

Phase 2: Optimization — Parallel text-optimizer agents, full brief shape:

Task(subagent_type: "text-optimizer", prompt: "
GOAL: cutting token cost across {N} files for this repo without losing meaning; you own
  {file} only, sibling agents own the rest and the reports are merged.
ROLE: optimize {file} in place. Do NOT touch any other file, do NOT change behavior,
  do NOT drop project-specific names, numbers, paths, versions or prohibitions.
SCOPE: in — {file}. Out — every other path; references/ are read-only inputs.
CONTEXT: mode={mode} is already chosen (loss budget per the mode table); Phase 1 Explore
  already analyzed {file} — findings: {cross-refs, redundancies}, so do not re-analyze.
  Sibling agents are optimizing the other {N-1} files of this run at the same time; rule and
  compression references come from your agent definition Step 0/Step 2 (${CLAUDE_PLUGIN_ROOT}
  is natively substituted at spawn).
  A pre-edit snapshot of {file} is already on disk at {RUN_DIR}/orig/ — never read, write or
  delete anything under {RUN_DIR}/orig/, and never re-run text-guard.sh yourself.
  D.5 cross-file dedup is NOT yours to judge. Your dedup decision list is exactly:
  {rows, or "none — keep every cross-file fact where it is"}. Execute those rows and nothing
  more; a cross-file redundancy you spot goes into your report as a suggestion, not an edit.
CONSUMER: the skill merges every agent's Optimization Report into one summary for the user;
  {file} itself is consumed by an LLM loading it as a prompt/doc, and other files still point
  at its headings — a heading you rename must stay resolvable or you break a sibling's file.
DONE: run the dedup pass (D.1-D.6) before compressing, apply transformations, verify refs
  (R.1-R.3), run the mode's verification protocol, then output the Optimization Report
  (metrics table + rules applied + fact-inventory result + semantic match %).
")

Spawn parallel: For multiple files, spawn ALL agents in ONE message for speed.

Phase 3: Independent Verify (MANDATORY, skill-owned, after EVERY Phase 2 return)

The agent that wrote the compression is never its own gate. Phase 3 runs in the skill, which has Task, and compares disk against disk — both sides survive a compaction.

Step 1 — mechanical sub-gate. EXECUTE using Bash tool, once per run:

bash "$CLAUDE_PLUGIN_ROOT/skills/text-optimize/scripts/text-guard.sh" verify --run-dir <RUN_DIR> <file>...

Exit 0 = every number, version, path, != prohibition and ALL-CAPS modal keyword in the original is still present, and the optimized file is kept. Exit 1 = at least one is gone: the script has ALREADY restored those files to their pre-edit bytes and printed the missing tokens. Restoration is the outcome, not a warning — report the missing tokens to the user and offer a re-run at a lighter mode. Exit 2 means no snapshot exists, i.e. Phase 0 was skipped: STOP, do not accept the result.

Step 2 — semantic gate, one fresh agent per file that passed Step 1 (spawn all in ONE message):

Task(subagent_type: "general-purpose", prompt: "
GOAL: independently gate a lossy rewrite before it is accepted; you did NOT write it.
ROLE: verifier. Read only. Do NOT edit, patch or improve either file.
SCOPE: in — ORIGINAL {RUN_DIR}/orig/{rel} and CURRENT {file}, both read from disk. Out —
  every other path; do not read the optimizer's report, it is the thing under test.
CONTEXT: mode={mode}, gate {>=98% standard | >=95% deep/max} plus a 100% sub-gate on numbers,
  names, negations and scope qualifiers. Merged duplicates and A.1/A.3 rewrites count as kept;
  A.4 `elided-known` counts as loss.
CONSUMER: the skill, which restores the ORIGINAL over {file} on your FAIL.
DONE: numbered atomic-fact inventory from ORIGINAL, each labelled kept/merged/lost/distorted,
  match %, sub-gate PASS/FAIL with the exact list of missing critical facts, verdict PASS|FAIL.
")

On a Step 2 FAIL, restore and report — never patch in place:

bash "$CLAUDE_PLUGIN_ROOT/skills/text-optimize/scripts/text-guard.sh" restore --run-dir <RUN_DIR> <file>

The snapshot stays in <RUN_DIR>/orig/ after the run; name the directory in the final report so the user can diff or delete it.

Quality Checklist

Before

• Phase 0 ran: clean tree confirmed, snapshot on disk, RUN_DIR captured
• Read entire text
• Identify type (prompt, docs, agent, skill)
• Note critical info and cross-references

During — Apply by Mode

Deep Mode Pipeline

Phase 1: Compress

• Load references/deep-compression.md for symbol/abbreviation tables
• Dedup pass (D.1-D.6) + dedup ledger before symbol substitution (see deep-compression.md Redundancy Factoring + Token-Class Keep/Drop Heuristics)
• Aggressive lossy pass (A.1-A.4) after dedup: line fusion (A.1) -> paraphrase (A.3) -> word drop (A.2) -> knowledge elision (A.4); record every A.2/A.4 drop in loss ledger (dropped -> reason)
• Scan text for terms occurring 3+ times → build DICT header
• Apply symbol substitutions, filler removal, structural compression
• Apply existing rules (C, T, S, R, P) in addition to deep techniques

Phase 2: Verify Round 1

• Self-check inside the optimizing agent (it has no Agent/Task tool — the INDEPENDENT gate is the skill's Phase 3, not this round)
• Extract a numbered atomic-fact inventory from ORIGINAL, check each in COMPRESSED, label kept/merged/lost/distorted; match % = (kept + merged) / total; verify no two distinct facts merged into one (D.6)
• A.1 fused / A.3 paraphrased facts count as kept/merged; A.4 elisions labeled elided-known in loss list and count as loss against the 95% gate
• Calculate semantic match %
• If >= 95% → done
• If < 95% → return loss list for patching

Phase 3: Patch + Verify Round 2

• Apply patches for missing facts
• Re-verify, including the 100% sub-gate on numbers/names/negations/scope qualifiers
• If still < 95%, or the sub-gate fails → the file is RESTORED from the snapshot by the skill's Phase 3 and the result is refused; report the loss list, never leave a lossy file in place
• Output final result + statistics
• Optional reconstruction probe: expand compressed back to prose, diff entities/numbers vs original (entities are lost first)

Max Mode Pipeline

Phase 1: Compress

• Dedup pass (D.1-D.6) + build dedup ledger before symbol substitution (deep-compression.md Redundancy Factoring)
• Apply all Deep techniques (DICT header, symbol substitutions, structural compression, aggressive lossy A.1-A.4 with loss ledger, inherited from deep)
• Load references/max-compression.md for atomic fact-line decomposition, ASCII operator dialect, format-aware tables
• Respect guardrails C1-C4: optimize for signal/token (not raw token count); preserve scope qualifiers; ~20% deletion ceiling — never strip punctuation; consistent terminology throughout
• Chain-of-Density final pass (B4): fuse missing entities at fixed length

Phase 2: Verify Round 1 — Claim Inventory

• Self-check inside the optimizing agent (the INDEPENDENT gate is the skill's Phase 3)
• Decompose original into numbered atomic claims (one predicate per claim), label each kept/merged/lost/distorted
• Semantic match % = (kept + merged) / total; merged (deduplicated) facts = preserved; A.1 fused / A.3 paraphrased facts = kept/merged; A.4 elisions labeled elided-known = loss against the 95% gate
• Gate >= 95% -> proceed; < 95% -> return loss list

Phase 3: Patch + Verify Round 2 — Self-QA Probe (MANDATORY)

• Apply patches; Round 2 is mandatory, NEVER skip; use the INDEPENDENT method: generate 10-20 questions from original (entities, numbers, conditions, negations), answer from compressed only
• Sub-gate: 100% of numbers, names, negations, scope qualifiers must survive
• If still < 95% or sub-gate fails -> the skill's Phase 3 RESTORES the snapshot over the file and refuses the result; report the explicit loss list (lost/distorted/merged/elided-known labels) plus the suggested lighter mode
• Output final result + statistics

Standard Mode Pipeline

Phase 1: Compress

• Load references/standard-compression.md
• Dedup pass (D.1-D.4, D.6) on fact inventory — merge accidental repeats, cap emphasis at 2
• Sentence-level zero-loss pruning before wording compression
• Remove filler words/constructions
• Merge repeated ideas
• Convert paragraphs to bullets/tables where appropriate
• Apply existing rules (C, T, S, R, P)

Phase 2: Verify

• Extract atomic-fact inventory from original; check each fact in compressed
• Gate: (kept + merged) / total >= 98% — list lost facts -> patch
• 100% sub-gate on numbers/names/negations/scope qualifiers; a failure is a restore-and-refuse via the skill's Phase 3, not a warning
• One round only

Iron Rules (All Modes)

After

• All facts preserved (except ledgered A.2/A.4 drops at deep/max)
• Logic consistent
• References valid (R.1-R.3)
• Tokens reduced

Output Format

## Optimization Report: [filename]

| Metric | Before | After | Change |
|--------|--------|-------|--------|
| Lines  | X      | Y     | -Z%    |
| Tokens | ~X     | ~Y    | -Z%    |

### Rules Applied
- [Rule IDs]: [Description of changes]

### Issues Found & Fixed
- [Issue]: [Resolution]

### Cross-Reference Verification
- [x] All file refs valid (R.1)
- [x] All URLs checked (R.2)
- [x] No circular refs (R.3)

Anti-Patterns