More than I expected. Most of it wasn’t writing new logic — the mandates and templates already existed. It was deciding, line by line, what belonged in a public starter kit and what belonged only to my own archive.
Some of the most useful notes in my own archive are useful because of their format, not their content. A lab-trend note that flags a value as optimal, borderline, or out of range using a consistent set of markers is a good design regardless of whose bloodwork is in it. The specific values are mine. The convention is not.
The first pass at the starter kit blurred that line. I copied over a few reference notes with plausible-looking example content — a glossary entry on a health topic, a renewal-rule note with invented dates — on the theory that a filled-in example teaches faster than a blank one. It doesn’t, not here. That content was specific to a household that doesn’t exist, would need to be un-learned before anyone typed a real fact into the same note, and taught nothing about the mechanism itself.
The fix was to ship the four reference templates as format only: the table structure, the flag convention, the callout style, a sourcing rule that says which claims need a citation and which don’t. No invented lab values, no invented statutes, no invented medications. The actual content of any reference note is supposed to come from whatever the person using the kit files and asks about — that’s the whole point of having an assistant build it up over time instead of a person filling out a form once. A pre-written example doesn’t demonstrate that process; it just hides it behind a plausible-looking fake.
A completely empty repository is its own kind of unhelpful. The first real decision anyone has to make with a document archive is what the top-level categories even are, and staring at an empty folder while trying to answer that from scratch is a bad first five minutes.
So the archive template ships with its category folders already created — Health, Identity, Legal, Finance, Home, and the rest — each holding a one-paragraph note that states the placement rule for that category and links back to the rulebook. Someone can read twelve short notes in ten minutes and understand the whole taxonomy before they’ve filed a single document. Renaming or deleting a category later is one line in that rulebook, not a redesign.
That’s a different kind of seeding than the reference-template question above. A folder name and a placement rule are structure. A lab value or a legal deadline is a fact about a specific person. The kit seeds the first and refuses to guess at the second.
The obvious way to bootstrap a new install is to point an agent at an existing pile of documents and say “sort all of it.” I tried writing the setup instructions that way and then talked myself out of it.
Two separate problems. The practical one is that reading, classifying, and filing a few hundred documents in one sitting spends a large share of a session’s budget on a single run, with no natural place to stop and check the work. The less obvious one is that a long unattended pass is exactly where a filing mistake or a bad extraction is most likely to slip past without anyone noticing, because there’s no natural checkpoint where a person actually looks at what happened.
The setup guide asks for the opposite: drop a few dozen files into an inbox folder, ask the assistant to sort that batch, look at what it did, then drop the next batch whenever you’re ready. There’s no deadline to have the whole archive filed. The system is built to accumulate correctly over weeks of ordinary use, not to be loaded in one afternoon and then hoped it’s mostly right.
The first version of the kit lived in a shared Google Drive folder — a zip file and a set of docs I could hand to the two people who’d actually asked for it. That was fine for two people. It meant every future update was a re-share, and it meant anyone else who wanted to try it needed to know me first.
Moving it to a public git repository under an MIT license changes the actual audience from “people I send a link to” to “anyone who finds it.” That’s a bigger decision than it sounds like, because a public repo gets read by people with no context on why a rule exists, which means every instruction in it has to justify itself on the page rather than relying on a shared conversation to fill in the gaps. Rewriting the setup guide for that audience caught a handful of places where a rule was stated but the reasoning behind it wasn’t, which is worth doing even for something that never leaves a Drive folder.
The two skills that do the actual filing and auditing work were originally distributed as built packages — a zip with a manifest and a script inside, ready to install. That’s a reasonable way to hand something to two people. It’s a bad thing to check into a public repository, for the same reason any built artifact is a bad thing to commit: it goes stale the moment the source changes, and nothing forces the two to stay in sync.
The repo now carries the plain source for each skill — the instructions and the one bundled script one of them needs — and a setup script builds the installable packages locally when someone runs it. That’s a small change, but it’s the same discipline any codebase applies to compiled output, applied to something that’s usually hand-packaged and forgotten about.
Not every constraint in a project like this comes from the design. Partway through moving the kit into its own repository, I ran into an environment limit that had nothing to do with the content: the sandbox I was working in couldn’t reach the repository’s filesystem path at all for running shell commands, even though it could read and write individual files there directly.
The practical effect was that every file in the new repository got created through direct file writes rather than a shell script, and the actual git add / commit / push had to stay a manual step handed back to me rather than something run automatically at the end. That’s a minor inconvenience for a one-time setup, but it’s worth naming for the same reason the unattended-run problem was worth naming: a system’s real constraints aren’t only the ones you designed on purpose. Some of them are just where the tooling stops, and the honest thing to do is say so rather than pretend the automation went further than it did.
The finished layout:
File_Archive_Template/
Organization_Philosophy.md the rulebook: naming, dating, placement
Health/, Identity/, ... category skeleton, one note per folder
Unsorted/, Trash/ inbox and pending-deletion folders
Living_Reference_Template/
00_README...md architecture and conventions
_Reviewers/ full mandate per scheduled review
_Skills/ full mandate per on-request skill
_Templates/ blank dashboard and reference notes
skills/
file-renamer/, file-archive-audit/ skill source, not built packages
setup.sh, setup.ps1 asks two questions, builds the rest
SETUP_GUIDE.md, BOOTSTRAP_PROMPT.md
Running the setup script asks where the two template folders should live, copies them there without touching anything already in place, and builds the two installable skill packages from source. Everything past that point is the setup guide: adapt the rulebook, open the vault, hand the assistant the bootstrap prompt, and start dropping in real documents a few at a time.
You need a cloud-synced folder your assistant can read (the kit assumes Google Drive), Obsidian for the vault, Claude API access for the scheduled reviews, and git. Then:
git clone https://github.com/espaillato/DriveOrganizerStarterKit.git
cd DriveOrganizerStarterKit
./setup.sh # ./setup.ps1 on Windows
The script asks two questions (where the File Archive folder should live, and where the Living Reference vault goes), then copies the templates into those locations without touching anything already there and builds the two .skill packages from source. SETUP_GUIDE.md documents the same steps by hand if you’d rather not run the script.
From there: adapt Organization_Philosophy.md to your own categories, open the vault in Obsidian, install the two skills, and hand the assistant the prompt in BOOTSTRAP_PROMPT.md. Then start dropping documents into Unsorted/ a batch at a time. There is no target for filing the whole archive at once. As section 3 covers, it is meant to accumulate over weeks of ordinary use, with the scheduled reviews keeping it current from there.
None of this changes what the system does. It changes who can pick it up without having talked to me first, which was the actual point of writing the case study in the first place.
]]>I added a decision layer on top of it. Source documents stay in the archive. Short dashboards describe the current state of a few important areas. Deeper reference notes hold the supporting detail. Scheduled reviewers check both the facts and the recommendations, while a separate maintenance process keeps the underlying files organized and the summaries current.
This post describes that method as a sanitized case study. The personal data is not the reusable part. The reusable part is the shape of the system, the division of responsibility, and the rules that keep a concise summary from becoming either stale or enormous.
A well-organized archive answers retrieval questions: where is the latest statement, which document superseded the old one, what was the result of a prior appointment, when does an identification document expire. Those are valuable questions, but they begin with someone remembering to ask.
The more useful questions cut across documents:
Answering those directly from a large archive every time is possible, but inefficient. It repeats extraction work, produces long answers, and makes it difficult to distinguish a source fact from a current interpretation of that fact. The system needed a small current-state layer that could be read in minutes and checked against the evidence behind it.
The result is less a second archive than a set of maintained views over the first one.
The system has three layers:
The flow is intentionally one-way at the evidence boundary:
source documents -> extracted facts -> current dashboard -> review -> action or question
A review may correct an extracted fact after checking the source, but a polished dashboard does not become evidence merely because it is concise and confidently written. The source remains the source.
The archive in this case contains several hundred documents across a dozen broad categories. Only a subset needs a living dashboard. Most documents are point-in-time records that can be filed once and left alone. A tax return from several years ago does not need a monthly rewrite. A current financial allocation, medication list, renewal date, or unresolved estate-plan item might.
That distinction keeps the maintained surface small enough to be credible.
An early design decision was to store the Living Reference as Markdown and use Obsidian as its primary view.
Markdown keeps the underlying material portable. The notes are plain text, readable without a particular application, easy to version and search, and straightforward for scripts or review tools to process. If the viewing tool changes later, the information does not need to be extracted from a proprietary database first.
Plain text alone is not a particularly good daily interface, though. Obsidian adds the human-facing layer: navigation, backlinks, cross-note links, headings, tables, search, and a graph of how related information connects. A dashboard can link to its detailed history, a current action can link to the reasoning behind it, and a shared definition can support several notes without being copied into each one.
That combination matters because the system has two audiences. Automated processes need predictable, tool-friendly text. A person needs to move through the information naturally and understand why one item connects to another. Markdown serves the first requirement without obstructing the second; Obsidian makes the same files comfortable to use without taking ownership of them.
The design is therefore not “an Obsidian database.” It is a portable Markdown knowledge base with Obsidian as a particularly useful reader and navigator. The distinction is small until the day a tool changes, at which point it becomes the whole portability plan.
Each dashboard is meant to answer, quickly:
Everything else has to justify its place.
The first versions accumulated chronological narratives, definitions, old decisions, and long explanations inside table cells. All of that was relevant, but relevance is not the same as usefulness on the main page. A dashboard that takes twenty minutes to read has stopped being a dashboard.
The working rule became: conclusions and current actions stay in the dashboard; evidence, derivations, and history move to linked reference notes. A line such as “confirm whether this account still matches the household allocation” belongs in the dashboard. The account history, allocation calculation, and reasoning behind the concern belong one link away.
The same rule applies to update logs. A log is useful evidence that a note is maintained, but an unlimited log makes every future read more expensive. Recent entries stay in the dashboard; older entries roll into a history note. Nothing is deleted, and the current page does not have to carry its entire biography around with it.
Each current fact links back to a real source document when one exists. The link is not decorative. It makes the summary auditable and gives a professional the full context without requiring a second search through the archive.
The reference layer handles material that is useful but too large or too stable for the dashboard:
This separation also makes corrections less confusing. A source value, a calculated trend, and a recommendation are three different kinds of claim. When they live in different places, a correction to one does not silently rewrite the others.
There is a practical trust rule underneath this: a summary should say which sources were read and which visible sources were not. “Current through this date based on these documents” is a checkable statement. “Current” by itself is mostly optimism.
The system separates mechanical maintenance from strategic review.
The frequent maintenance loop handles work with a mostly deterministic answer: naming and placement, missing links, stale metadata, malformed tables, a newer source document that has not been reflected in a dashboard, or an unresolved question waiting in a note. It runs often because the checks are comparatively cheap.
The slower review loop handles questions that require judgment: whether a financial strategy still matches its constraints, whether an estate plan still covers the risks it was designed for, whether a health priority should change, or whether a renewal rule has changed. Those reviews run less often and use a written domain mandate.
This division prevents the filing process from casually becoming a financial, legal, or medical reviewer merely because it noticed something while moving a file. It also prevents the specialist review from spending most of its time fixing filenames and broken links.
The two loops communicate through inline flags placed next to the relevant text. A person can leave a question or correction in a note. A maintenance pass can leave a question for a named reviewer. The marker remains until the named party resolves it, and duplicate checks prevent the same open issue from being added again on every run.
That mechanism is described in more detail in the review-council post. The important point here is that the communication lives with the artifact, not only in a chat transcript or run report.
Each domain review has a written mandate: what it owns, which files it reads, what standards it applies, what it may change, and what it must never execute.
The reviewers are expected to do more than fact-check. They reconsider whether the current recommendation is still sensible given the full set of constraints. They also check the combined effect of several recommendations. Five reasonable changes can still add up to one unreasonable plan.
The output follows a simple contract:
That last boundary matters. The system can prepare a better discussion with a professional and make omissions easier to spot. It does not place trades, change beneficiaries, submit government forms, prescribe treatment, or otherwise confuse analysis with authority.
An editorial reviewer has a different job. It does not make domain judgments. It keeps dashboards short, relocates historical narration, checks terminology and links, and makes sure a useful note has not gradually become a tome.
One operational issue appeared only when the reviews ran on a schedule. The frequent maintenance task sometimes needed the standards used by a specialist reviewer, but the review personas originally lived inside task-specific instructions that unattended runs could not reliably access because each reviewer runs in their own sandbox.
The first fallback was a short persona summary in a shared note. It kept the task from failing, but it created two versions of the standard: a full mandate for the specialist and a condensed one for everyone else. They could drift, and a shallow answer could look more complete than it was.
The fix was to externalize the review context into ordinary, versioned reference files that every relevant process can read. Each reviewer now has a mandate document, and the mechanics shared by all reviewers live in one shared protocol. Scheduled tasks point to those files instead of carrying private copies of the rules.
This is a small design change with a useful general lesson: if a recurring process depends on context, that context is part of the system’s data. It should be stored somewhere accessible, reviewable, and versioned, not hidden inside the configuration of the one task that usually uses it.
Externalizing the context has a second benefit: it makes the setup model-agnostic. Everything a reviewer needs is in the documents, so the instruction is just “read your persona document and do what it says.” I have started running the same review on different models to see how their suggestions differ. It also allows a split by capability: the frequent maintenance loop can run against a small local model, while the specialist reviews run on higher-capability ones.
Publishing the method is not the same as publishing a sample of the real system with a few names changed.
A safe case study removes or generalizes:
The sanitized version keeps the schema, rules, workflow, and failure modes. Example data should be synthetic from the start rather than redacted after the fact. Redaction is easy to get almost right, which is not a particularly reassuring privacy standard.
There is also a product boundary here. A reusable starter kit can operate entirely on a person’s own storage and notes. A hosted service that ingests financial, health, identity, and legal documents takes on a much larger security and compliance problem.
The smallest useful version does not need software beyond a file store and a note system. It needs a good template and a disciplined setup process.
I would package it as:
The first implementation should be guided and local. A handful of pilots would show which rules generalize, where setup remains too dependent on the original archive, and whether the dashboards change decisions often enough to justify maintaining them.
The system already measures its own activity reasonably well: files processed, notes updated, reviews completed, open markers found. Those are operational counts, not outcomes.
A productized method needs a smaller set of measures tied to usefulness:
The last measure should remain close to zero. Convenience has a habit of volunteering other people’s privacy as its first optimization.
The useful product here is not a pile of personal documents and not a chatbot pointed at a folder. It is a maintained path from evidence to a current summary, from that summary to a review, and from the review to a decision someone can inspect before acting. The documents will vary. The path does not have to.
]]>This post is about the failure that made that obvious, and the authority model I built to fix it. The pattern isn’t specific to a document archive, so it’s written to lift and adapt.
A large sweep had more to cover than fit in one pass, so the work got split across several parallel subagents. Each one got a slice of the checklist and a short instruction: apply the rules, report back. One rule mattered more than the others. Certain findings couldn’t just sit in a report; they also had to be written as a standing marker at the spot they applied to, so the next run — or I — would see them without digging through old chat logs.
That rule was clear in the source instructions. It didn’t survive the handoff. Each subagent was told, in effect, “list the findings you’d flag for a human in your report.” Reasonable-sounding, and it dropped the second half of the rule: also write the marker. The subagents did good work otherwise and the reports were accurate. The markers just never got written, because the instruction that would have produced them got summarized away between the rulebook and the delegation.
Nobody chose to skip the step. It fell through a summarization gap that nothing was checking.
The easy reading of that bug is that the subagents slipped up. The more useful reading is that the setup never divided responsibility in the first place. It divided labor. Three processes ran instead of one, but the authority over what each could do and had to do was still a single blob, re-derived and re-summarized on every handoff.
That’s the distinction that matters: parallelism makes copies of one undivided authority. It doesn’t split responsibility. A team needs each class of decision to have an owner, needs a delegated task to carry its obligations with it, and needs a finding to be cleared by its owner rather than by whoever reaches it first. Without that, five agents instead of one is five shots at the same mistake, not five narrower areas of accountability.
The fix is unglamorous: the full obligation travels with the delegation, word for word, every time. Not a summary, not a paraphrase, not a pointer to a document. “Follow the rules in the shared doc” is not the same as restating the rule in the subagent’s instructions. The first survives summarization badly. The second has nowhere to lose the requirement, because the rule and the instruction are the same text.
The fix is a three-tier authority manifest, written out in full at the top of every delegation instead of referenced by name.
AUTO — do it without asking, then report what you did. For mechanical actions only: no judgment, no ambiguity, same input always gives the same right output. Formatting fixes, applying a documented convention, moving something within a boundary that was never in doubt.
FLAG — stop, write the question at the spot it applies to, and do nothing else until it’s answered. For anything that needs judgment: a classification that could go more than one way, a change that alters what something appears to mean, anything that would require a new standing rule. Writing the flag is the action. There’s no version of this tier where the agent also does the thing “just in case,” however confident it is.
NEVER — a short, absolute list, no exceptions no matter how good the reasoning sounds at the time. This tier exists to survive a persuasive edge case. Keep it short enough to memorize and specific enough that applying it needs no judgment.
The part that fixes the bug: every subagent dispatch restates this manifest — the specific AUTO/FLAG line for that task — as literal text in its own instructions, not a citation. Pointing an agent at a shared document by name is the exact thing that failed once already. The fix isn’t to trust the reference more. It’s to not depend on a reference surviving summarization at all.
An authority model is only as good as where it draws its lines, and the first version drew this one too conservatively to live with. The original rule was blunt: anything already in its intended place needed a confirmation before it moved, anywhere. Safe, but it meant routine reorganizing — splitting a folder into subfolders, renaming a folder once its contents outgrew the name — raised as many questions as a genuinely ambiguous reclassification. Ask about everything and the answers turn into rubber stamps, which defeats the point of asking.
The fix was a narrower line that’s still safe. Restructuring within a top-level category that’s already correct is AUTO; a subfolder split or a rename doesn’t change what category something belongs to. Moving something across a top-level boundary is FLAG; that’s a reclassification, not a tidy-up, however good the new spot looks. Both are “moving a file,” but they answer different questions, and only one needs me in the loop.
The test isn’t “did something move.” It’s “after this move, is it a fundamentally different category of thing.” A rename that changes apparent ownership or purpose is a reclassification even if the file never leaves its folder. A restructure that stays inside the same top-level category isn’t, even if every file in it got renamed and re-nested.
Once FLAG items are required, it’s easy to treat “did every ambiguous item get a flag” as the whole verification job. It’s half. The other half is the AUTO side: for every action a subagent called routine, check afterward that it actually stayed inside its authorized boundary, not just that the report said so.
Skipping this half is the more dangerous choice, because the failure is invisible. A missing flag looks incomplete — there’s a gap where an answer should be, and someone notices. An action that was carried out and reported as routine, but actually crossed a line that needed a confirmation, looks like every other handled item in the report. Nothing about it says “check me.” The only way to catch it is to re-derive, independently, whether the boundary held — not to take the report’s word for it.
In practice: before folding a subagent’s work into the record, re-check every move it labeled routine against the rule it was following, using the real before-and-after state rather than the subagent’s summary of it. If something crossed a line it shouldn’t have, that’s not a quiet fix in the log. It’s a finding on its own, because the action already happened and editing the report doesn’t undo it.
One more case needs its own rule, because it’s the one most likely to feel like a fair exception: mid-task, an agent proposes a plausible new standing rule — not a decision about one file, but something that would become “how we always do this” if nobody pushed back.
The answer is the same however solid the reasoning looks: no agent adopts a new standing rule on its own. It goes through the same gate as any other judgment call — proposed, reviewed, written into the rulebook only after a human has signed off — and only then do future runs rely on it. A one-off mistake affects one file. An unapproved rule that becomes precedent affects every future decision that matches it, for as long as it takes someone to notice it was never approved.
This sits at the same level as the rule against permanent deletion without review. Both are about the same thing: not letting one pass’s judgment turn into permanent, hard-to-reverse state without a checkpoint.
None of this is specific to a document archive. The same shape fits a software team putting several review agents around a shared codebase: a design reviewer, a security reviewer, a correctness reviewer, each commenting on a change without waiting on the others, plus one executor agent that applies changes based on what comes back.
Wiring several agents to comment on the same artifact is the easy part, and the tooling for it is getting commoditized; plenty of it does async multi-agent review well enough. The hard question is the one this post keeps circling: what is the executor allowed to apply on its own, what needs a human confirmation first, and what checks afterward — independently — that the executor stayed inside that line rather than trusting its own account of what it did?
That last part is easy to skip. A system that only checks “did the reviewers comment” looks fine right up until an executor acts past its authority and files it as routine. Make the authority manifest explicit, restate it at every delegation instead of linking to it, and verify in both directions. Then the agents start behaving like a team with real boundaries instead of one authority running in parallel.
The throughline across both posts: more agents only helps if something explicit keeps them from acting like one. That something isn’t a scheduler, and it isn’t a chat channel — both of those already existed before this problem showed up. It’s an authority contract, stated in full at every handoff and checked both ways afterward, and the idea is the same whether the team is reviewing tax documents or a pull request.
]]>So I split the one generalist sweep into several narrower reviewers, each on its own schedule. That created a new problem. These agents don’t share a conversation, and they can run days apart. How do they talk to each other, and to the person they work for?
The original auditor did three things on every run: check the archive against its naming and placement rules, check whether the reference notes were still in sync with new source material, and check the notes for internal rot — dead cross-references, stale metadata, sections that had drifted out of shape. All three are mechanical. Given the rule and the data, there’s one right answer and you don’t need any special training to find it.
That covered the need until the reference notes spread across several domains: finance, legal, health, identity. Each one carries open questions with no mechanically correct answer. Does this asset allocation still match the risk tolerance it was built for? Does this beneficiary designation still line up with the estate plan? Does a new lab result change what’s worth prioritizing? Answering those well takes a domain expert’s judgment, applied on a schedule, against outside standards that keep moving — tax law, medical guidance, immigration rules.
Piling that onto the weekly sweep would have made one skill responsible for both “is this file named correctly” and “is this retirement strategy still sound.” Those are two very different jobs, and one skill wasn’t going to do both well.
The weekly sweep kept its job unchanged: cheap, mechanical, runs often, fixes the obvious stuff, flags the rest. Each domain then got its own reviewer on a monthly schedule. Each reviewer has a persona (a tax planner for finance, an estate and immigration attorney for legal, a physician for health), a mandate written down in one place, and a narrow job: read the domain’s notes, check whether the strategy they encode still holds up against current best practice, and update them if it doesn’t.
Every reviewer carries the same boundary, worded identically in each persona: advisors advise, they don’t execute. The finance reviewer can recommend rebalancing, but it never places a trade. The legal reviewer can point out that a beneficiary designation looks stale, but it never files anything with an institution. The rule is absolute on purpose. A note that appears to grant an exception doesn’t get to override it.
If you’re building something similar: one frequent shallow sweep that owns mechanical correctness everywhere, plus one slower deep reviewer per domain for the calls that need real expertise. Resist the urge to let the fast sweep pick those up just because it’s already running. That’s the pressure that wears the split down over time.
Splitting by depth leaves a gap. The fast sweep runs several times a week; the deep review runs monthly. When the fast sweep turns up something that needs expert judgment, it can’t sit untouched for three weeks until the monthly review notices it. It also shouldn’t get a quick guess passed off as a considered answer.
So the fast sweep answers it right away, but against a shallower standard: a condensed version of the persona instead of the reviewer’s full mandate, with the answer labeled as shallow. It then queues the item for the next deep review, marked higher priority than the rest of the backlog because it has had less scrutiny so far.
A fast answer and a considered one should never look the same in hindsight. If you answer with less depth than you’d like, say so in the record. Otherwise nobody knows there was a gap to close, and the deep review layer might as well not exist.
None of this works unless the separately-scheduled agents can communicate — with the person they work for, and with each other across the gap between a Wednesday sweep and next month’s review. Two channels cover it, both using the same inline mechanism so there’s nothing new to learn for the second one.
Human to agent. I annotate a note inline, next to whatever it’s about: a question, a correction, an answer to something asked earlier. On its next pass the agent finds every annotation, resolves what it can — research it, act on it, apply the fix — and removes the marker once it’s handled. It never deletes an unanswered one just to clear it. In practice, three marker types cover it:
> [!human-question]
> Is the online renewal window actually 90 days, or 60?
> [!human-comment]
> That case really did run 2009 to 2011. Don't re-flag the date.
> [!human-answer]
> Yes, go ahead and standardize those filenames.
A question gets researched and answered in place. A comment gets treated as an instruction and acted on. An answer resolves whatever it’s replying to. All three get removed once handled, with a one-line note in the file’s history log about what happened, rather than left in place.
Agent to agent (and agent back to human). When a finding needs judgment the finding agent doesn’t own, or the fast sweep wants to leave something for the deep reviewer, it uses the same inline marker, addressed by name, at the spot it applies to:
> [!agent-question]
> For tax-reviewer: this account's cost basis doesn't match the last statement.
> Flagging instead of guessing which figure is stale.
> [!agent-comment]
> For docs-reviewer: this note has gotten long enough to need a table of
> contents. Not my job to fix, just noting it.
Only a reply from the named party clears it. An agent that finds a marker addressed to someone else doesn’t get to decide it’s close enough and resolve it. That would defeat the point of naming an owner.
This carries over to a setting with nothing to do with document filing. Picture a codebase with a handful of review agents attached to it instead of one linter — a security reviewer, a design reviewer, a migration reviewer — plus one agent that applies changes. The security reviewer finds something outside its own lane and leaves [!agent-question] / For migration-reviewer: this index change looks like it'll lock the table under load, can you confirm before it merges? right on the diff. The migration reviewer, not the security reviewer, is the one who clears it, and not before then. The grammar and the ownership rule carry over unchanged; only the domain is different.
Two small details made this reliable:
One failure here is worth writing down, because the design didn’t predict it. It only turned up once the thing ran unattended.
The fast sweep’s fallback for a strategic question (from the cadence gap above) was meant to read the relevant reviewer’s mandate document and apply just the one relevant section — cheaper than the full procedure, but still based on the real standard. That worked in an interactive session. On a scheduled run it didn’t: the cross-skill file reads failed every time, across every domain, on the same day the same paths read fine interactively. So this wasn’t a bad path or a flaky file. A scheduled run can’t reliably read another task’s files at all.
The fix was to stop routing around the boundary and plan for it. There’s now a shared one-paragraph fallback — the same persona summary for every domain — living in a document every skill already loads for other reasons. When the unattended read would fail, the sweep uses that instead of burning a turn on an attempt it knows will fail. It’s a downgrade from the full standard, and it’s labeled as one. That’s acceptable because the alternative was a crash or a skipped check, both worse than a shallow but honest answer.
Don’t assume something that works interactively works the same on a schedule. Test the real failure on a real scheduled run before you design around it. “This should work” and “this fails this exact way every time” led to different fixes here.
What this setup still lacked mattered more than any single piece above: one shared answer to who is allowed to act on what without asking first, across all of these separate agents rather than inside any one of them. The next post is about that gap and the failure that exposed it.
]]>Call it a longevity plan or a healthspan plan, whatever you like. The content is a short, chart-derived list of labs, imaging, functional tests, and behavior changes worth raising at a doctor’s visit, each one tied to a specific reason from the chart rather than a generic “things people over 50 should think about” list.
Two framing choices matter more than anything in the content:
It’s not a diagnosis or a treatment plan. It’s preparation material. The goal is a better-informed conversation at an appointment, not a replacement for one. That distinction has to survive being written down, or the document turns into something it shouldn’t be.
It exists to coordinate across specialists who don’t see each other’s records. A cardiologist, an endocrinologist, and a sleep clinic each get a narrow slice of the picture. Nobody except the person living in that body — and now this document — sees all three slices at once. That’s the gap it fills.
The most important constraint on this document: it never duplicates what a standard checkup already covers. If a lab is already on the checklist for an upcoming visit, it doesn’t also appear here. It stays where it already lives, once.
This matters because the common failure mode is a “personalized” health document that’s mostly generic filler — “eat more vegetables,” “get enough sleep” — with a name at the top. That kind of document loses your trust by the second read, because none of it needed to know anything about you. Here it’s the opposite: every line exists because of something specific in the chart, and a section at the bottom lists what the standard checklist already handles well, so nothing gets duplicated by accident later.
The list stays narrow and evidence-weighted rather than aspirational. Longevity medicine covers a wide range of tests and interventions with very different evidence behind them; this document sticks to the well-established, low-downside end and skips the speculative end.
The plan has three categories — additive labs, imaging and functional tests, behavioral priorities — and every item carries its reasoning inline, not just a name. Not “ApoB” but why ApoB, given what the last lipid panel showed and what ApoB catches that a standard panel doesn’t. Not “resistance training” but which gap in an otherwise-strong fitness picture it addresses.
That’s the point. A bare list of test names is something you could get from a search engine. A list where every item explains why it matters for this chart only exists because someone read the chart.
The tracking half is a checklist: checkbox, status, and once something is done at a visit it moves to a completed line with a date and a pointer to where the result landed. The plan should show progress over time, not sit as a wish list that gets ignored or forgotten.
This is a separate, recurring task from the one that built the plan in the first place — a scheduled monthly pass, per person, that:
The cost discipline is the part worth calling out. A monthly review that re-extracts everything from source documents each time would be expensive, and it would duplicate work two other parts of this system already do: filing new documents, and a weekly audit that catches anything not yet summarized. So this review only reads the already-processed notes. If it spots a source document newer than the plan’s last update that hasn’t been folded into those notes yet, it flags that gap for the other layer rather than doing the extraction itself. It stays cheap by staying narrow about whose job is whose.
Even a review that finds nothing to change still writes a log entry: “reviewed, no changes, N items still open, nothing new shifts priorities.” That’s not busywork. A plan with no review history looks the same as a plan nobody checks anymore, so a monthly cadence only means something if “no news” and “no one looked” stay distinguishable on the page.
This is the same instinct as a rule from the archive-reorg post: a stale note is worse than no note, because it looks authoritative right up until it’s wrong. Here it’s a habit rather than a check — silence gets logged on purpose, so it reads as “confirmed current” instead of “abandoned.”
The series so far is one idea at three levels: collect the data, organize the data, then use it for something, and don’t let any of the three quietly stop. This is the “use it” layer, and the monthly loop is what keeps it from becoming one more good intention that fades by March.
]]>This is the Android app I built to fix that. It reads everything Health Connect exposes, aggregates it sensibly, and appends it to a per-person CSV file in Google Drive. No backend server, no third-party service, just the phone and a Drive folder.
The source is open: espaillato/HealthSync. The sections below are the design decisions and bugs behind it.
Fair question: why build this instead of glancing at the Samsung Health app now and then? The data is source material for something else.
I keep a structured personal document archive organized around a small set of life categories, Health among them. Within each category a _Core folder holds living reference documents: the kind meant to reflect current understanding and get updated as things change, rather than frozen at whenever someone last wrote them. Keeping a health overview current used to mean sitting down and rewriting it by hand every few months, which is the kind of maintenance that stops happening.
What I’m working toward: have an AI model read the structured data in the archive and use it to spot trends, flag things worth a second look, and keep the _Core reference documents up to date from real data instead of remembered impressions. That needs real structured data to read. A phone’s health dashboard doesn’t produce it, and neither does a folder of screenshots. A clean, deduplicated, sensibly-aggregated CSV landing in the right place in the archive does. That’s what this app is for: the data-collection layer under a larger system.
Samsung Health has its own proprietary sensor pipeline for a handful of metrics, and reading those directly means special-casing Samsung’s SDK. I didn’t want that. The rule I settled on:
That one rule kept the scope honest. It also means the app works for any Health Connect source, not just Samsung Health — body-composition data (weight, body fat, etc.) written by a different app or a different manufacturer’s scale comes through the exact same path.
androidx.health.connect:connect-client, uploads via the Drive v3 API.user1_health_sync.csv, user2_health_sync.csv, dead simple to open in a spreadsheet or load with pandas.The CSV schema is deliberately flat:
timestamp_utc,owner,metric,value,unit,source_record_id
source_record_id is the dedup key — more on that below.
Early on the app synced Health Connect’s raw records verbatim. That’s fine for a day or two, then steps and heart-rate data balloon into thousands of rows that no longer serve the actual goal: seeing trends over weeks, months, years.
The fix is a metric-by-metric aggregation policy:
One wrinkle: a calendar day is the wrong bucket for sleep. Steps taken between midnight and midnight map cleanly onto “today.” A sleep session that starts at 11pm and ends at 7am doesn’t. Bucketing it by calendar day either splits one session across two days or assigns it to whichever day it started on, and both corrupt night-over-night trends.
The fix: sleep metrics use a noon-to-noon “sleep day” instead of a calendar day (instant.minusHours(12), then take the date). Everything else stays on calendar-day boundaries. So the app has two definitions of “day” running side by side, on purpose. That’s worth a loud comment in the code, since a future edit could break it without noticing.
That in turn creates a completeness problem: a calendar day is “done” at midnight, but a sleep day isn’t “done” until noon the next day. A single query boundary can’t correctly serve both. The app resolves this by separating two concerns that used to be conflated into one timestamp:
isCompleteCalendarDay / isCompleteSleepDay), regardless of how fresh the query itself was.The sync cursor only ever advances to the latest point that’s safe for every metric — never past a boundary that could still receive more data.
A service account is the right tool here: no user-facing login, no refresh-token dance on-device, just a JSON key file and a folder shared with the service account’s email as Editor.
Two gotchas that cost real time:
Service accounts have no storage quota of their own. files.create() against a folder the service account only has Editor access to (not ownership) fails with storageQuotaExceeded — service accounts can only create files up to their own (zero) quota. The workaround is boring but reliable: pre-create the empty CSV files yourself, share the folder, and let the app only ever files.update() an existing file it never has to “create.”
Dedup has to be data-driven, not timestamp-driven. Health Connect write sources can backfill already-passed timestamps — a source might not get write permission until well after it started collecting data, then dump hours of retroactive history the moment permission is granted. If the sync cursor had already advanced past that window, that backfilled data becomes permanently unreachable, since the cursor never looks backward. Two things fix this together: the cursor only advances when a sync actually finds something (an empty result never moves it forward), and every upload is deduped against a synthetic, deterministic source_record_id parsed out of the CSV’s last column before anything gets appended. That combination means a manual “resync everything from scratch” is always safe to run — nothing above the file’s high-water mark can duplicate.
This is the one worth writing down for anyone else scheduling periodic background work on Android.
The background sync used PeriodicWorkRequestBuilder(1, DAYS, 1, HOURS) — a one-day interval with a one-hour flex window, setInitialDelay() computed to land on a specific hour, ExistingPeriodicWorkPolicy.UPDATE on every app launch so re-opening the app would re-anchor the schedule if the target time ever changed.
On a real device, dumpsys jobscheduler showed the job’s actual Minimum latency landing roughly 23 hours later than the computed initial delay implied it should. Reproducible too: the same offset showed up on two separate phones.
The cause: setInitialDelay on a periodic work request only shifts when the period starts. It does not let the first execution skip ahead within that period. The first run still waits out (interval − flex) beyond the initial delay, like every run after it. With a 1-hour flex on a 24-hour interval, that’s initialDelay + 23h for the first execution, so almost a full extra day passes before anything runs.
Two separate fixes were needed:
ExistingPeriodicWorkPolicy.UPDATE doesn’t reliably re-anchor an already-scheduled periodic work to a freshly computed initial delay — confirmed by changing the target hour and watching UPDATE leave the old cadence in place. Switched to CANCEL_AND_REENQUEUE, which fully removes and reinserts the WorkSpec instead of trying to patch it in place.Verified with adb shell dumpsys jobscheduler, comparing the job’s reported Minimum latency against adb shell date on the device, rather than reasoning about the API from the docs. The docs don’t mention any of this; the device state showed it plainly.
One more real bug, caught by actually using the app rather than reading the code: after granting Health Connect a new permission (a metric that wasn’t being read before), the app’s existing sync cursor was already ahead of that metric’s entire history. From the cursor’s point of view, that metric simply started existing the moment the permission was granted — everything Health Connect still retained from before that was silently unreachable.
The fix is a manual “Resync Full History” action: reset the cursor to null, re-run the sync. It’s safe to hit at any time, for any reason, precisely because of the source_record_id dedup backstop described above — already-uploaded days get filtered out on the way to Drive, not duplicated.
Health Connect’s permission screen needs an activity the OS can deep-link into for “why is this app asking for this” — but the manifest entry for that changed on Android 14, and the two requirements coexist rather than one replacing the other:
ACTION_SHOW_PERMISSIONS_RATIONALE.VIEW_PERMISSION_USAGE action, the HEALTH_PERMISSIONS category, and the START_VIEW_PERMISSION_USAGE permission.Missing the second one doesn’t throw an error — it just makes the permission screen flash open and immediately close, which is a genuinely confusing failure mode to debug from logs alone (logcat showed both activities created and destroyed within the same millisecond). Both aliases need to be declared side by side; there’s no version-gating trick that lets you skip one.
No Play Store listing — this is a two-person household tool, sideloaded via a signed release build on each phone. A couple of things that mattered in practice:
adb shell run-as ... cp. Release builds aren’t debuggable, so that’s blocked outright — the real answer is an in-app “Import Key” flow using ActivityResultContracts.OpenDocument(), letting the user pick the downloaded key file from wherever it landed (Downloads, an email attachment) and having the app copy its bytes into its own storage via the returned content:// URI.<cutoff>” — which barely moves day to day and gives zero feedback about whether a sync attempt just ran and failed versus never running at all. Splitting that into two separate fields — last sync attempt (wall-clock time, updates on success or failure) and data through (the actual cutoff) — made failures visible instead of silent.This one started as a hardware problem. A Bluetooth blood-pressure cuff generally pairs with one phone at a time — fine for one person, awkward for a two-person household unless you buy two cuffs and keep track of whose is whose. When the cuff was paired, the readings flowed through Health Connect cleanly; I confirmed that with real synced data. Rather than double the hardware, the better option was the watch’s on-device blood-pressure feature, which only needs the cuff occasionally for calibration.
That’s where it stopped working. The watch’s BP readings live in a separate app from the main health-tracking one, and that app’s blood-pressure data never reaches Health Connect, on any version. Querying its content provider by hand threw a SecurityException demanding a signature|privileged permission. No third-party app can hold that permission, sideloaded or not, and there’s no settings toggle or future update that changes it.
The workaround: make the app a share target. The BP app does support exporting readings and sharing that export elsewhere — PDF, in the version this was built against (an HTML option existed at some point but wasn’t available by the time this got built, so it isn’t handled). Registering an ACTION_SEND intent-filter for application/pdf turns the sync app itself into a destination in the share sheet: export, share, done.
The PDF parsing gotcha deserves its own paragraph. The export is small and machine-generated with real embedded text, not a scan, so text extraction instead of OCR — good news, since OCR would add a misread-digit risk that this data can’t afford. I built a parser and verified it against a desktop PDF text-extraction library’s output for a real sample export, which laid each reading out as five separate lines. Shipped it, tested on the device, got “0 readings found.” The on-device PDF library, chosen because it could do real extraction without OCR, laid the same file out one line per reading, space-separated fields, no line breaks between them. Two outputs, both correct, for the same PDF. The fix was mechanical once I had the real structure: rewrite the pattern, dry-run it against a captured real extraction before touching the build. The recurring lesson on this project is to check the actual library against the actual device, not another library’s output on the same file.
Not a second upload path. Confirming an import doesn’t talk to Drive directly. It stages the parsed rows locally and triggers the same background sync Health Connect data goes through, which folds both sources into one upload. One place in the app authenticates and writes to Drive; a second path would drift from it over time.
The aggregation question got revisited once there was real data to check it against. Blood pressure started in the same bucket as heart rate: dense, fluctuating, aggregate to daily min/avg/max. That was a guess made before any real data existed. Actual exports showed 2-3 deliberate spot readings a day, not hundreds of continuous samples, closer to a scale weigh-in than a heart-rate stream. It moved to the same point-in-time, one-row-per-reading treatment as weight and height. That also dropped some complexity: a metric with no daily bucket has no “is today’s bucket finished yet” problem, which the aggregated version had to handle.
Every export overlaps the last one, so duplicate handling runs every time, not occasionally. The BP app’s own export options are fixed, overlapping windows (a week, two weeks, a month, three months, year-to-date), so re-exporting routinely re-covers ground already synced. Two layers handle that: each reading’s source_record_id is derived from its own timestamp, so an already-uploaded reading is skipped automatically, and a second dedup step inside the upload catches what that alone can’t — two overlapping staged but not-yet-synced imports both producing the same ID within a single upload batch.
One more thing: an early debug aid wrote the raw parsed report to external storage so it could be pulled and inspected during development. Once it had served its purpose it kept writing anyway — a name, a date of birth, and every reading, sitting on disk with nothing to clean it up. I removed it once I noticed. The on-screen preview already shows what was parsed, and closing the screen should be the end of it.
The repo has a full build-it-yourself guide; the short version is three parts.
Build the APK. You need JDK 17+ and the Android SDK (minSdk 26, so any phone on Android 8 or newer that has Health Connect). Then:
git clone https://github.com/espaillato/HealthSync
cd HealthSync
./gradlew assembleRelease
For a quick trial assembleDebug is fine; for anything you’ll keep updating, set up a release keystore first, because regenerating it later invalidates every future install, so back the .jks up somewhere durable.
Set up the Google side once. Create a service account, add a JSON key, and enable the Drive API. In Drive, make a folder shared to the service account’s email as Editor, and pre-create one empty CSV per person inside it, because the service account can’t create files itself (the quota gotcha from section 4).
Install and configure on each phone. Sideload the APK, tap Import Drive Key and pick the JSON file, enter a name (it becomes the CSV owner and the filename), and grant Health Connect permissions on both screens: the per-category one, and the “additional access” one for history and background sync.
After that it syncs on its own around 2am; Sync Now forces an immediate run. Sync frequency is a single constant (SYNC_INTERVAL_DAYS in SyncWorker.kt). The repo’s CLAUDE.md will walk an AI coding agent through the same setup if you’d rather not do it by hand.
Most of these bugs — the scheduling gap, the flash-closing permission screen, the unreachable backfilled history, the PDF layout mismatch — weren’t visible from reading code or docs. They showed up by running the app on real devices and checking system state: dumpsys, logcat, the Drive file contents. Health and scheduling APIs on Android have a wide gap between what the docs say and what the OS does.
This is the story of fixing that: how the first approach failed at the part that mattered most, and what it produced along the way that made the second approach work.
A read-only audit script walked the archive and produced a blunt table: folder name, subfolder count, file count. The top of that table told the story — near-duplicate category names differing only by a typo or a synonym, several folders with a handful of files each that existed only because something needed somewhere to go at the time, and nothing anywhere indicating whose document it was or whether it was shared.
None of that is unusual. It’s what any shared drive looks like after years of “just put it somewhere for now,” and it doesn’t sort itself out.
The first pass was straightforward automation: a Python pipeline against the Drive API that classified files with an ordered list of (category, [keywords]) rules, deduplicated exact-content matches by hash with a deterministic scoring function to auto-pick a “winner,” repointed shortcuts instead of leaving them dangling, and — critically — split into a read-only planning phase and a separate, explicitly-scoped apply phase, so nothing with write access ever ran until the proposed classification had been reviewed as plain CSV data first.
Some of that held up well and is worth keeping regardless of what does the classifying:
_Joint folder for shared documents, a _Core folder for reference material, a General catch-all, plus an explicit Unsorted bucket so “not yet categorized” is a visible state instead of a silent one.insufficient authentication scopes error, because the cached token had been minted under the planning phase’s narrower, read-only scope. Because the plan itself was just reviewable data and every apply attempt was logged, that failure was just a log line to go fix — not a mess to clean up.What the script couldn’t do was hold a reason, only a keyword. Real placement rules look like “if it proves who you are, it belongs here regardless of who issued it,” or “if a doctor would care about it, it belongs in Health,” or “this abbreviation looks like it belongs in one category but is excluded because of how a particular process works.” Those are judgment calls rather than string matches, and each one eventually showed up as a misfile that had to be caught by hand and turned into another keyword-list exception, in a rule list that only grew.
That ceiling is why the first project’s main output was a document, not a script. Writing down every “if X, then Y, because Z” rule in prose, in one place, as the reasoning rather than a keyword fragment, was worth more than the code that tried to enforce it. Calling the pipeline a failure isn’t quite fair — it did the dedup, the shortcut hygiene, and the plan/apply safety rails correctly, and those still hold. But as a classifier it plateaued well below what the archive needed, and the document it forced into existence outlasted it.
The fix replaced the keyword list with something that can actually read: two narrow, purpose-built Claude skills sitting on top of the archive, both anchored to the same reasoning document instead of a hard-coded rule table.
Both skills open with the same requirement: read the rulebook first, every run, and refuse to proceed if it’s missing. Never fall back to memory or convention. That constraint carries a lot of weight. It’s the difference between a rule document a person consults now and then and one an agent reloads fresh every session, which matters because an agent has no memory of last week’s edge-case decision unless something outside it holds that decision in writing.
This is where “an agent instead of a script” turns from an abstract upgrade into a concrete one.
Identifying a document means reading it, and real-world scans are messy. The filer’s fallback chain handles that rather than giving up:
Only when nothing can be extracted — an encrypted file, an unreadable scan even after all of that — does it stop and ask instead of guessing. That three-tier fallback, ending in “look at the page before giving up,” is not something a keyword-matching script could approximate.
From there the naming itself follows the rulebook directly: a date prefix (only if a date can actually be confidently determined from the content — never invented), a descriptive body specific enough to identify the document without opening it, consistent handling of acronyms and institution names, the original extension preserved.
Where a file currently sits changes how much autonomy the filer has, and the reason is simple: a file’s current location is itself information. Something in an inbox-style holding folder isn’t a deliberate choice yet, so the filer renames and moves it outright, no confirmation, and only stops to ask if the content can’t be identified at all.
A file already inside a real category folder is different. Someone put it there on purpose, even if the name is wrong, so moving it always gets proposed and confirmed rather than applied silently. Even a same-folder rename gets a check first: does the new name change what the file appears to be about — who it belongs to, what type of document it is, what it’s for? A pure formatting fix (casing, spacing, date format) goes through without asking. Anything that shifts apparent ownership or purpose comes back as a proposal with the reasoning attached, because that name might have been chosen deliberately, and guessing wrong is worse than asking.
The same instinct shows up in the auditor’s own triage: fix silently only when it’s mechanical and reasoning-free, hand off anything content-dependent to the filer, and ask the user for anything that requires guessing intent — including a flat rule to never silently repoint a broken cross-reference, never invent a missing piece of metadata, and never reorder or merge content without a human confirming the guess first.
The archive isn’t the only thing that can drift — a parallel set of running reference notes (a per-topic, always-current summary, separate from the point-in-time source documents backing it) has two independent ways of rotting, and the auditor checks both, deliberately treating them as unrelated failure modes rather than one:
Freshness against the source archive. When a new document lands in a category that a note is meant to summarize, that note should get updated as part of filing it — but if that sync step gets skipped, the note quietly falls behind whatever the archive itself now shows. The check is simple: compare the newest relevant source file’s date against what the note’s own metadata claims it reflects. Deliberately not re-extracting anything to check this — that’s real, costly work, and the freshness check is meant to stay a cheap weekly sweep that just flags what’s behind, handing the actual re-sync off separately.
Internal consistency, independent of the archive. A note can be perfectly in sync with the archive and still be quietly broken, because these are notes a person edits directly, by hand, not exclusively through the filing skill. So the auditor separately checks: cross-references between notes that no longer resolve to anything (a rename or deletion elsewhere silently orphaned the link), metadata that says a note was last touched on one date while its own content log shows a later edit, section ordering drifting back toward an older layout after a manual edit, reference notes nothing links to anymore, and markdown tables where a row’s been hand-edited into having the wrong number of columns. There’s also a specific content-drift heuristic — a “snapshot, not encyclopedia” principle, where general explanatory content that belongs in a shared reference note has crept back into a note that’s supposed to hold only person-specific facts. That one’s explicitly a heuristic to flag for review, not something to silently move on its own judgment.
One category of note gets a dedicated secondary sync path of its own, because it’s structurally different from a narrative summary: a running numeric-trend table, wide format, one column added per new data point, tracked separately from the main note it’s linked from. Keeping that kind of table honest needs its own small set of hard rules, learned the hard way rather than assumed upfront: standardize a new entry’s label against what’s already in the table before adding it as a new row — the same underlying measurement legitimately shows up under different names across different sources, and silently merging two rows that turn out not to be the same thing is worse than a harmless duplicate row flagged for a human to reconcile later. Guard explicitly against transposed or misread digits when transcribing a number by hand. And when a single source file happens to bundle more than one date’s worth of readings together, double-check which figure belongs to which date rather than assuming page order lines up with chronological order — a real, named failure mode, not a hypothetical one.
A few operational choices behind this layer are worth calling out on their own, because they’re the kind of thing that only becomes obvious after building it, not before:
Stripped of anything specific to my own household, the rulebook’s shape is worth describing on its own, because the shape is the reusable part — and the top-level category list specifically is worth sharing close to verbatim. Landing on a stable category boundary is the hardest part of this whole exercise, harder than any of the automation built on top of it, and it’s also the most reusable across households: what a document is about generalizes; the specifics of any one archive don’t.
The rule that matters more than any individual category name: every category gets a one-line test, not just a label. “Finance” as a bare word invites endless debate about where a mortgage statement goes; “if it affects net worth, cash flow, or taxes” settles it in one read, for that document and every future one like it.
| Category | Placement test |
|---|---|
| Identity | Proves who you are — belongs here regardless of who issued it. |
| Immigration | Affects where you’re legally allowed to live. |
| Health | Something a doctor would care about. |
| Insurance (non-health) | Limits financial damage from an adverse event. |
| Legal | Creates or modifies a binding obligation or authority. |
| Finance | Affects net worth, cash flow, or taxes. |
| Home | Changes when you move. |
| Work | Matters only because of where you’re employed. |
| Family | The organizing axis is a specific person (non-primary family member), not a topic — see the override rule below. |
| Personal | Losing it is annoying, not dangerous. |
| Individual | About you as a person, outside of work or family. |
| Unsorted | Explicitly “not yet categorized” — a real bucket, not a place things drift by default. |
A few things about that list generalize past any one household. It’s short on purpose — a dozen or so buckets is few enough to hold in your head, which matters more than being exhaustive, since an Unsorted escape hatch means it never needs to be exhaustive. Every row is a test, not a topic — “what would someone searching for this actually assume it’s filed under” beats “what’s this document about” as the question to design each row around. And a couple of categories exist specifically to prevent a subtler failure than plain sprawl: Individual exists because “about you, but not work and not family” is a real, recurring bucket that otherwise silently collapses into an ever-vaguer “Personal,” and Family deliberately overrides every other category for a defined set of people, because who a document is about occasionally needs to outrank what it’s about — worth deciding once, explicitly, rather than re-litigating per document.
It ends with a line that’s stuck with me past this one project: clever systems decay, obvious systems persist. The entire document is built around that — every rule is written to be re-derivable by a tired human (or a fresh agent with no memory of the last conversation) glancing at it cold, not just executable by whatever wrote it originally.
It’s easy to write off the first attempt once the second one works better. But the discipline the script enforced — plan before you apply, quarantine before you delete, log every action, never let the thing doing the classifying also hold write access — still matters with an agent in the classifier’s place. An agent making placement judgment calls needs those guardrails as much as a keyword matcher did, probably more. The ask-vs-auto boundary above is the same instinct pointed at a different kind of decision-maker.
The reasoning document that made the second approach work came directly out of the first attempt’s constraint: a keyword list forces you to write “why does this belong here” as an explicit rule, one category at a time. Without that constraint, the document might never have gotten written.
Most of what lives in a personal archive is a point-in-time record — filed once, correct forever, never meant to change. A smaller category of document is meant to stay current instead. The running reference notes described above are that category — a summary meant to be trusted as accurate today.
Keeping something like that current used to mean remembering to sit down and manually re-edit it every few months, which is exactly the kind of maintenance that quietly stops happening. Now an agent reads whatever new, structured source material lands in a relevant category and folds it into the note that summarizes it, the same way it’s already reading the archive’s own rulebook to decide where things belong. That needs real structured data to read, which is what the Health Connect → Drive sync project exists to produce: clean, structured, machine-readable source data landing in exactly the right place in this same archive, rather than one more pile of point-in-time records nothing goes back and reads again.
Building this inside Google Drive, rather than some other cloud store used as dumb storage, has a payoff that’s easy to miss: the same organized archive ends up queryable three ways, because Drive is a first-class data source for Google’s own AI tooling. The Living Reference notes are one interface — curated, narrow, current-state summaries with links back to source. The archive itself is a second: Gemini can be pointed at that same Drive and asked open-ended questions across the whole corpus, with no separate indexing pipeline or export step to maintain. Drive’s own search and folder browsing is a third, for when a file just needs to be found by hand. None of the three needed extra infrastructure once the archive was clean, and the work that went into cleaning the data is what makes all three trustworthy.
_Core/reference layer maintained less by remembering to revisit it and more by an agent reading real source material on an ongoing basis, with hard-won rules against the specific failure modes (mismatched labels, transposed digits, misattributed dates) that actually showed up.It isn’t a generic guide. Follow it top to bottom for the same result.
Open PowerShell as Administrator:
wsl --install
Reboot when prompted.
After reboot, open Windows Terminal and select Ubuntu.
Create:
wsl -l -v
Expected:
Ubuntu Running 2
Inside Ubuntu:
sudo apt update && sudo apt upgrade -y
Install baseline packages:
sudo apt install -y \
build-essential \
curl wget unzip zip \
ca-certificates gnupg lsb-release
echo $SHELL
If not /bin/bash:
chsh -s /bin/bash
exec bash
curl -sS https://starship.rs/install.sh | sh
Enable it:
echo 'eval "$(starship init bash)"' >> ~/.bashrc
exec bash
Create config:
mkdir -p ~/.config
nano ~/.config/starship.toml
Paste:
format = "$username$directory$git_branch$git_status$java$cmd_duration $character"
add_newline = false
[username]
show_always = false
style_user = "dimmed white"
style_root = "bold red"
format = "[$user]($style) "
[directory]
truncate_to_repo = true
style = "bold cyan"
format = "[$path]($style)"
[git_branch]
symbol = " "
style = "bold purple"
format = "[$symbol$branch]($style)"
[git_status]
style = "yellow"
format = "[$all_status]($style)"
[java]
symbol = " ☕ "
style = "red"
format = "[$symbol$version]($style)"
[cmd_duration]
min_time = 500
style = "dimmed white"
format = " [⏱ $duration]($style)"
[character]
success_symbol = "\\$"
error_symbol = "\\$!"
[hostname]
disabled = true
[time]
disabled = true
[battery]
disabled = true
[memory_usage]
disabled = true
Reload:
exec bash
Verify:
~ $
Download: https://code.visualstudio.com
Install with defaults.
In VS Code → Extensions (Windows side):
Inside the WSL environment (server-side extensions):
cd ~
code .
Verify bottom-left shows:
WSL: Ubuntu
curl -s "https://get.sdkman.io" | bash
source "$HOME/.sdkman/bin/sdkman-init.sh"
Verify:
sdk version
sdk install java 21-tem
sdk install java 17-tem
sdk default java 21-tem
Verify:
java -version
sdk install maven
sdk install gradle
sudo apt install -y \
python3 python3-venv python3-pip \
pipx \
libssl-dev zlib1g-dev libbz2-dev \
libreadline-dev libsqlite3-dev \
libffi-dev xz-utils tk-dev
curl https://pyenv.run | bash
Add to ~/.bashrc:
export PYENV_ROOT="$HOME/.pyenv"
export PATH="$PYENV_ROOT/bin:$PATH"
eval "$(pyenv init -)"
Reload:
exec bash
Install Python:
pyenv install 3.12.8
pyenv global 3.12.8
python --version
python -m venv .venv
source .venv/bin/activate
pip install -U pip
curl -fsSL https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.1/install.sh | bash
exec bash
nvm install --lts
nvm alias default lts/*
node -v
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
exec bash
rustup component add rustfmt clippy
sudo apt install -y \
jq ripgrep fd-find bat tree htop \
lsof dnsutils file less httpie shellcheck
Aliases:
echo "alias fd=fdfind" >> ~/.bashrc
echo "alias bat=batcat" >> ~/.bashrc
exec bash
~/bin (symlinked)mkdir -p ~/projects/oss/dotfiles/bin
ln -s ~/projects/oss/dotfiles/bin ~/bin
Add to PATH (if not already):
echo 'export PATH="$HOME/bin:$PATH"' >> ~/.bashrc
exec bash
git config --global url."git@github.com:".insteadOf "https://github.com/"
Create ~/.gitconfig-github:
[user]
name = <Name>
email = <Github Public Email>
Add to ~/.gitconfig:
[includeIf "hasconfig:remote.*.url:https://github.com/**"]
path = ~/.gitconfig-github
Verify:
git config --show-origin --get user.email
which java
which python
which node
which cargo
which git
All should resolve inside $HOME.
Prompt should show $, not >.
You now have:
It’s a boring setup, which is the point. It should keep working for years without attention.
]]>