Reorganising folders by concern made one agent 10x faster

Capability vs setup: the gap that breaks the work

The piece opens on a deliberate contrast. An AI designed a vaccine against coronaviruses nobody has caught yet, while the author's own agent spends nearly two minutes opening wrong files to fetch an old brief. His point: the gap between what an AI can do and what your setup lets it do is what makes or breaks a workflow.

Nobody builds the mess on purpose. Folders pile up "for how I think", and the agent gets lost inside a structure shaped for a human.

The keeper is the reframe. When an agent trips on easy retrieval, fix the scaffolding around it before reaching for a stronger model. Scaffolding here means the folder structure and maps the agent reads to find its way, separate from the agent's own smarts.

Why folders built for you fail an agent

He filed by content type — articles, research, assets, strategy — because he thinks in categories and his brain cross-references automatically. An agent doesn't. Ask it to plan a launch and the context lives in strategy notes, brand guidelines and past launches scattered across folders, so it searches everywhere every time, blind to which draft is current and which is archived.

His fix is to organize by concern: group files by the job they serve (Brand System, Editorial Strategy, Promotion), not by file type, so related work sits together and the agent stops crossing boundaries. This is the load-bearing move. The index and the numbering only support it.

In finance-ops terms it's the chart-of-accounts rule: you file by function, not by document type, so whoever reads it finds a whole process in one place. A well-run shared drive follows the same instinct — organize for the reader, not the filer.

What the capability actually burns on

He timed five common tasks. Finding the current article brief took 7 files opened and 2:00. Brand colours: 5 files, 1:12. A launch's promotion strategy: 3 files, 0:34. The agent kept grabbing archived versions, and worse, stopped to ask which file to use when the context should have answered.

Same behaviour on every model he tried, which is what rules the model out as the cause. The number that matters isn't the "10x" headline — that's the single best case, task 1 going from 2:00 to 0:10. It's that most of the agent's capability was being spent on navigation before the real task even started.

Treat the figures as directional: five tasks, one author, self-timed, no control group. He says as much himself.

The fix: one concern per folder, a map at the root, numbers for order

Three rules working together. One folder per concern. An INDEX.md — a short hand-written map at each major folder's root listing the subfolders, the canonical files, and a "Where To Go" starting point — which the agent reads first, so it knows what it's holding before it touches anything. He calls it "a soft approval gate: the agent isn't allowed to start work until it knows what it's working with."

Then numbered folders (01.Brand System, 02.Editorial Strategy) so read-order is explicit instead of alphabetical, with archived material in a 06.Archived that the agent skips by default.

The map itself took three drafts. A 40-line full listing was too much to parse on every read, a 15-line one was too thin. It landed on subfolders plus canonical files plus where to start. It is, in PKM vocabulary, a machine-facing MOC (Map of Content): the same curated-doorway idea, written for the agent's first read instead of yours.

The anti-patterns: where more structure makes it slower

The two mistakes he made are the reason to trust the fix. Putting an INDEX.md in every subfolder made the agent spend its time reading indexes instead of working, so he kept them only at major-folder roots.

And nesting structure inside structure (two levels became five) forced the agent to parse several indexes and numbering sequences to reach a single file. "Depth is the enemy of fast lookup, and most reorganizations add depth thinking it's precision." Two software-world rules say the same thing: flat beats nested, and the smallest interface that does the job wins.

His governing rule is a fit-check worth stealing. Add structure only when the agent gets lost, and only enough to fix that one problem. Building infrastructure before the agent shows any confusion is over-engineering.

The catch: retrieval changes the maths

The honest counter-take sits in what his agent didn't have. It had no retrieval layer, so it walked folders blind, and that's exactly why a map bought a 10x. If your agent already searches semantically or over a full-text index, it doesn't wander the same way, and the headline number shrinks hard.

It's still additive rather than redundant. Most setups have paths where the agent opens specific files by hand rather than searching, and a short "Where To Go" map at those roots — plus an explicit "skip archived by default" — trims that hand-navigation and encodes what to ignore.

His 5-minute test settles it cleanly: time three real tasks your agent does often and count files opened before the right one. Anything over 30 seconds or three wrong files points at a folder worth a map. Measure before you reorganize.

Vocabulary

• organize by concern — group files by the job they serve, not by file type
• INDEX.md (root map) — a short hand-written 'start here' map at a folder's root
• soft approval gate — the agent must read the map before it's allowed to start work
• scaffolding — the folder structure and maps around the agent that guide navigation
• MOC (Map of Content) — a curated doorway note that points you into a topic

If you're building — what to watch for

• Measure before you restructure: time three tasks your agent runs often and count the wrong files it opens first. Over 30 seconds or 3+ misses is the signal; below that, leave the folders alone.
• If your agent already has a retrieval layer (embeddings or full-text search), discount the headline gain — the map only pays off on the paths where the agent still opens files by hand.
• Add structure only when the agent gets lost, and only enough to fix that one problem. Infrastructure built before the confusion appears is over-engineering.
• Depth is the enemy of fast lookup. A map at every subfolder makes the agent read indexes instead of working; keep them at major roots only.
• Mark archived material explicitly so the agent skips it by default — grabbing a stale version reads as a model failure when it is really a filing failure.

Reading it critically

• "10x" is the single best case (one task, 2:00 to 0:10); across his five tasks the typical span is nearer 3-5x.
• N=5, one author, self-timed, no control group — directional at best, and he admits it.
• The vendor wrapper (the "$30 stack", the vaccine hook, the follow-CTA) is framing, not evidence. Keep the mechanism, drop the pitch.
• It doesn't fix sync or stale-copy problems — an old version on another device still reads as current.
• He concedes pure-code or data-heavy setups may need different organizing principles entirely.