Making Files Clearer

What this skill does

# Making Files Clearer

A systematic approach to transforming verbose, redundant, or disorganized files into clear, concise, essential-only content.

## Core Principles

### 1. Ruthless Elimination
- **Remove redundancy**: Delete duplicate information, repeated explanations, and overlapping content
- **Cut fluff**: Eliminate unnecessary adjectives, hedging language, and verbose phrasing
- **Strip decorative elements**: Remove ASCII art, excessive formatting, and visual noise unless they serve a functional purpose

### 2. Essential Information Only
- **Keep what matters**: Retain only information that directly serves the file's purpose
- **Question every line**: Ask "Does removing this change understanding?" If no, remove it
- **Preserve accuracy**: Never sacrifice correctness for brevity

### 3. Strategic Examples
- **Examples add clarity when**:
  - Concept is abstract or counterintuitive
  - Multiple valid interpretations exist
  - Common mistakes need illustration
- **Examples are unnecessary when**:
  - Concept is self-evident
  - They merely repeat what's already clear
  - They're "nice to have" but not essential

### 4. Logical Organization
- **Group related content**: Cluster similar topics together
- **Progressive structure**: Simple concepts before complex ones
- **Clear hierarchy**: Use headings to show relationships
- **Scannable format**: Readers should find information quickly

## Workflow

### Step 1: Create Backup
```bash
cp original.md original.md.backup
```

### Step 2: Analyze Current State
1. Read the entire file
2. Identify the file's core purpose
3. List essential information categories
4. Note redundant sections, fluff, and organizational issues

### Step 3: Create Clarity Plan
Before editing, outline:
- What to keep (essential information)
- What to remove (redundancy, fluff)
- How to reorganize (new structure)
- Where examples add value

### Step 4: Execute Transformation
Apply changes systematically:
1. **Remove**: Delete redundant and unnecessary content
2. **Reorganize**: Restructure for logical flow
3. **Clarify**: Rewrite unclear sections concisely
4. **Validate**: Ensure no essential information lost

### Step 5: Present Changes for Review
Show the user:
- Summary of what changed
- Before/after comparison
- Ask for confirmation

### Step 6: Finalize
After user confirms:
```bash
rm original.md.backup
```

If user rejects changes:
```bash
mv original.md.backup original.md
```

## Common Clarity Anti-Patterns

### Redundancy
❌ **Bad**: Explaining the same concept multiple times in different words
✅ **Good**: One clear explanation, possibly with a targeted example

### Unnecessary Examples
❌ **Bad**: "For instance, if you have a variable `x = 5`, that's an example of setting a variable"
✅ **Good**: "Variables store values: `x = 5`"

### Verbose Phrasing
❌ **Bad**: "It is important to note that you should always make sure to..."
✅ **Good**: "Always..."

### Over-Documentation
❌ **Bad**: Documenting every obvious step
✅ **Good**: Documenting non-obvious behavior and gotchas

### Poor Organization
❌ **Bad**: Random topic ordering, nested sections with unclear purpose
✅ **Good**: Logical grouping, clear hierarchy, scannable headings

## Output Format

When making a file clearer:

1. **Show before/after comparison** (if file is small enough):
   ```
   Original: 250 lines, 15 sections, 30% redundancy
   Revised: 120 lines, 8 sections, focused content
   ```

2. **Summarize changes**:
   - What was removed and why
   - How content was reorganized
   - Where examples were added/removed

3. **Present the clarified content**: Use Edit tool to update the file

4. **Validate**: Confirm all essential information preserved

## Edge Cases

- **Technical documentation**: Preserve all technical accuracy; brevity should never compromise correctness
- **Legal/compliance files**: Consult before removing anything that might be required
- **Tutorials**: Examples are often essential; keep those that teach, remove those that just show off
- **Configuration files**: Comments may seem verbose but often prevent errors; keep contextual comments

## Success Criteria

A file is clearer when:
- A first-time reader understands it faster
- Information is findable without scrolling/searching extensively
- No questions arise from ambiguity or missing context
- The file can be maintained more easily
- Essential information density is maximized