The Disk Space Detective Story - Plan

Genre & Style

Mystery/Detective Noir meets Hoarders meets CSI: Cyber

• Film noir detective investigating a "crime scene" (the full disk)
• Each command is a detective tool/technique
• Files and directories are suspects, witnesses, and clues
• The investigation unfolds methodically with red herrings and discoveries

Story Arc

Act 1: The Case Arrives (Setup)

User's question: "How much disk space do we have?"

• Opening scene: Detective gets the call - "We need you. The machine is dying."
• The First Survey (df -h): Walking into the crime scene
  • 89% full! Only 2.2GB left! dramatic music
  • The victim (disk) is barely breathing
  • Teaching moment: df -h is like taking the vital signs

Act 2: The Investigation Begins (Rising Action)

Scene 1: "Follow the Money" - Top-Level Sweep

Commands: Multiple du commands in parallel

• Detective splits into 4 clones (parallel execution!) to search simultaneously
  • Clone 1: Checking /home
  • Clone 2: Interrogating root /
  • Clone 3: Looking for the usual suspects (node_modules)
  • Clone 4: Checking the trash (tmp files)
• Teaching moment: Why run commands in parallel? Time is money!
• Discovery: "We got three big fish: /snap (7.4GB), /home (6.9GB), /var (4.2GB)"

Scene 2: "Dig Deeper" - Following the Leads

Commands: Targeted du on suspicious directories

• Each directory is a witness being questioned
• Detective takes notes, uses sort -hr (organizing evidence by size)
• Red Herring: "Is it the node_modules?" (Only 697MB - not the main culprit!)
• Teaching moment: Always sort and limit output (head -20) - don't drown in data

Scene 3: "The Usual Suspects" - Cache Investigation

Commands: Exploring .cache, .npm, checking journal logs

• Meeting the hoarders: Puppeteer (1.2GB of browser!), Playwright (901MB more browsers!)
• The npm packrat (1.8GB of "I might need this someday")
• Comedy: Cache files as hoarders with emotional attachments
  • Puppeteer: "But what if I need Chrome version 114, 115, AND 116?!"
• Teaching moment: What IS cache? Why does it exist? When is it safe to delete?

Scene 4: "The Snap Trap" - System Packages

Commands: Investigating /snap and /var/lib/snapd

• Discovery: Ubuntu keeps old versions like a photo hoarder
• Two GNOME versions living together (3.1GB + 1.2GB)
• 716MB snap cache - backups of backups
• Teaching moment: Package managers keep old versions for rollback (safety vs space)

Act 3: The Solution (Resolution)

Scene 5: "Building the Case" - The Report

• Detective assembles all evidence on the board (our bullet-point breakdown)
• Connecting the dots with red string
• Teaching moment: How to read du output, understand directory structure

Scene 6: "The Cleanup Plan" - Justice Served

• Creating the todo list (8 items)
• Each cleanup command is like arresting a suspect
• Estimated recovery: 4-5GB!
• Teaching moment: Always verify what you're deleting, calculate space savings

Characters

Main Character: The Detective (Claude/AI)

• Methodical, curious, explains everything
• Has a toolkit of commands (magnifying glass = du, fingerprint kit = find, etc.)
• Talks to the audience (CS students) breaking the 4th wall

The Suspects/Witnesses:

1. Cache Family - Hoarders who mean well

   • Puppeteer Pete (keeps all browser versions)
   • Playwright Paula (same problem)
   • npm Nancy (saves everything "just in case")

2. The Snap Gang - Old-timers who won't leave

   • GNOME Grandpa v42 (won't retire even though v46 is here)
   • Chromium Charlie (multiple versions)

3. Log Larry - The journalist who records everything (154MB of journals)

4. Temp Tim - The messy neighbor in /tmp (472MB)

5. node_modules - The Red Herring

   • Everyone suspects them first!
   • But they're actually reasonable (only 697MB)
   • Teaching moment: Don't assume, investigate!

Key Teaching Moments (Educational Goals)

Command Concepts:

1. df -h: High-level overview (human-readable sizes)
2. du: Disk usage deep-dive (--max-depth, sorting)
3. Parallel execution: Running multiple independent commands at once
4. sort -hr: Organizing output (human-readable, reverse)
5. head: Limiting output to useful amounts
6. find: Searching for specific patterns
7. sudo: When you need permissions (entering restricted areas)

Problem-Solving Process:

1. Start broad → narrow down
2. Run parallel searches when independent
3. Sort and filter to find signal in noise
4. Verify before acting (check sizes, safety)
5. Document findings (make a plan)

System Knowledge:

1. What are caches and why they exist
2. Package managers keep old versions
3. Logs accumulate over time
4. Difference between /home, /var, /tmp, /snap
5. What's safe to delete vs. risky

Creative Elements

Visual Metaphors:

• Commands as detective tools
• Directories as rooms/buildings
• Files as suspects/evidence
• Disk space as real estate
• Parallel commands as splitting into clones

Comedy Moments:

• Cache files with separation anxiety
• Old snap packages refusing to retire
• node_modules getting blamed unfairly
• The dramatic reveal when tmp is only 21MB (anticlimactic)
• Journal logs as a gossip columnist

Narrative Devices:

• Inner monologue explaining decisions
• Breaking the 4th wall to teach
• Flashbacks showing why each command was chosen
• Before/after reveals

Story Flow Structure

Question → Initial Survey → "The scene" → Parallel Investigation
    ↓
Discovery of Big 3 → "The main leads"
    ↓
Deep Dive each lead → "Interrogation"
    ↓
Find specific culprits → "The guilty parties"
    ↓
Verify and document → "Build the case"
    ↓
Present solution → "Justice served"

Tone Notes

• Playful but educational
• Accessible to beginners
• Shows the thinking process not just commands
• Celebrates when wrong guesses happen (node_modules!)
• Emphasizes "why" not just "what"

Target Audience Adaptations

For CS students who:

• Know basic terminal concepts but not disk management
• Haven't done system administration
• Learn better through story than documentation
• Need to see the reasoning, not just the commands