The Archaeology of Accumulated Files: How Documentation Debt Nearly Buried the Project
September 19–21
The system was working, but the documentation was drowning.
787 files scattered across 104 directories. Session logs in three different locations. 186 binary blog files mixed with development documents. The Jekyll infrastructure tangled with project documentation in the root directory.
Sound familiar?
This is what happens when you’re building fast and organizing later. Every session creates artifacts. Every experiment leaves traces. Every good intention to “clean this up next week” compounds into archaeological debt that makes finding anything a research project.
Friday afternoon, after the Great Refactor planning session, we faced a choice: push forward with implementation or spend the weekend organizing the foundation. The inchworm in me whispered the right answer.
Sometimes the most productive thing you can do is sharpen the saw.
The survey methodology
Before you can organize anything, you have to know what you have. I assigned Claude Code the role of documentation manager and it conducted a systematic survey of the entire docs/ tree.
Not just file counts — that would be meaningless. We needed to understand the archaeology of how the documentation had evolved:
- Which directories had become dumping grounds?
- Where were session logs actually living versus where they should be?
- What percentage of files were working documents versus finished deliverables?
- How much space was being consumed by binary assets that belonged elsewhere?
The results were sobering. 14% of all documentation files were cluttering the development root directory. Session logs existed in docs/development/session-logs/, docs/development/, and scattered in other locations with no clear pattern.
This wasn’t just untidiness. It was actively impeding archaeological research — the ability to trace decisions, understand context, and learn from past work.
Spotting the patterns
Organizing files feels like housekeeping but it’s really information architecture. How you organize documents shapes how you think about the work.
Having session logs scattered across multiple directories wasn’t just inconvenient. It was preventing us from seeing patterns across time. Blog material was getting lost because it lived mixed with working documents instead of being tagged and tracked.
The real cost of documentation debt is cognitive noise.
When finding last week’s planning notes requires grep searches across multiple directories, you stop looking for last week’s planning notes. When session logs don’t live in predictable locations, you stop referencing past decisions.
Information that’s hard to find becomes information that doesn’t exist.
The dev/YYYY/MM/DD convention
The solution wasn’t just reorganizing existing files — it was establishing patterns that would prevent future drift.
Starting today, all working files related to each day’s work go in dev/YYYY/MM/DD/: session logs, gameplans, agent prompts, planning documents, reports. Everything except actual code, which still lives where it belongs in the application structure.
We’ve also got a folder now called dev/active/ where the current day’s files can go, but once a file isn’t actively being used anymore it needs to be archived to the dated folder. This means I am also now systematically saving every artifact generated by or for any of my agents during a session, when in the past such docs were scattered between the local filesystem and wherever the web chat store their files.
You could call it session-based artifact co-location — ensuring that when you’re investigating how a decision was made or why an approach was chosen, all the relevant materials live in the same place.
Want to understand what happened during the Layer 4 investigation on September 18? Look in dev/2025/09/18/. All the session logs, gameplans, agent coordination prompts, and decision artifacts are co-located chronologically.
This pattern scales naturally: daily directories within monthly directories within yearly directories. No arbitrary file limits. No complex categorization schemes that break down under pressure.
The six-phase restructuring plan
Rather than spending a weekend moving files randomly, we developed a systematic methodology. Six phases, 3.5 hours total, with comprehensive backup and verification at each step.
Phase 1: Foundation Architecture — Create clear directory hierarchy separating public, internal, and archived documentation
Phase 2: Session Log Consolidation — Centralize all session logs with chronological organization optimized for archaeological research
Phase 3: Development Directory Restructuring — Separate current work from historical documents
Phase 4: Architecture Documentation — Optimize architecture docs with decision tracking
Phase 5: Asset Management — Organize 186 binary files with size and naming guidelines
Phase 6: Navigation Enhancement — Create master navigation system with role-based entry points
The methodology included explicit zero data loss protocol with git commits at each phase completion, verification checksums for moved files, and rollback plans for every step.
Optimizing for all the archaeological research we have to do
One of the most valuable outcomes was optimizing for archaeological research — the ability to trace how decisions evolved over time.
Session logs now live in chronological organization: docs/archives/session-logs/2025/09/ with monthly index files. Blog draft identification happens during session logging. Cross-references between related sessions get captured systematically.
When you’re debugging an architectural decision six months from now, you want to find not just the final choice but the discussion that led to it, the alternatives that were considered, and the context that made the decision feel obvious at the time.
Documentation systems that support archaeological research become compound valuable over time. Systems that don’t become archaeological debt.
The value of boring work
This kind of systematic file organization feels like administrative work that doesn’t advance the core project. It’s tempting to skip it in favor of “real development.”
That’s exactly backward thinking.
Proper information architecture becomes more valuable as the project grows. Every session that creates artifacts in predictable locations. Every decision that gets captured with its context. Every pattern that gets documented systematically.
The time you spend organizing information systems gets paid back with interest every time you need to find something, understand something, or explain something to a new team member (or future version of yourself).
Session logs as institutional memory
The real insight came from recognizing session logs not just as progress tracking but as institutional memory for a solo developer with AI assistance.
Each session captures not just what got done but how it got done, what was learned, what didn’t work, and why certain approaches were chosen. This becomes critical context when you’re working with AI agents who don’t persist memory between sessions.
When you brief a new Claude Code agent on a task, you want to point them to the relevant session logs that contain the context, the decision history, and the lessons learned. That only works if session logs are organized predictably and tagged appropriately.
Weekend discipline
Saturday morning brought the urge to push forward with GREAT-1 implementation. The Great Refactor plan was ready. The path forward was clear. Why not start immediately?
The reason is that the inchworm protocol applies to information architecture just as much as code architecture. You don’t build on an unstable foundation, even when the foundation work feels less exciting than the construction work.
Three hours of systematic file organization this weekend will save dozens of hours of “where did I put that document” searching over the next few months.
A meta-lesson about solo development
Traditional software development practices assume team contexts with shared institutional memory, standardized tooling, and natural knowledge transfer through code reviews and planning meetings.
Solo developers with AI assistance need different patterns. Your documentation system is your institutional memory. Your file organization is your knowledge management system. Your session logs are your onboarding documentation for future agents.
When you’re the only human brain responsible for remembering how everything connects, systematic information architecture becomes infrastructure, not overhead.
The project can’t outgrow good organizational habits. But it can definitely be suffocated by bad ones.