Skip to main content

Featured

The Docstring Coverage Gate Is the Product: What I Verified in AI Doc Generator

The Docstring Coverage Gate Is the Product: What I Verified in AI Doc Generator Documentation debt never announces itself. It shows up as the three hours you lose reading a function called process_data2 , or as the README that documents an argument the code stopped accepting two refactors ago. Every team knows the number that matters is documentation coverage, and almost nobody has a cheap way to measure it, let alone gate a merge on it. That is the specific pain I went looking for a tool to solve, and it is how I ended up testing AI Doc Generator — a $49 single-file Python CLI that scans a codebase for undocumented functions and classes. This post is what I actually measured in the bundle, on my machine, from a clean copy. Including the parts that don't work. Yes, it is a product I sell, and this article says so plainly rather than dressing up as a neutral review. The real problem: coverage is invisible until it is a crisis Ask a team what fraction of its public functions...

A PhD Reading Queue Is Not a Note-Taking Problem. It Is a Retrieval Problem.

A PhD Reading Queue Is Not a Note-Taking Problem. It Is a Retrieval Problem.

Every doctoral researcher I know has the same failure, and it is not laziness. You read a paper in March, you write something about it somewhere, and in September you need that specific finding for a chapter argument — and you cannot find it. Not because you never wrote it down, but because you wrote it down in four different places with four different shapes: a highlight in the PDF, a line in a notebook, a Zotero item with a half-filled note field, and a bullet in a document called thoughts.docx.

So you re-read the paper. You spend forty minutes finding a claim you already found once. Multiply that by a thesis.

The useful lens is retrieval, not capture. Capture is cheap and every tool does it. The question that decides whether a literature workflow survives contact with a real chapter is: given a claim I half-remember, can I get to the exact paper, the page, and the place I already used it, in under a minute?

We built a small kit around that question. It is fifteen plain markdown files and one stdlib Python script, not an app. This article explains the structure it enforces, what it deliberately does not do, and who should not buy it.

What actually breaks in month six

Four failures show up in almost every academic vault we have looked at, and none of them are solved by more note-taking.

One: the note has no address. A literature note named "Smith et al — interesting" cannot be linked to, cited, or found again. Without a stable identifier per paper, every note is an island.

Two: the atom and the paper are confused. A single paper contains many claims. If you write one long note per paper, you cannot reuse one claim in two chapters without copy-pasting it. If you write only atomic claims, you lose the paper as a unit and cannot answer "what did I think of this paper overall."

Three: the queue has no vocabulary. A reading list with 180 unread items and no defined states is a guilt generator. Nothing tells you what to read this week, and so you read whatever arrives in the inbox instead.

Four: nothing ever reaches the draft. The vault grows, the chapter does not. There is no path pointing from a claim to the section that uses it, so the writing stage starts from zero every time.

The shape the kit enforces

The bundle is a set of conventions plus templates, and the conventions are the product. Five folders, one command:

mkdir -p Literature Zettel Projects/Thesis-MOC Meetings Templates Prompts Data

Each folder answers one of the four failures above.

Literature/ holds exactly one note per paper, named by a citekey derived from a fixed scheme: surname, year, first title word, lowercased ASCII, leading articles dropped. So Okonkwo, "Spaced Retrieval in Doctoral Cohorts", 2023 becomes Literature/okonkwo2023spaced.md. That filename is the address. A citation is now a wiki-link, and the link works in Obsidian, in a text editor, and in a grep.

Zettel/ holds atomic notes: one claim each, named okonkwo2023spaced-001.md. The prefix is the paper's citekey, which is the retrieval trick that matters. From a claim you can walk back to the paper; from the paper you can list every claim you extracted from it, without a database.

Projects/Thesis-MOC/ holds chapter maps-of-content: the only place a claim is linked to a section of your argument. This is the folder that answers "where did I use this?" — because the answer is written down in one place instead of remembered.

Meetings/ holds supervisor meeting notes with a decisions block and an action-item table, so that the same three questions do not get re-asked every month.

Data/ holds the reading queue as a plain CSV: citation_key, title, first_author, year, added_date, triage, priority, status. Twelve rows are pre-populated as a working example.

Getting papers in: two documented paths, neither of them magic

The honest version of "Zotero integration" is that Zotero has no official Obsidian bridge, so there are two working routes and you pick one.

Path one: a community plugin. zotlit or obsidian-zotero-integration connect a running Zotero to your vault and create one literature note per item on demand, with the eleven front-matter fields the template expects. This is the fastest per-item route and it is genuinely good software. It is also third-party, so it moves when its maintainers move.

Path two: a CSV export and one command. Select the items in Zotero, export as CSV (not BibTeX), confirm the header row matches the documented shape, then:

python3 tools/zoterocsv2notes.py zotero-export.csv --out-dir <vault>/Literature

That script is the only executable thing in the bundle. It is stdlib-only, needs Python 3.8 or newer, makes no network calls, and ships with a selftest you can run before trusting it:

python3 tools/zoterocsv2notes.py --selftest

Expected output: SELFTEST PASS. If you get a failure, your Python is too old or the file was corrupted in transfer — check with python3 --version before blaming the script.

