DEV Community: Samson Sunny

From 33 Specs to 20: Fixing Documentation Sprawl Before It Rots

Samson Sunny — Tue, 15 Sep 2026 17:32:47 +0000

Last week I opened my app's spec folder and counted the files. Thirty-three. For an iOS app built by one person.

Fifteen of them were shorter than 55 lines. Three described quick capture — separately. One existed purely to document UI I had already deleted. The folder had become a museum of decisions instead of a description of the product.

This is the story of consolidating those 33 specs into 20 without losing a single requirement — and the rules I wrote down so it doesn't happen again. If you maintain any documentation that grows one file at a time, the failure mode is the same whether the docs describe software, a team workflow, or your own systems.

How the sprawl happened

It happened honestly. Every time I built a feature, I wrote a spec for it. Capture a task inline in a list? New spec. Capture a task inline in Upcoming? Another spec. A haptic on completion? Spec. An animation on completion? Different spec.

Each file made sense on the day it was written. The problem is what they described: events, not things. completion-animation describes something that happened once — completion got an animation. What a reader actually needs is the completion experience: the animation, the haptic, the delayed exit, together.

The symptoms were classic:

Symptom	What it looked like
Micro-files	15 specs under 55 lines; some were a single requirement
Split families	Three capture specs, three reorder specs, five notification-adjacent specs
Tombstones	A spec whose every requirement was marked REMOVED — history masquerading as guidance
Finished chores	A "cleanup" spec describing a one-time task as if it were eternal behavior
Inconsistent format	Some files had purpose statements and clean structure; others still carried merge markers from months ago

None of this was visible day to day. That's what makes documentation sprawl insidious — each individual file looks fine. The rot is in the aggregate.

"Every piece of knowledge must have a single, unambiguous, authoritative representation within a system."

— Andy Hunt & David Thomas, The Pragmatic Programmer

That's the DRY principle, usually applied to code. It applies twice as hard to documents, because documents have no compiler to catch the duplication.

The rule that fixed the grouping

Before touching a single file, I wrote down the diagnosis: specs should be organized by capability — a thing the product does — not by change — something that happened once.

A capability can hold many requirements. Completion animation and completion haptic aren't two capabilities; they're two requirements of one capability: what completing a task feels like. Quick capture in a list, quick capture today, quick capture in Upcoming — one capability, three contexts.

With that lens, the whole folder regrouped itself almost mechanically:

Before (33 files)	After (20 files)
contextual-task-creation, list-inline-capture, upcoming-inline-capture	quick-capture
completion-animation, completion-haptic-feedback	completion-interaction
daily-reorder, custom-list-reorder, task-actions	task-ordering
list-delete, list-rename, list-reorder	list-management
reminder-date-model, reminder-deadline-time	reminder-scheduling
bulk-selection, bulk-operations	bulk-editing
clear-notifications-on-open, notification-migration	absorbed into task-notifications
sidebar-navigation, clean-unused-code	deleted

Fifteen files became six. Two moved into an existing home. Two were deleted outright. Thirteen specs I never needed to touch stayed exactly as they were.

"A spec suite grows one file per decision until reading it costs more than rebuilding."

The consolidation, step by step

The scary part of merging documents is silent loss — a requirement that falls out during the merge and nobody notices for a year. So the process was built around verification, not writing:

Inventory every requirement title. Not summaries, not vibes — exact headings. The count came back: 150 requirements across 33 files.
Group by entity, then by verb. Tasks, lists, editor, notifications, bulk operations. Within each group, related files revealed themselves immediately.
Merge into capability files with a normalized format: a purpose statement at top, flat requirement list below, no stale markers.
Diff titles after every merge. Every original requirement title had to appear exactly once in the output set. Four near-duplicate titles got renamed to disambiguate ("Sort order uses fractional string encoding" existed twice — once for tasks, once for lists).
Reconcile scenario counts per target file. If a merged spec absorbed three sources with 9, 9, and 8 scenarios, the result must contain exactly 26.
Delete dead weight last, once everything else was accounted for. The tombstone spec and the finished chore went to the archive.
Write the index and the maintenance rules. Twenty specs, grouped by domain, with the rules that keep it that way.

