An AI skill that merges new source material (a lecture, a chapter, a paper) into the notes you already have — with conflict detection, tier-gated writes, and mandatory citations. It supplements your notes; it never silently rewrites them.
🧰 Sibling projects: textbook-to-note (write NEW notes from textbooks) ｜ 🔎 vault-search (the semantic search this skill calls) ｜ 🧪 openevidence-tools (optional evidence enrichment)
I have thousands of notes, built up since med school, and new material never stops arriving — a lecture today, a new edition chapter next week, a paper worth keeping tomorrow. The naive move is to hand the new material to an AI and say "update my notes." That fails in a specific, dangerous way: the risk isn't that the AI misses new content — it's that it quietly overwrites the things your old notes already got right. You won't notice, because the output still looks like a good note.
The first version of this skill answered that with a rule I was rather proud of: no factual disagreement is ever resolved automatically — every one of them waits for you. Actually running it taught me that was fake safety.
An unbounded review queue gets rubber-stamped. By item twelve you are pressing accept, and "held for your judgment" has quietly become "auto-applied with extra steps" — worse, because each conflict came with a "here's my recommendation" line that anchored me before I had read either claim. And refusing to decide is itself a decision: while a conflict sits in a queue, the incumbent claim stays authoritative inside the note, so a possibly-stale value wins by default.
So v1.1 keeps the asymmetry and changes what follows from it: adding is cheap, changing is expensive — so changes are made non-destructive instead of forbidden.
- Append-with-citation is auto-approved. A new bullet with a source attached can't hurt the note.
- Conflicts are typed and routed, and nothing is ever deleted. A new edition superseding an old one auto-applies with the old value kept struck-through, cited and dated. A genuine dispute that isn't worth interrupting you for is written into the note as an inline conflict block quoting both claims verbatim — resolved at read-time, the next time you open that note, when you have more context and more attention than any end-of-run queue will ever get.
- Only the high-stakes disputes interrupt you, and at most five per run. A cap you can actually clear beats a queue you won't read. High-stakes blocks carry no recommendation line, on purpose.
- Restructuring and new-note creation always wait for review.
One skill, two modes:
Single-target mode — you have a source and roughly know which note it belongs to. The skill reads the source, finds candidate target notes by semantic search, you pick 1–3, and it produces a structured supplement report: conflicts first, then supplement drafts, format improvements, and — just as important — what the target already covers and what it has that the source doesn't.
Scatter mode (--scatter) — one source touches many notes (a review lecture, a guideline update). The skill extracts ALL concepts, finds every related note, and processes each one with tier-gated approval:
| Change type | Tier | What happens |
|---|---|---|
| Append factual bullet + citation | T1 | auto-written, logged in changelog |
| Add an exam/priority marker to an existing line | T1 | auto-written, then byte-checked — the line minus the marker must be identical to the original |
| Converting existing bullets into a table | T2 | held for your review — it's a rewrite, and column-binding corruption is silent |
| Factual conflict with existing note | routed | superseded edition → auto-applied non-destructively (old value struck-through, cited, dated) · low-stakes dispute → inline conflict block, resolved at read-time · high-stakes dispute → synchronous review, capped at 5 per run |
| Section restructure | T2 | held for your review |
| New note needed | T3 | held for your review |
A note holding a conflict that's waiting on your decision also holds back the T1 items next to it (same section, or anything that presupposes the contested fact) — otherwise you'd be reviewing a conflict against a note that has already moved. Everything else is written immediately.
You review only the items that need judgment; the mechanical 80% happens without you. Every run ends with a changelog of exactly what was written where — appends, supersessions, conflict blocks and rejections, and the numbers have to reconcile.
The generalized version of this design — for team wikis, agent memory, any knowledge base that isn't medical — is written up in docs/the-pattern.md.
These came from real failures, not design sessions:
- A section coverage ledger, not a second pass over my own draft. v1.0 re-read the source using its own draft items as search queries; that mechanism is gone, because queries derived from what you already found cannot surface a topic cluster you missed entirely — the miss is invisible to itself. Instead every heading in the source gets an explicit verdict (produced items / already covered / NOTHING), the ledger ships as part of the report, and every
NOTHINGheading is re-read before the report is final. On long sources a second, structure-blind lens runs alongside it: list every claim in the source absent from the target, ignoring section alignment entirely, and flag on either lens. - Source qualification before anything is read for content. Your own lecture notes or a textbook chapter are
TRUSTED; an AI-generated summary or a third-party document you can't trace to a primary source isUNVETTED— and one unvetted source demotes the entire run to manual, because trust is a property of the document, not of individual claims. - Sources and targets are different universes. Raw incoming material (inbox, lecture dumps) can never become a supplement target — otherwise the AI happily "supplements" your unprocessed junk and grows a second, worse vault beside your real one.
- Empty-section scan. Permanent notes usually follow a template, and templated sections sit empty for years. Before comparing, the skill lists each empty section in the target with a proposed source to fill it (evidence sections → literature search; mechanism sections → textbook chapter), and asks once.
- Citations are non-negotiable. Every written bullet carries its source. If something genuinely has none, it gets an explicit
⚠️ agent-inferredmarker instead of blending in. - A self-check gate before every write — mechanical checks (broken links/embeds, placeholder citations) plus semantic checks a linter can't do (no uncited filler, no language drift, no banned sources leaking in as citations).
This is a skill file for Claude Code (works as a slash command; the pattern ports to any agent framework that can read a markdown playbook):
- Copy
skills/note-supplement/SKILL.mdto your project as.claude/commands/note-supplement.md - Replace the placeholders at the top (
{NOTES_DIR},{SOURCES_DIRS},{SEARCH}) with your vault's layout - Run
/note-supplement <source file>inside your vault
A semantic search index makes target-finding much better — I use vault-search — but plain Grep works to start.
For the mechanical half of the self-check gate, run python scripts/gate_check.py <note.md> [--vault-root <dir>] (stdlib-only) — wire it as a pre-write hook if you want it enforced automatically.
See examples/example-session.md for a full worked session (source → conflict report → tiered writes → changelog).
- Not a note writer — for producing new notes from textbooks, see textbook-to-note
- Not a summarizer — it deliberately refuses to compress or restyle your existing content
- Not autonomous — but it doesn't pretend to escalate everything to you either. It bounds what interrupts you (five conflicts a run, high stakes first) and makes everything else non-destructive and reviewable in place, in the note, when you next read it
MIT © Po-Wei Chen (drpwchen)
This tool is one piece of my personal AI workflow. If you want to learn how to use AI agents like Claude Code from zero (no programming background needed), I wrote a beginner series (in Traditional Chinese):
這個工具是我個人 AI 工作流的一部分。想從零開始學怎麼用 Claude Code 這類 AI agent（不需要程式背景），可以從我的入門系列開始：
Full map of my tools and posts ／ 所有工具與文章的全貌 → drpwchen.com/map