Document Optimizer

Read, optimize, and rewrite markdown documents for token efficiency, structural clarity, and LLM parseability. The target file is provided as a file path argument.

Workflow

1. Read the file at $ARGUMENTS. If no path is provided, ask for one
2. Analyze the document for optimization opportunities using the principles below
3. Rewrite the file in place with all optimizations applied
4. Verify the rewritten document preserves all factual content and meaning from the original
5. Report using this format:

Original: [N] lines → Optimized: [N] lines ([N]% reduction) Changes: [comma-separated list of key changes]

Optimization Principles

Token Economics

Evaluate each sentence for token value. Remove content that restates common knowledge, repeats itself, or adds no actionable value.

Remove decorative language. No "please note", "it's worth mentioning", "remember that", "importantly".

Eliminate filler transitions. "Additionally", "furthermore", "in other words", "as mentioned above".

Remove hedging. "Consider", "try to", "when possible", "generally speaking", "it depends".

Structural Optimization

Technique	Apply When
Convert prose to tables	Comparing options, listing attributes, or mapping inputs to outputs
Convert prose to lists	Content contains discrete, parallel, independent items
Keep prose	Explaining relationships, conditional logic, or rationale
Merge sections	Multiple sections cover the same concept
Remove sections	Content restates framework docs or common knowledge

Flatten unnecessary nesting. Collapse single-item subsections into their parent.

Place critical information first within each section. Most important content at the top.

End sections decisively. No trailing "etc.", "and so on", or "and more".

Sentence Compression

Remove filler words and passive voice:

• Before: "It is recommended that you should make sure to always validate user input"
• After: "Validate user input at API boundaries"

Combine related statements:

• Before: "Use TypeScript for all new files. Make sure to add type annotations. Enable strict mode in tsconfig."
• After: "Use TypeScript strict mode with explicit type annotations for all new files"

Remove redundant qualifiers:

• Before: "This is a very important and critical step that must always be done"
• After: "Required step"

Content Filtering

Remove Entirely

• Welcome messages, introductions, background history
• Motivational statements ("This will help you write better code!")
• Content the model already knows (framework basics, language syntax)
• Hypothetical future scenarios ("If we ever migrate to...")
• Time-sensitive references without dates
• Redundant examples that demonstrate the same concept

Preserve

• Domain-specific knowledge the model lacks
• Concrete examples demonstrating non-obvious patterns
• Decision criteria and trade-off analysis
• Exact commands, configs, and code snippets
• Constraints and prohibited actions

Formatting Cleanup

Use language-labeled code blocks. Never use unlabeled fences.

Use consistent heading hierarchy. No skipped levels (h2 -> h4).

Remove excessive emphasis. Bold only for hard constraints where violation causes failure. Limit to 10% of content.

Use one blank line between sections. Remove consecutive blank lines.

Standardize list markers within each list (all - or all *, not mixed).

Terminology Consistency

Identify synonyms used for the same concept. Choose the most precise term and use it throughout.

• Before: alternating "endpoint", "route", "URL", "path" for the same concept
• After: consistently "endpoint" throughout

Constraints

• Preserve all factual content and meaning. Compression must not alter semantics
• Preserve code blocks verbatim unless they contain obvious errors
• Preserve document title (h1 heading). Rephrase for concision only if verbose
• Do not add new content. Optimization removes and restructures; it does not invent
• Do not add commentary or annotations to the output file
• Write the optimized document directly to the source file

Scope Boundaries

Do not use for:

• Non-markdown files
• Documents requiring content creation or expansion
• Files already optimized by a previous run
• Code files or config files with markdown comments