Initial commit

commands/optimize-doc.md

@@ -0,0 +1,199 @@
+---
+description: Optimize documentation for conciseness and clarity by strengthening vague instructions and removing redundancy
+source: https://www.reddit.com/r/ClaudeCode/comments/1o3ku9t/hack_and_slash_your_md_files_to_reduce_context_use/?share_id=gJBjUdlUApY73VB0TANvU&utm_medium=android_app&utm_name=androidcss&utm_source=share&utm_term=2
+---
+
+# Optimize Documentation
+
+**Task**: Optimize `{{arg}}`
+
+## Objective
+
+Make docs more concise and clear without vagueness or misinterpretation.
+
+**Goals** (priority order):
+1. Eliminate vagueness - add explicit criteria and measurable steps
+2. Increase conciseness - remove redundancy, preserve necessary info
+3. Preserve clarity AND meaning - never sacrifice understanding for brevity
+
+**Idempotent**: Run multiple times safely - first pass strengthens and removes redundancy, subsequent passes only act if improvements found.
+
+## Analysis Methodology
+
+For each instruction section:
+
+### Step 1: Evaluate Clarity
+
+**Can instruction be executed correctly WITHOUT examples?**
+- Cover examples, read instruction only
+- Contains subjective terms without definition?
+- Has measurable criteria or explicit steps?
+
+Decision: Clear → Step 2 | Vague → Step 3
+
+### Step 2: If Clear - Evaluate Examples
+
+Check if examples serve operational purpose:
+
+| Keep If | Remove If |
+|---------|-----------|
+| Defines what "correct" looks like | Explains WHY (educational) |
+| Shows exact commands/success criteria | Restates clear instruction |
+| Sequential workflow (order matters) | Obvious application of clear rule |
+| Resolves ambiguity | Duplicate template |
+| Data structures (JSON, schemas) | Verbose walkthrough when numbered steps exist |
+| Boundary demos (wrong vs right) | |
+| Pattern extraction rules | |
+
+### Step 3: If Vague - Strengthen First
+
+**DO NOT remove examples yet.**
+
+1. Identify vagueness source: subjective terms, missing criteria, unclear boundaries, narrative vs explicit steps
+2. Strengthen instruction: replace subjective terms, convert to numbered steps, add thresholds, define success
+3. Keep all examples - needed until strengthened
+4. Mark for next pass - re-evaluate after strengthening
+
+## Execution-Critical Content (Never Condense)
+
+Preserve these even if instructions are clear:
+
+### 1. Concrete Examples Defining "Correct"
+Examples showing EXACT correct vs incorrect when instruction uses abstract terms.
+
+**Test**: Does example define something ambiguous in instruction?
+
+### 2. Sequential Steps for State Machines
+Numbered workflows where order matters for correctness.
+
+**Test**: Can steps be executed in different order and still work? If NO → Keep sequence
+
+### 3. Inline Comments Specifying Verification
+Comments explaining what output to expect or success criteria.
+
+**Test**: Does comment specify criteria not in instruction? If YES → Keep
+
+### 4. Disambiguation Examples
+Examples resolving ambiguity when rule uses subjective terms.
+
+**Test**: Can instruction be misinterpreted without this? If YES → Keep
+
+### 5. Pattern Extraction Rules
+Annotations generalizing specific examples into reusable decision principles (e.g., "→ Shows that 'delete' means remove lines").
+
+**Test**: If removed, would Claude lose ability to apply reasoning to NEW examples? If YES → Keep
+
+## Reference-Based Consolidation Rules
+
+### Never Replace with References
+
+- Content within sequential workflows (breaks flow)
+- Quick-reference lists (serve different purpose than detailed sections)
+- Success criteria at decision points (needed inline)
+
+### OK to Replace with References
+
+- Explanatory content appearing in multiple places
+- Content at document boundaries (intro/conclusion)
+- Cross-referencing related but distinct concepts
+
+### Semantic Equivalence Test
+
+Before replacing with reference:
+1. ✅ Referenced section contains EXACT same information
+2. ✅ Referenced section serves same purpose
+3. ✅ No precision lost in referenced content
+
+**If ANY fails → Keep duplicate inline**
+
+## The Execution Test
+
+Before removing ANY content:
+
+1. **Can Claude execute correctly without this?**
+   - NO → KEEP (execution-critical)
+   - YES → Continue
+
+2. **Does this explain WHY (rationale/educational)?**
+   - YES → REMOVE
+   - NO → KEEP (operational)
+
+3. **Does this show WHAT "correct" looks like?**
+   - YES → KEEP (execution-critical)
+   - NO → Continue
+
+4. **Does this extract general decision rule from example?**
+   - YES → KEEP (pattern extraction)
+   - NO → May remove if redundant
+
+### Examples
+
+❌ **Remove** (explains WHY):
+```
+RATIONALE: Git history rewriting can silently drop commits...
+Manual verification is the only reliable way to ensure no data loss.
+```
+
+✅ **Keep** (defines WHAT "correct" means):
+```
+SUCCESS CRITERIA:
+- git diff shows ONLY deletions in todo.md
+- git diff shows ONLY additions in changelog.md
+- Both files in SAME commit
+```
+
+## Conciseness Strategies
+
+1. **Eliminate redundancy**: Remove repeated info, consolidate overlapping instructions
+2. **Tighten language**: "execute" not "you MUST execute", "to" not "in order to", remove filler
+3. **Structure over prose**: Bullets not paragraphs, tables for multi-dimensional info, numbered steps for sequences
+4. **Preserve essentials**: Keep executable commands, data formats, boundaries, criteria, patterns
+
+**Never sacrifice**:
+- Scannability (vertical lists > comma-separated)
+- Pattern recognition (checkmarks/bullets > prose)
+- Explicit criteria ("ALL", "NEVER", exact counts/strings)
+- Prevention patterns (prohibited vs required)
+
+## Execution Instructions
+
+1. Read `{{arg}}`
+2. **For large documents (>100 lines)**: Use TodoWrite to track sections:
+   ```
+   ☐ Section: [name] - analyze clarity
+   ☐ Section: [name] - analyze clarity
+   ...
+   ☐ Apply all optimizations
+   ☐ Verify quality standards met
+   ```
+3. Analyze each section using methodology above
+4. Optimize directly: strengthen vague instructions, remove redundancy, apply conciseness strategies
+5. Report changes to user
+6. Commit with descriptive message
+
+## Quality Standards
+
+Every change must satisfy:
+- ✅ Meaning preserved
+- ✅ Executability preserved
+- ✅ Success criteria intact
+- ✅ Ambiguity resolved
+- ✅ Conciseness increased
+
+## Change Summary Format
+
+```
+## Optimization Summary
+
+**Changes Made**:
+1. [Section] (Lines X-Y): [Change description]
+   - Before: [Issue - vagueness/redundancy/verbosity]
+   - After: [Improvement]
+
+**Metrics**:
+- Lines removed: N
+- Sections strengthened: M
+- Redundancy eliminated: [examples]
+
+**Next Steps**: [Further optimization possible?]
+```