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?]