The Yak-Shaving Diaries: One Week of 'Productive' Procrastination, Fully Documented

Let me describe a Tuesday for you.

I sat down at 9 AM with one goal: add keyboard shortcuts to my RSS reader, a side project I've been maintaining for about two years. Simple feature. Maybe two hours of work, including tests.

At 11:47 PM that night, I had not written a single line of the shortcut handler. Instead, I had:

• Extracted a FeedParser interface out of my parser module
• Rewritten three services to depend on that interface
• Migrated my test suite from Jest to Vitex
• Written a custom ESLint rule to enforce the new pattern
• Updated the README to document architecture decisions nobody will ever read

The shortcuts still don't exist. This is the story of how that happens, why it keeps happening, and what I finally did about it.

The Anatomy of a Yak

For the uninitiated, yak-shaving is the art of following a chain of tangential tasks until you're doing something wildly unrelated to your original goal. The term comes from a Ren and Stimpy episode and was canonized in developer culture years ago. Every engineer knows the feeling. Very few of us admit how often we do it on purpose.

Here's the seductive part: none of my Tuesday detours felt like procrastination. Extracting an interface felt like good engineering. Migrating the test runner felt like staying current. Writing the ESLint rule felt like investing in the future.

That's the trick refactoring plays on you. Shipping a feature has a binary outcome — it works or it doesn't, and users will tell you which. Refactoring has no such verdict. You can always refactor a little more. There's no moment where a stranger's reaction tells you your work was pointless.

Refactoring is work without the risk of being judged. Which is exactly why it's so appealing.

The Week, By the Numbers

After that Tuesday, I got curious and tracked the rest of the week. Here's where the hours actually went:

• Monday: 1 hour on features, 5 hours on 'project structure improvements'
• Tuesday: 0 hours on features, 8 hours on the abstraction cascade described above
• Wednesday: 2 hours on features, 4 hours upgrading dependencies, 2 hours fixing what the upgrades broke
• Thursday: 3 hours on features (a personal record!), 3 hours refactoring the code I'd just written
• Friday: 1 hour on features, 5 hours writing a blog post about my RSS reader's architecture

Total feature progress: 7 hours out of 40. And notice Friday — I wrote content about the code instead of improving the code. Even my meta-work had meta-work.

The kicker? The three features users actually requested were: keyboard shortcuts, better mobile layout, and OPML export. Total estimated effort: about two days. I spent two weeks avoiding them.

Why We Do This (The Uncomfortable Part)

I've thought a lot about why smart people with good intentions do this, and I've landed on three reasons:

Refactoring has no user. When I ship keyboard shortcuts, someone might use them and someone might not. That's vulnerability. When I extract an interface, the only judge is me — and I'm a lenient grader.

Cleanup feels like progress even when it isn't. A diff with 400 changed lines looks like a productive day. Your git contribution graph can't tell the difference between meaningful work and expensive noodling.

Feature work requires decisions, and decisions can be wrong. Should the shortcut for 'mark all read' be Shift+A or E? I don't know! That ambiguity is genuinely uncomfortable. Refactoring the parser module, by contrast, has a correct answer that I already know.

The Guardrails I Use Now

I'm not going to tell you refactoring is always bad — some of my Tuesday work genuinely made the codebase better. But I've installed a few rules for myself, and they've helped:

The two-strike rule. I can't refactor a piece of code until it's annoyed me on two separate occasions. One-off friction is just noise. Patterns are only patterns the second time.

Feature-first mornings. Before 11 AM, the only commits allowed are ones that touch user-facing behavior. Cleanup is an afternoon activity, after I've earned it.

The shipping tax. Every hour of refactoring requires a shipped feature in the same week. If I refactor and don't ship, the refactor was avoidance, and I have to delete something to pay for it. (I have never enforced this literally. The threat works anyway.)

Write the issue, not the code. When I spot an abstraction worth extracting mid-feature, I write a GitHub issue describing it and move on. Surprisingly, most of those issues look pointless a week later. The urge is often hotter than the need.

A Test You Can Run Right Now

Here's the simplest heuristic I've found: ask yourself, would a user notice if I did this or if I didn't?

If the answer is no, you're not building — you're tidying. Tidying is fine, occasionally. But it should be a snack, not a meal. And if you find yourself tidying every time you sit down to build, you're not an engineer having high standards. You're a person avoiding the scary part of the work.

The scary part, by the way, is the only part that matters. My RSS reader with a beautiful architecture and no keyboard shortcuts helps no one. A janky one with shortcuts helps everyone who asked for them.

The shortcuts shipped the following Monday. Took two hours. I'm still a little embarrassed by that math.