The verification changed the emotional experience entirely. Deleting a spec sounds reckless until you can say: every requirement title and every scenario is accounted for — here are the numbers. Then deletion stops feeling like loss and starts feeling like cleanup.

"Perfection is achieved, not when there is nothing more to add, but when there is nothing left to take away."

— Antoine de Saint-Exupéry, Wind, Sand and Stars

The rules that keep it small

Consolidating once fixes nothing if the same habits rebuild the pile. These went into the index at the top of the folder:

Amend, don't proliferate. New behavior goes into an existing capability spec unless it's genuinely a new capability. A new requirement is not a reason for a new file.
Prune on a cadence. Every release: delete specs for removed behavior, flag overlaps for merging. Sprawl is cheaper to handle monthly than annually.
Index by domain. A single README mapping every spec to its area means navigation scales even when the count grows again.
Normalize on touch. Whenever a file is edited, it leaves with consistent formatting. No special trips.

Photo by Pixabay on Pexels

This is a to-do list problem wearing a costume

Here's why I'm writing about this on a productivity blog rather than an engineering one: the failure mode is identical to a task list that only ever grows.

Append-only systems feel productive because adding is frictionless. But a list, a wiki, or a spec suite is only as good as its merge and delete operations. When capturing costs nothing and consolidating costs everything, the system drifts toward noise — and eventually you stop trusting it, which defeats the entire point.

The fix is the same discipline in miniature:

Append-only habit	Consolidation habit
New note for every thought	Add to the note that already covers the topic
Done items linger forever	Completed work gets archived on a schedule
Duplicate lists for the same project	One home per topic, links instead of copies
Cleanup "someday"	Cleanup on a date you chose in advance

💡 Product tip: This is exactly why Wednesday Calendar splits tasks into two axes. Time-based tabs — Today, Tomorrow, Upcoming — hold only what deserves attention now, and everything else lives permanently in the Later tab. Nothing is ever lost by keeping the attention views small, because the permanent home absorbs the rest. Small surface, complete system.

Pick one doc collection you maintain — team wiki, personal notes, that specs folder — and run the same pass I ran: inventory what's there, group by thing-not-event, verify nothing disappears in the merge, write down the amendment rule. An hour of consolidation buys years of a system you actually trust.

If you're curious about the app this documentation describes, Wednesday Calendar is a free download on the App Store.

Your Subtasks Don't Need Subtasks

Samson Sunny — Tue, 15 Sep 2026 17:32:43 +0000

Photo by Maxim Makarov on Pexels

A few years ago I managed a website redesign inside my task manager. It started sensibly: a project called "Website redesign" with a handful of steps. A month later I opened it up and found this: Website redesign → Design → Homepage → Hero section → Pick new photo. Five levels deep. I had built a matryoshka doll out of chores.

Here's the part that stuck with me: I never looked at level four again. Not once. That photo-picking step sat in the dark at the bottom of the tower for weeks while I believed the project was moving, because the top of the tower looked organized.

That app let me nest subtasks infinitely, and I assumed that was a feature. It took me an embarrassingly long time to see what it actually was: an escape hatch from making decisions.

Why infinite nesting fails

Every serious task manager offers unlimited nesting, and on the demo screen it looks powerful. A tree! Structure! Systems! But trees have a property the demo doesn't show: the further something is from the root, the less light it gets.

In practice, deep nesting breaks your productivity in three quiet ways.

Nesting becomes planning theater. Rearranging a hierarchy feels like work. It produces the sensation of progress without any of the substance. When a step turns out to be complicated, nesting lets you file the complexity under something instead of facing the real question: what is the actual next action?

Depth hides deadlines. In most apps, a task buried three levels down doesn't show up when you look at your day. You see "Website redesign," tidy and collapsed, while the thing that actually needs doing today — picking the photo — sits invisible underneath. Your daily view lies to you by omission.