One caveat that is documented rather than hidden: the CSV export shape does not carry venue or Zotero URL, so the utility leaves both fields empty. You fill them in when you open the note. A plugin path fills them for you. Neither route is wrong; they trade a dependency against two manual fields.

The reading queue has four states and that is the whole system

The triage vocabulary is fixed: read-now, skim, defer, reject. Four states, no custom taxonomies, no fifth option for the paper you feel guilty about. Anything that is not read-now is explicitly not this week's problem, and reject is a legitimate, recorded decision rather than an unread item that rots at the bottom.

The queue also ships an AI prompt pack: eight prompts, each targeted at one stage of the pipeline rather than "summarise this paper." A title-and-abstract triage prompt that assigns a state and a one-line reason. A methodology red-flag check. A related-work gap finder. A claim-to-atomic-note extractor that emits the note's four body sections. A contradiction steelman, which asks the model to argue the strongest case against a claim you are about to build on. A supervisor-meeting brief generator that produces a four-block agenda from queue states. A related-work paragraph drafter. A BibTeX field mapper for the exports that arrive in the wrong shape.

Two things about that pack, stated plainly. The prompts are text files you paste into whatever assistant you already use; the kit does not call any API, and nothing in it is an integration. And a model's summary of a paper is not evidence that the paper says what the summary says — verify anything you would cite, in the source, before it reaches a draft.

Worked examples, because templates alone do not teach a pipeline

Two files walk the same fake research project end to end. Worked-Example-A.md takes one paper from a Zotero export row through the literature note, three atomic notes, and a chapter MOC entry. Worked-Example-B.md takes that same project through a supervisor meeting, a MOC update, and an actual thesis draft paragraph, with the claims linked back by citekey.

Both use invented papers with invented findings. They are illustrations of structure, not research findings, and every figure in them is fabricated for the example.

That is the part that free vaults do not usually include, and it is the honest reason this is a paid file rather than a free repo. What you are buying is curation: one consistent convention set, two worked paths through it, and a triage prompt pack. Not features. Free community academic vaults and plugins exist and are genuinely good — bramses, PaperBell, and zotlit are all free and open, and if one of them fits how you work, use it and keep your money.

Who this is not for

The boundary is more useful than a feature list, so here it is without softening.

Skip it if you want a Zotero replacement. This is not a reference manager. Zotero stays where it is; the kit is the vault on the other side of the export.

Skip it if you need collaboration. There is no sync service, no sharing, no permissions, no commenting, no multi-user anything. It is files in a folder that you back up yourself.

Skip it if you need your department's citation style enforced. The kit generates citekeys and front matter. It does not know whether your school wants APA, Harvard, or a local variant, and before you cite anything in submitted work you should check your institution's rules rather than trust a template.

Skip it if you will not fill in the queue. An empty triage column is a template with someone else's example rows in it. The system is four words of discipline per paper; without that it is fifteen markdown files.

Skip it if you have never used Obsidian and do not want to start. The setup guide claims about fifteen minutes for the folder skeleton, template copy, CSV import, and first-run checklist. That is accurate for someone comfortable with a terminal or a file manager. It is not a one-click app install, and it is not a web service.

And the explicit non-claims, since this is where most product pages get vague: the bundle ships no CRM, no map or navigation integration, no API, no dispatch software, no employee scheduling, no GPS tracking, no automated anything, no invoicing, and no payment processing. Nothing in it connects to anything. It is fifteen files that you open and edit.

The kit, the price, and the disclosure

ResearchVault — The PhD & Researcher Obsidian Vault is available at the ResearchVault listing on Gumroad. The current intro price is $1.00, verified against the live listing on 22 November 2026. It is an intro price on a ladder that can step up later, not a permanent promise, so check the listing before you buy.

Disclosure: this post links to a product we made. If you buy through the link, we may earn a commission at no extra cost to you. We also have zero verified sales of it to show you, and no reviews or testimonials to cite, because inventing either would be the fastest way to lose your trust and we would rather have the $1 honestly.

Honesty block: example figures are illustrative planning inputs — not market rates and not earnings. No legal, tax, insurance, licensing, veterinary, automotive-repair, or financial advice. No claims of CRM, map, API, or invoicing integrations the bundle does not ship.

One more piece of evidence, because a keyword claim is not a demand claim. The reasoning behind this product came from search-intent work: people consistently search for combining Zotero with Obsidian, for literature-note templates, and for how to organise a reading queue. That is intent density. It is not search volume, it is not purchase proof, and it does not tell you this kit will work for your thesis. The structure either matches how you think or it does not.

Keep reading

If the retrieval frame here was useful, the same pipeline appears in a longer write-up: from Zotero export to thesis draft, walked paper by paper shows the citation pipeline with real export rows and the failure modes that come with them. Our study-vault walkthrough for students covers the semester-long lecture-note case, the $15-to-$99 vault comparison explains what those paid vaults actually contain, and the five-minute starter vault is the shortest path if you have never opened Obsidian at all.

Corrections and questions are welcome. If we got a fact wrong — including anything about your institution's citation requirements — write to nandminc2020@gmail.com and we will fix it.

Comments