The Problem
I keep most of my working knowledge in a large markdown vault — years of notes, project docs, research. Over time the folders had drifted into two competing organizing schemes, laid down in different months and never reconciled. The same kind of document had two plausible homes, and one project was scattered across three different folders. Clicking through it by hand had stopped being obvious, which is the whole point of a folder structure.The Approach
I pointed Claude Code at it and made it diagnose before moving anything — plan mode, no edits until I’d seen the map. Two of the design calls were mine and worth stating plainly. First: kill the “active” status folder entirely. Status-as-folder is a trap — things go in and never leave, because nobody remembers to empty it. State like that belongs in a metadata field you can query, not a directory you have to groom. Second, and the one I cared about most: cluster the loose files by lineage, not by filename. A filename prefix is a guess about what a file is. Its real home is wherever the work session and the notes that produced it point — so trace each file back to its originating session before deciding where it goes. I also had Claude build two small pieces of infrastructure so this wouldn’t silently rot again: a startup check that flags files left sitting too long, and an assisted routine that proposes a home for each stale file and waits for my approval before it moves anything.What Happened
The lineage rule earned its keep right away. Claude’s first instinct was to drop a cluster of files into an existing folder because the names matched — and the lineage trace showed they were a different body of work that just happened to share a keyword. They went somewhere else. Then the mess. After moving the folders, Claude ran a bulk find-and-replace to fix the now-broken path references, and it cheerfully rewrote the provenance notes it had just written — the little “moved here from the old location” breadcrumbs — into circular nonsense that pointed at the new location instead of the old one. I caught it on the verification pass, when I had it grep for leftover references and the numbers didn’t smell right. We reverted those by hand. Partway through, looking at how one function’s material was strewn across three places, I changed the target structure mid-flight and we re-ran the consolidation against the cleaner shape.What I Learned
A path string isn’t self-describing. “Points here” and “used to live here” look identical to a find-and-replace, and an agent will flatten the distinction unless you tell it which documents describe the present and which describe the past. The broader thing, again: the craft in this kind of work is the directing and the catching, not the typing. Claude did the moving. What I added was the two judgment calls up front and the one error I caught before it shipped.Drafted by my Claude from our working session. I approved it before it went up.