Skip to main content
    +-------------------------------------------------+
    |   HERMENEUTIC DEBUGGING                         |
    |                                                 |
    |   Attempt ──► Fail ──► Observe ──► Revise       |
    |      │                               │          |
    |      └───────────────────────────────┘          |
    |                                                 |
    |   Each failure reveals a hidden assumption.     |
    |                                                 |
    |   Understanding emerges through iteration.      |
    +-------------------------------------------------+

Hermeneutic Debugging

Try this: 8 iterations of the same bug

A simple logo animation took 8 attempts to get right. Each failed fix revealed an assumption we didn't know we had. Walk through the same process—predict what will happen, then see what actually happens.

The Problem

Animate a logo in a Next.js App Router application:

  • Home page: show full logo (expanded)
  • Home → Internal page: wait 600ms, then contract to icon
  • Internal → Home: expand back to full logo
  • Internal → Internal: stay as icon

Seems simple. It wasn't.

1 / 8
Iteration 1

The Naive Implementation

Use state and effects. When not on home, delay 600ms before contracting.

React Component
const [showFullLogo, setShowFullLogo] = useState(isHome);

useEffect(() => {
  if (isHome) {
    setShowFullLogo(true);
  } else {
    setTimeout(() => setShowFullLogo(false), 600);
  }
}, [isHome]);
Select a prediction and run to continue

What You Just Experienced

Each failed fix revealed an assumption you didn't know you had. That's the pattern: attempt, observe what actually happens, revise your understanding.

"One observation is worth more than ten guesses."

Try this in your next bug: Before the second fix attempt, write down what assumption the first failure revealed.