strategy · 2026-05-20 · dare.co.uk filing-system framework

Filesystem spine — no spine, some spine, complete spine + the HTML sidecar question

A recurring issue Dan named today: filesystems that mix categories, statuses, entities, and events at the same hierarchy level. Three levels of spine + when HTML sidecars help / hurt. Generalized from this morning's insurance-claim folder audit; applicable to audrey-archive, vehicle receipts, client deliverables, anywhere file volume grows past ~50.

TL;DR

• Three spine levels: no spine (flat list of disparate concepts), some spine (partial nesting that breaks at the next category), complete spine (Insurer → Policy → Claim → numbered-section nesting). Most household filesystems start at no-spine and never climb.
• The recurring failure mode: mixing categories (Contents), statuses (Submitted/Excluded/Missing), entities (Loan Depot), events (Payouts), and objects (Shed Structure) at the SAME hierarchy level. Each adds a "spine break."
• HTML sidecars buy a lot but cost something: they turn a file browser into a cockpit, but introduce two sources of truth. Rule: use HTML sidecars when file count > ~50, multi-stakeholder, or time-sensitive. Skip below that.
• Sidecars work only on complete-spine filesystems: rendering a cockpit on top of a no-spine tree just photographs the chaos in HTML.

The recurring issue Dan named today

Looking at Dan's 4TB drive insurance-claim folder this morning:

The three levels of spine

Level 1 — No spine

Flat list at the top level. Folders are a mix of categories, statuses, entities, events, and objects. Nothing nests; everything is one click from the root. Common signs:

• Multiple folders with similar names ("Submissions" + "Submitted Property Contents" + "Status")
• Folders that describe a STATE rather than a class of thing ("Excluded", "Missing", "Submitted")
• Folders that describe a counterparty ("Loan Depot") next to folders that describe a money flow ("Payouts")
• No README, no index, no orientation file — you have to remember what each folder holds

Trade-offs. Fast to start. Familiar pattern (the Desktop "just dump it here" pattern at scale). Survives ~20 files; breaks past ~50. Future-you will not remember why you made those choices.

Level 2 — Some spine

One or two levels of nesting around a clear top-level concept (insurer → policy, or year → month), but inside the nested folder the no-spine pattern re-emerges. Common signs:

• Top level is clean, deeper levels are flat
• "I had a system but it got messy" — almost always means some-spine, not no-spine
• Pattern: year/2026/ at the top is great; everything inside 2026/ is the old chaos

Trade-offs. Better than no-spine because new top-level entries fit cleanly. But the second-level chaos compounds: every n-th claim repeats the same flat-list-of-disparate-things pattern, so reorganizing is N× the work.

Level 3 — Complete spine

Every level of nesting answers a different conceptual question. Each folder name says "I am a kind of X" where X is consistent within its level. Common signs:

• Numbered prefixes (10-, 20-, 30-...) — alphabetical sort = logical order
• Status is metadata, not folder structure
• Each level answers one question: insurer? policy? claim? section?
• An 00-index.md or README at each significant root tells you what's here
• An 99-inbox/ at the leaf where new files land before being filed

Trade-offs. Most work to design (~30 min for an insurance claim). Easiest to navigate, hardest to outgrow, supports tooling on top.

Eight principles for climbing to complete spine

1. Numbered prefixes (10-, 20-, 30-...). Alphabetical = logical order. New categories slot in between existing ones (15- goes between 10- and 20-) without renaming everything.
2. Per-event isolation. The same property can have multiple claims; mixing them is the most common future-pain. claim_<id>_<date>_<cause>/ as the unit of isolation.
3. Category ≠ status. "Submitted / Excluded / Missing" aren't categories of contents — they're states. One contents/ directory; state in _state.json or filename suffix. Anything that's a STATE goes into metadata, not folder structure.
4. Filename convention: <YYYY-MM-DD>_<vendor>_<purpose>.pdf. Sortable chronologically, scannable for "what is this."
5. Inbox at the leaf. 99-inbox/ is where new scans land before being filed. The pipeline picks up from there.
6. Auto-generated cockpit at each significant root. 00-index.md (or 00-cockpit.html) summarizes the claim — totals, outstanding actions, deadlines. Regenerated from filesystem state + structured metadata.
7. Entity folders where it makes sense. 30-invoices/tree-removal/, 80-loan-servicer/loan-depot/ — group by the thing-being-paid-for or the party-being-dealt-with. "Loan Depot" deserves its own subfolder under 80-loan-servicer/, not a top-level slot competing with the claim itself.
8. Status as file, not folder. If you have a folder called "Status", it's either a markdown file (70-status.md at the claim root) or it's metadata in a JSON sidecar. Status changes; folder names shouldn't.

The HTML sidecar question — when does it help?

The bigger move beyond "complete spine" is layering a generated HTML cockpit on top of the filesystem. The pa.gf.cx claim-cockpit sketch is exactly this — a per-claim landing page (00-index.html) generated from the filesystem state + JSON sidecar + analyst output, surfaced behind CF Access.

This is high-leverage but not free.

Where this applies beyond insurance

Migration path — for today's insurance claim

Concrete steps to climb from no-spine to complete-spine in ~30 minutes:

1. Create the destination tree: ~/Drive4TB/insurance/homeowners/liberty-mutual/policy_H3V-281-240408-75/claim_046414618_2021-07-29_storm/
2. Create the numbered sections: 10-correspondence, 20-estimates, 30-invoices/{tree-removal,electrician,dumpster,structural}, 40-payouts, 50-contents, 60-structure/{shed,fencing,kennel}, 70-photos, 80-loan-servicer/loan-depot, 99-inbox
3. Move existing folders into slots:
   • Scans → 99-inbox/ (raw incoming; pipeline will consume from here)
   • Loan Depot → 80-loan-servicer/loan-depot/
   • Payouts → 40-payouts/
   • PA Insurance → this IS Liberty Mutual; rename to 00-policy-docs/ or merge into root
   • Missing + Submitted + Excluded Property Contents → all collapse into 50-contents/ with state in _state.json
   • Status → 70-status.md at the claim root
   • Submissions → if it's correspondence, into 10-correspondence/; if it's the same as Payouts, merge into 40-payouts/
   • Contents → 50-contents/
   • Shed Structure → 60-structure/shed/
4. Generate the first 00-index.md from the existing claim sidecar (~/Code/home-projects/pa/home-insurance/claims/_bulk-source/2026-05-20-bulk-scan-19-pages.json) — pulls insurer, total paid, outstanding amounts, deadlines, action ranking
5. (Optional) Generate the HTML cockpit alongside 00-index.md if you want the pa.gf.cx surface to mirror the filesystem

The closing aphorism

A folder is a promise about what's inside. A no-spine filesystem is a promise broken with every new folder. A complete-spine filesystem promises the structure will absorb the next file. The cockpit on top is the receipt that says: I kept the promise.