Completion gets fuzzy. With five levels, what does "almost done" even mean? Nobody checked off anything at levels two through four, but the whole structure gives off a finished vibe. Vague completion is how projects stall at 90% forever.

As David Allen writes in Getting Things Done, "You don't actually do a project; you can only do action steps related to it."

Allen's distinction is sharper than it first appears. Projects aren't things you do — steps are. And if a "step" contains its own sub-steps, it isn't a step. It's a project wearing a step's clothing, and your task list should say so.

"A step that needs its own steps isn't a step. It's a task in disguise."

The rule: one level deep

So here is the rule I now hold: a task can be broken down exactly once. A subtask cannot have children. Ever.

If breaking something down produces a piece that itself needs breaking down, you don't get to nest again. You have to make a real decision, and it's always one of two:

Promote it. That piece isn't a subtask — it's a full task in its own right, with its own place on your list and its own claim on a date.
Split differently. The breakdown was wrong. Regroup so that every leaf of the tree is genuinely actionable.

	Infinite nesting	One level deep
What planning forces	Endless filing decisions, deferred	One honest question: is this a task or a step?
Visibility	Deep items invisible in daily views	Every item surfaces by its own date
Completion	Fuzzy "it looks done" vibes	Fraction on the parent — 2/3 means 2 of 3 steps done
Deleting a project	Orphans left behind, sometimes	Steps go with it. No debris
On a phone	Pinch-zoom archaeology	Flat rows, readable at a glance

The table's second column isn't a constraint imposed by a tool. It's a constraint imposed by reality — Allen's reality, where only action steps get done.

Three rules that keep one level honest

One-level nesting alone isn't enough; badly done, it just flattens the confusion. Four companion behaviors make it actually work. These started as implementation details in Wednesday Calendar, but they're worth following no matter what tool you use.

1. Finishing all the steps does not finish the task. Check off every subtask and the parent stays open, waiting for you. This is deliberate. The last subtask being done is data; the project being done is a judgment. Keeping the final check in your hands creates a built-in review moment — did we actually ship the redesign, or did we ship it with the footer still broken? Automatic completion steals that inspection from you.

2. Deleting a parent takes its steps with it. Nothing lingers. Cancelled project means cancelled project — including the reminders attached to steps you'll never do. Half-deleted hierarchies are how ghost tasks accumulate.

3. Progress is a fraction, not a forest. Instead of expandable trees, the parent row simply shows where its steps stand: 1/3. Two taps tell you everything the five-level tower was hiding, in less space than the tower's title.

Each step also owns its own schedule. A subtask with a date shows up in your day alongside every other task — not trapped under a parent that happened to get dated too. An undated step stays quietly at home with its siblings. Either way, nothing hides.

💡 Product tip: In Wednesday Calendar, subtasks are added from the editor and behave like full tasks — they can carry notes, priorities, and their own reminders. Parent rows show the completed/total fraction, and finishing the parent sweeps its steps along with it. The one thing the app will never do is complete the project for you.

Photo by cottonbro studio on Pexels

Try this today

You don't need a new app to run this audit. Ten minutes, any tool:

Open your most-nested project — the one you've been avoiding looking inside.
Read the deepest level aloud. If any item there has children, you've found a task in disguise.
Promote it or regroup. Make every leaf genuinely doable by someone who doesn't need to ask "what does this mean?"
Give real steps real dates. If a step matters this week, it gets a date and earns its place in your daily view — not a seat in the audience under its parent.
Delete one tower. If a branch hasn't been touched in a month, cancel it outright. The relief is immediate and the loss is usually zero.

The deeper your current structures run, the more time step five will save you.

Flat lists feel less impressive than trees. That's exactly why they work — there's nowhere left to hide from the actual work.

If you want a tool that enforces this shape instead of fighting it, Wednesday Calendar is a free download.

Wednesday Calendar on the App Store — tap a screenshot to open it.

The 5-Minute Daily Planning Ritual

Samson Sunny — Sat, 15 Aug 2026 17:59:51 +0000

Photo by Content Pixie on Pexels

