local-research-runner

Local Research Runner

Drain the "To do" queue of a local JSONL research tracker (the kind initialized by the local-research-db skill) by researching each task with a subagent and writing findings as markdown files into the vault's raw/notes/ directory. The standard McBrain ingest flow then picks those files up — there is no special "local-bridged" ingest mode.

Prerequisites

• The vault must be a McBrain vault — registered in ~/.mcbrain/registry.json (visible via the mcbrain MCP server's list_vaults tool). Every <vault> path in this skill means the absolute path from that registry entry.
• The vault's CLAUDE.md must have ## Research tracker → Backend: local.
• The vault must have raw/research_tasks/tasks.jsonl (created by local-research-db).
• Python 3 must be available on the user's host (for the atomic-write helper). No third-party packages, no extra CLI tools (no flock(1), no lockfile, no filelock). Standard library is enough on macOS, Linux, and Windows alike.
• The Agent tool must be available (for spawning research subagents). WebSearch / WebFetch are used by the subagents, not by this skill directly.

Inputs to Collect

1. Which topic to drain. Read ## Research tracker → Topics: from CLAUDE.md.
   • One topic registered → use it.
   • Multiple topics → if the user named one, use that; otherwise ask which.
   • Zero topics → tell the user no topics are registered and stop.
2. Batch size. Default 5. If the user asked for a different cap, honor it. Never exceed 5 in one run without explicit confirmation — parallel research burns tokens fast.

That's the entire input set.

The Atomic Write Protocol — read this once

Every modification of tasks.jsonl (claim, status flip, notes_path write) goes through the protocol documented at references/atomic_write_protocol.md. Read it before writing any code that touches tasks.jsonl. The summary:

• Acquire an exclusive lock by os.open-ing tasks.jsonl.lock with O_CREAT | O_EXCL | O_WRONLY. The file's existence is the lock; its contents are unimportant. Acquire timeout: 5 seconds.
• Modify the data: read the whole tasks.jsonl into memory, mutate, serialize to a temp file in the same directory, os.fsync, then os.replace the temp over the real file. (os.replace — not os.rename — because Windows.)
• Release the lock by os.unlink-ing the lock file.
• Wrap acquire/release in try/finally.