research

Start in the notes

python3 $VAULT/.scripts/notes.py -m "<subject>"

That one search ranks topics/, analysis/, and sources/ together, so prior conclusions and the evidence under them arrive in the same list. $VAULT/.claude/rules/notes.md covers the search discipline that makes it land: several phrasings, the jargon and the plain words, and -x for an exact symbol. Read down from topics/index.md for the standing account, open the analysis/ notes it points at, and read the sources/ files that bear on the question.

None of this is grounds to stop, narrow, or skip a pass. It is context you start from, not an answer you inherit. When a prior note asserts something load-bearing, open the source under it instead of taking the claim.

Fix a slug here, {topic}-YYYY-MM. Every source landed during the pass writes it into supports, the reverse edge back to the note. Add slugs as the pass splits into more notes, and use unfiled only for a source whose note arrives later in the same pass.

The roster

Every round runs these seven stages in this order. The cut between them is not a judgment call. Fixing it is the point: each stage does one job, at the tier that job is worth, and cannot quietly take on the next one.

Four rules make the table binding:

• Only stage 4 writes to sources/. No agent in any other stage runs --out, to-markdown.py, or any converter. This is the gate the 460-file July 2026 pass did not have.
• Only stage 5 opens a full source, and it opens the landed file. Never a digest of one. A claim in a note is traceable to text an opus agent actually read, which is why stage 3 is forbidden the full text and stage 5 is forbidden a summary.
• Only stage 6 writes to analysis/ or topics/. Stages 1 through 5 return findings to the orchestrator and write nothing to the notes.
• No agent asks the user anything or runs git. Batching one question and one commit at stage 7 is why a sixty-source pass interrupts once.

Model tiers are fixed above rather than chosen per dispatch, because the failure they prevent is asymmetric. Haiku deciding "this paper is off-topic" is cheap and visible when wrong. Haiku deciding "this paper supports the claim" is neither: a confidently wrong claim reads exactly like a right one.

Bound every agent, and say the bound in its prompt. A scope is the question, the surfaces worth trying, and a cap on calls. Unbounded prompts reliably buy 60 to 90 tool calls apiece for findings that plateau far earlier.

Surfaces are options

surfaces.md is the menu: every command verified on this machine, with the traps that make each one fail silently. Stage 1 picks from it, stage 2 runs what stage 1 picked. It lists what is available, never what to run.

Which surfaces a question earns is a stage 1 decision. A question about an algorithm may want papers and code and nothing else. A market question may want vendors, forums, and case law. Something that happened this month may want X and nothing older.

The machine is a surface too. Project code, docs/, past scratchpads, ~/Downloads, config, logs, transcripts, cited by path and line like anything else. Sweep for it when the subject plausibly touches work already on disk, and skip it for a purely external question.

Run the local sweep at stage 0, never alongside stage 4. sources/ is on disk, so a sweep running next to the stage that lands files reads what that stage is writing and reports it as material the machine already held. That happened in July 2026: 40 confident hits on a subject the vault held nothing about, every one written minutes earlier by a sibling.

Passes, plural

One round is the floor. Each round ends with a list of what it opened up, and anything on that list that matters earns its own round: a vendor named once in a forum thread, a paper three sources lean on, a repo everyone wraps.

Show the first round before spending the second. Say in two lines what it found and what the next cut would chase. A pass that runs several rounds before the owner sees anything has bet the whole budget on a reading of the question nobody confirmed.

Spend at least one round trying to break the answer rather than extend it, with stage 5 agents prompted to refute, and take seriously whatever survives. Stop when a round stops changing the answer.

python3 $VAULT/.scripts/vault.py <url> says whether a URL is already held, and a source another agent landed is still evidence. Its dedupe is weaker than it looks: it collapses the several forms of one arXiv or YouTube id, but not a paper living on both arXiv and PhilSci-Archive, and not an abstract page against the full PDF of the same document.

Evidence

• Every load-bearing claim carries a quote and a locator. Page, section, line, timestamp, retrieval date. A claim you cannot point at is a claim you are guessing.
• Do not summarize sources. sources/ holds each one in full and says it better. What matters is what a source changes: which existing note it confirms, contradicts, refines, or has no bearing on.
• Contradictions lead. A source that collides with an existing note is the most valuable thing a pass produces. State both propositions, say which is better evidenced, and put it at the top.
• Cite or flag, cut only what is fabricated. Thin support gets marked and kept, because the marking is information. A citation that does not resolve, or a quote absent from the source it names, gets cut and the cut named in the note.
• Independence is by cluster. Three blog posts citing one paper are one source.
• Write down what you could not reach: the blocked API, the WAF, the expired session, the scanned PDF, the results ranked below where you stopped reading. Each reads as an empty field unless the note says otherwise, and a silent zero is the one unacceptable outcome.

Land it

Stage 6 writes everything at once, after the passes are done.

• analysis/, one note per operational fact or per dated pass. Findings answering different questions are different notes, not one long file.
• topics/, rewritten in place for every subject the pass touched, and written when a subject has none. This is the layer read first, so a pass that stops at analysis/ has left its conclusion somewhere already dated. The fold-up stops two hops out, per $VAULT/.claude/rules/notes.md.
• Existing notes, edited where the pass refined or overturned them.
• sources/, everything cited, with supports pointing back. What earns a place there is add-source.md, and it is judged on the read rather than on any property of the file.

$VAULT/.claude/rules/notes.md routes the rest, one file per step: acquiring, deciding an edit against a new file, frontmatter, wikilinks, pruning what the change made dead, and closing out.

Repeat passes

A subject already covered gets a full pass, not a shortened one. The prior note says what to hold up against fresh evidence and what to recheck first. It is not a list of closed questions. Write what changed, what died, and what is new, and edit the prior note where this pass overturned it.