I used to start my days reactively — open my task manager, see 40 items, feel overwhelmed, grab whatever felt most urgent. By 3 PM, the thing I actually needed to do was still untouched.

The problem wasn't discipline. It was that I had no ritual. I was asking my brain to make high-stakes prioritization decisions while it was still warming up.

Here's what that looked like: I'd sit down with coffee, open the app, and instantly feel my shoulders tighten. Forty items stared back at me — some from last week, some from a project I'd already abandoned, some I couldn't even remember adding. I'd scan, panic, and pick the loudest thing. An email follow-up, a Slack thread, whatever had the most recent timestamp. By lunch I'd completed five small tasks and made zero progress on anything that mattered. And the worst part? I couldn't even tell you what I'd accomplished. The day felt busy but empty.

The fix was a five-minute daily planning ritual. Same time every morning. Three steps. No decisions that require creative energy.

The ritual

Review and clear yesterday. Check off what's done, postpone what slipped, strip the dates that no longer matter.
Pick one priority. Choose the single task that makes the day feel successful if it gets done.
Capture what's new. Dump everything in your head into the list, fast, no filtering.

That's the whole thing. Five minutes, in order, with a hard stop. Here's each step in detail.

Step 1: Review and clear yesterday

Open today's view. Before adding anything new, look at what's already there.

Most of it rolled over from yesterday. Some tasks I started but didn't finish. Some I completed but never checked off. A few were important yesterday but irrelevant today.

Three quick actions handle all of it:

Check off what's done. If I completed a task but forgot to mark it, one tap clears it. Satisfying. Takes ten seconds.
Postpone what slipped. Anything I clearly wasn't going to do yesterday gets a swipe right — it moves to the next day. No guilt, no rescheduling ceremony.
Strip what no longer matters. If a task was tied to a meeting that got cancelled or a deadline that moved, I remove its date entirely. It goes back to Later — still exists, still accessible, just not cluttering my today.

💡 Product tip: In Wednesday Calendar, swipe right on any task to postpone it to the next day — keep going and the full swipe applies instantly. Swipe left to delete. That's the entire gesture vocabulary, and there's nothing to memorize.

This step is about honesty, not optimization.

"The goal isn't a perfect list. It's an accurate one."

Photo by cottonbro studio on Pexels

Step 2: Pick one priority

Most planning advice tells you to prioritize everything. High, medium, low. Urgent vs important. Eisenhower matrices and quadrant analysis.

Here's a simpler rule: pick one thing.

Not the most urgent thing. Not the thing your boss emailed about. The one thing that, if you finish it today, makes the day feel successful.

Everything else is secondary. If you get to it, great. If you don't, tomorrow exists.

If picking one thing still feels impossible, use this fallback: which task has the nearest external deadline? Not one you invented, but one set by someone else — a client, a manager, a legal requirement. That's your priority until it's done. The ritual isn't about finding the perfect most important task. It's about committing to one and moving forward.

I set this as the first task in my list and keep moving. No color coding, no flags, no labels. It's the first row. That's enough.

Step 3: Capture what's new

By now, yesterday is handled and today has its anchor. The list is clean.

Now I dump any new thoughts. The thing I remembered in the shower. The favor I promised someone. The errand I can't keep putting off.

I type as fast as I can. No formatting, no priorities, no list assignment. Just raw capture into today's view. Hitting return clears the field and lets me type the next one — the keyboard stays open until I close it. Takes about thirty seconds for six or seven items.

There's one trap here: capture can expand to fill all available time. If you're past two minutes, stop. Close the keyboard. Those extra thoughts will still be there tomorrow. The ritual has a hard stop for a reason.

Once it's all out of my head, I scan once more. Anything that belongs on a specific date goes there. Anything that belongs in a specific list gets moved. But most of it stays right where it landed — in today, waiting to be done or moved to Later when I repeat this tomorrow.

Photo by cottonbro studio on Pexels

Before vs after

	Before the ritual	After two weeks
