What six months of project notes actually look like

I've written about this vault twice: how it's set up, with one folder per project and a note per working session, and the nightly routine that reads the notes back against reality and corrects whatever has drifted. Neither post asked the obvious question, which is whether the thing is any good.

So I counted it. Six months of notes, eight projects, one afternoon and a short Python script.

The counting is worth a sentence of its own. The vault is a folder of markdown files, so measuring it is a folder walk and a few regexes. There's no export step, no API, no plugin, and nothing to ask permission of. That's the argument for plain files, and it stays theoretical right up until the day you want to know something about your own notes.

Here's what the walk found.

The vault is not evenly loaded

Eight project folders, 295 notes between them, plus nine that sit loose at the top level. The two busiest hold just under half of everything. The four quietest hold 63 notes between them, about a fifth.

My first reaction was that the small ones were neglected. They aren't. Note volume tracks how often I was confused, not how big the project is or how much it matters. The 86-note project isn't the largest codebase I have. It's the one where I kept being wrong about my own data, where three separate design decisions got reversed, and where a single feature took four sessions and produced four notes explaining why the previous three were incomplete.

A project with 14 notes is a project that behaved. Looking at the chart that way inverts it. The tall bars aren't achievement, they're friction that got written down, and the short bars are the ones where the work went the way I expected.

The habit arrived all at once

Twenty in April, 13 in May, three in June, nothing in July, then 96 in August and 88 in the first twenty days of September. 184 of the 220 dated notes were written in the last seven weeks.

Nothing about my discipline changed in July. What changed in August is that writing the note stopped being a separate job. Through the spring, the note was something I did after the work, which meant I did it when the work had gone well and skipped it when the session ran long. Now the agent that did the work writes the note before the session ends, from the session it just had, and the marginal cost of a note is close to zero.

The July gap is the honest part of the chart and I'm leaving it in. That month has no record at all, and one of the projects in this vault lost its git history in the same stretch, so there's genuinely nothing to reconstruct from. Two months later I was still paying for it in small ways, looking for decisions that were made and never written anywhere.

Most notes are one page, a few are reports

The median note is 1,162 words, which is about a page and a half. 114 notes land in the 500 to 1,500 band and 76 come in under 500. Those short ones are usually a single decision or a single bug with its cause.

Nine notes run past 6,000 words, and they're all the same kind of note: the standing summary that answers "where is this project right now". Those get rewritten rather than appended to, which is why they're long and why they stay accurate. The longest is a little over 25,000 words and it's the only note in its project I'd read if I came back after a year away.

One number I didn't expect: 139 of the 304 notes contain at least one markdown table, and only 45 contain a code block. I would have guessed the reverse. Tables turn out to be what a work session actually produces — before against after, target against measured, six findings with a status each. Code goes in the repository. The note holds the comparison that made me change the code.

The whole structure is three filenames

Eight notes in this vault are called `Checklist`. Eight are called `Credentials`. Five are called `Progress, next and missing`. That repetition is the system, and it's most of what makes 304 notes navigable rather than a pile.

The split is 220 dated session notes against 84 standing notes. The dated ones are append-only history and I almost never edit one after the day it describes. The standing ones are the opposite and get rewritten constantly. Knowing which kind a note is before opening it is the entire benefit of a naming convention, and it costs nothing to maintain because the filename carries it.

The open column is the one I read

441 items ticked, 365 still open. Five of the eight projects have more open than done.

If this were a project management tool I'd be looking at a 55% completion rate and feeling bad about it. It isn't one, and the ticked column is the least interesting thing on the chart. Those items are finished and I'm never going to read them again. The open column is the only written record of a project's unfinished business, including the parts I decided not to do and the parts that are waiting on something outside my control.

A checklist where the done column only ever grows would mean I'd stopped adding to it, which for a live project means the list has gone stale rather than the work having finished.

Warnings outnumber confirmations two and a half to one

The notes use three markers. A warning is something that will bite me again if I forget it. A confirmation is something checked against the real thing rather than assumed. An alarm is reserved for anything that cost money or data.

Across 304 notes there are 1,089 warnings, 453 confirmations and 178 alarms. That ratio has a mechanism behind it. A warning is durable, so it goes in and stays in. A confirmation is true at a moment and quietly expires, so it doesn't accumulate. The count isn't telling me the projects are in trouble, it's telling me the two markers have different half-lives.

The risk is marker inflation. If a third of the sentences in a note are flagged as warnings, the flag stops carrying information and I start skimming past them, which defeats the point of having them. The fix I'm applying is a prune: a warning whose cause is gone gets deleted from the note rather than left standing as history. That loses a little of the record, and I'd rather have 400 warnings I read than 1,089 I don't.

The graph is a hub and spokes

887 wikilinks across the vault. 147 notes, just under half, link to nothing at all.

For a while I read that as a failure, because the appeal of a linked vault is the picture where everything connects to everything. What's actually there is a hub and spokes. The summary notes carry 63, 51 and 33 links each, pointing down at the day logs that fed them. A dated note typically carries two, one back to the previous session and one up to the summary, and two is enough for the job it has.

The notes with zero links are almost all short dated notes about a single self-contained thing. I could link them to something, and the link wouldn't mean anything. I'd rather the graph stay sparse and honest, so the hubs remain the obvious entry points when I open a project cold.

Four things the count changed

The measurement was worth doing for these, all of which were invisible to me from inside the vault:

• `description` is on 75 notes out of 304. It's the line that shows up in search results and it's the first thing I read when deciding whether to open a note. Standing notes get it from now on. Dated notes can live without it because their filename is already a description.
• `updated` is on 12 notes. At that coverage the field is decoration, and worse, it implies the other 292 notes are current. Either every standing note carries it or the field goes. I'm keeping it and enforcing it on the five summary notes, which are the only ones where staleness actually misleads.
• 28 distinct tags, eight of which are just the project's own name. The folder already says which project a note belongs to, so those eight tags are a duplicate index that has to be maintained by hand. They're coming out.
• The warning prune, for the reason above.

None of that required a new tool. It required counting what was already sitting on disk.

If you keep notes like this, the count is worth running once. Point an agent at the folder and ask it for notes per project, words per note, how many carry each frontmatter field, how many link to nothing, and how often each convention you think you follow actually appears. It takes one prompt and a script you throw away afterwards. The useful part isn't the chart, it's finding out which of your own rules you've quietly stopped following.

I'll run it again at the end of the year and see which of these four stuck.