Instruction Optimizer
Invariant Principles
- Smarter AND smaller - Compression that loses capability is regression, not optimization
- Evidence over claims - Show token counts before/after; verify no capability loss
- Unique value preservation - Deduplicate redundancy, keep distinct behaviors
- Clarity at critical points - Brevity yields to clarity for safety/compliance sections
Reasoning Schema
Inputs
| Input | Required | Description |
|---|---|---|
instruction_file | Yes | Path to skill, prompt, or CLAUDE.md to optimize |
target_reduction | No | Desired token reduction percentage (default: maximize) |
preserve_sections | No | Sections to skip optimization (safety, legal) |
Outputs
| Output | Type | Description |
|---|---|---|
optimization_report | Inline | Summary with before/after token counts |
optimized_content | Inline | Full optimized file content |
verification_checklist | Inline | Capability preservation verification |
Declarative Principles
| Principle | Application |
|---|---|
| Semantic deduplication | Same meaning stated N times -> state once |
| Example consolidation | Multiple examples of same pattern -> one with variants noted |
| Verbose phrase elimination | "In order to" -> "To"; "It is important to note that" -> [delete] |
| Section collapse | Overlapping sections -> merge under single heading |
| Implicit context removal | Obvious-from-title content -> delete |
| Conditional flattening | Nested if-chains -> single compound condition |
Compression Patterns
"In order to" -> "To"
"Make sure to" -> [delete]
"You should always" -> "Always"
"Prior to doing X" -> "Before X"
"In the event that" -> "If"
"Due to the fact that" -> "Because"
"At this point in time" -> "Now"
"For the purpose of" -> "To"
Process
- Read file completely
- Estimate tokens (words * 1.3)
- Identify safety-critical sections (skip these)
- Apply compression patterns
- Draft optimized version
- Verify capability preservation
- Calculate savings, present diff
Large File Strategy (>500 lines)
For files exceeding 500 lines, use parallelization:
- Split into sections: Identify logical boundaries (phases, categories)
- Dispatch parallel subagents: Each analyzes one section for compression opportunities
Task: "Analyze lines 1-200 of [file] for compression. Return: redundancies found, suggested compressions, estimated savings." Task: "Analyze lines 201-400 of [file] for compression. Return: redundancies found, suggested compressions, estimated savings." - Orchestrator merges: Collect findings, check for cross-section dependencies
- Resolve conflicts: If Section A references Section B's content, coordinate changes
- Apply atomically: Make all changes in single edit to maintain consistency
Verification Protocol
Before declaring optimization complete, verify NO capability loss:
- Identify 3 representative use cases from original instructions
- Mentally trace each use case through the optimized instructions
- Compare: Does optimized produce equivalent behavior?
| Use Case | Original Handles? | Optimized Handles? | Status |
|---|---|---|---|
| [Case 1] | Yes | ? | |
| [Case 2] | Yes | ? | |
| [Case 3] | Yes | ? |
If ANY use case degrades: revert that specific optimization.
Output Format
## Optimization Report: [filename]
### Summary
- Before: ~X tokens | After: ~Y tokens | Savings: Z (N%)
### Changes
1. [Technique]: [Description] (-N tokens)
### Verification
- [ ] Triggers preserved
- [ ] Edge cases handled
- [ ] Outputs specified
- [ ] Clarity maintained
### Optimized Content
[full content]
Skip Optimization When
- Already minimal (<500 tokens)
- Safety-critical content
- Legal/compliance requirements
- Recently written (let stabilize)
Self-Check
Before completing:
- Token count reduced (show numbers)
- All triggers from original still work
- All edge cases still handled
- No safety sections compressed
- Terminology consistent throughout
- Structured formats preserved exactly
If ANY unchecked: STOP and fix before presenting result.