Opening the app	Felt like facing a hoard	Feels like clearing a counter
Deciding what to do	Dozens of small choices all morning	One look at the priority, then start
Time spent planning	Twenty-minute spirals whenever I opened the app	Five minutes, once, before work
What got done	Five small tasks, nothing that mattered	One meaningful thing, done
End of day	Couldn't say what I'd accomplished	Knew exactly what the day was

The difference isn't the number of tasks completed. It's the quality of attention.

"One meaningful thing per day instead of ten meaningless ones. That compounds fast."

Why five minutes works

The ritual works because it separates three cognitive acts that most planning tools smash together:

Reviewing is backward-looking. Did I do what I said I would? It's quick and binary.

Prioritizing is forward-looking. What matters most today? It's one decision, not forty.

Capturing is open-ended. What's new? It's creative, so it goes last, when my brain is already warmed up.

As Cal Newport writes in Deep Work, "To produce at your peak level you need to work for extended periods with full concentration on a single task free from distraction."

The ritual avoids attention depletion by batching all planning decisions into one five-minute block. Your brain processes yesterday, commits to today, and clears working memory — all before the real work begins. The rest of the day, your attention is free for execution, not triage.

There's a second cognitive principle at play: the Zeigarnik effect. Unfinished tasks occupy mental RAM. By reviewing yesterday and clearing the debris in step one, you release that cognitive hold. By choosing one priority in step two, you give your brain a single open loop to hold — not forty.

When you try to do all three at once — which is what happens when you open a raw task list and stare at it — you overload your working memory. You end up planning for twenty minutes and still feeling unsure.

Five minutes, in order, with a hard stop. That's the ritual.

How it maps to Wednesday Calendar's design

This ritual wasn't invented for Wednesday Calendar. I developed it years before I built the app. But when I designed Wednesday Calendar's two-axis model — time-based attention tabs on one axis, permanent list structure on the other — I realized the ritual was already using that same logic.

Step 1 cleans the attention axis. Tasks that need to happen today stay; everything else moves to Later or loses its date. Step 2 sets today's attention target — one task gets the spotlight. Step 3 feeds the capture pipeline. The Later tab is the release valve: anything that doesn't need attention today still has a permanent home. It's not deleted, not forgotten, just temporarily invisible.

The app and the ritual reinforce each other. The ritual tells you what to do; the app makes it effortless.

Adapting the ritual

Not every morning looks the same. Here's how the ritual flexes for different day types:

Day type	How the ritual flexes
Heavy meeting days	Skip step 2 — the calendar already set your priority. Spend the full five minutes on steps 1 and 3.
Deep work days	Step 2 is critical — pick the one task that needs uninterrupted focus and let it anchor your morning.
Errand days	Use step 3 to add location context — "pick up dry cleaning" becomes a place-based reminder.
After a vacation or sick day	Spend most of your time on step 1 — be aggressive about stripping dates. Most of what accumulated no longer matters or was already handled by someone else.

Making it stick

Two things made this stick after years of failed planning attempts:

Fixed time. I do it with my first coffee. The habit is anchored to something I already do, not a calendar alarm I'll snooze.
The app opens on Today. Wednesday Calendar launches on the Today tab every time, so my planning view is right there when I open it — zero navigation friction.

If you miss a day, don't double down. Skip the priority pick — just do steps 1 and 3 — and start fresh tomorrow. The ritual works because it's sustainable, not because it's perfect. A five-minute reset beats a twenty-minute guilt spiral every time.

The first week is the hardest. Your brain will resist the structure. It will tell you that these five minutes are wasted, that you could be doing instead of planning. Push through. By day ten, the resistance dissolves. By day twenty, skipping the ritual feels wrong — like leaving the house without your keys.

Try it tomorrow morning. Five minutes. Same steps. See how it changes the rest of your day.

The ritual doesn't require any specific app — a paper notebook works fine. But if you want to try it with the one I built around this exact workflow, Wednesday Calendar is a free download.

Wednesday Calendar on the App Store — tap a screenshot to open it.

Your First Post Title

Samson Sunny — Thu, 06 Aug 2026 07:03:24 +0000

Write your article here. Replace this with something about the
feature you shipped this week or a productivity insight aligned
with the TaskFlow mental model.