← the whole session plugin/skills/insight/SKILL.md

>-

Knowledge Oracles

An "oracle" here means a NotebookLM notebook loaded with a curated pile of someone's own documents — decisions, corrections, domain knowledge, session history — that you can ask a question and get an answer grounded in that specific person's or project's material, instead of your own general knowledge. This is optional infrastructure. It needs Google NotebookLM accounts, the nlm CLI, and time spent curating what goes into each notebook. A fresh install of this plugin has none of it set up.

Is this set up? Check before you rely on it

  1. Run /alignment-harness:harness-setup if you haven't already — it walks through whether oracles exist for this person and records their notebook ids in the switches file, never hardcoded in a skill.
  2. Check alignment-harness config show (or alignment-harness doctor) for an oracle list. If one or more are configured, use the mechanics below against those.
  3. If none are configured, say so plainly — 🔮 No knowledge oracles are set up for this project yet (see /alignment-harness:harness-setup). — and fall back to: searching the project's own docs and notes, git log for relevant history, and the person's past Claude Code sessions (~/.claude/projects/*/*.jsonl, grep for the topic). Report what you found and where you looked, the same way you'd report an oracle's answer. Never silently skip this step and never pretend a query ran when it didn't.

MCP FALLBACK (once you have oracles set up): If mcp__notebooklm__search_recent or any MCP notebook call fails (transport closed, connection refused), use the CLI directly: nlm notebook query <id> "your question" --profile <profile-name>. Never hardcode a notebook id in a skill file or in your own memory — look it up fresh each time via oracle-locate.sh (in this skill's bin/) or your config, since which account holds which notebook can change. The CLI usually installs to ~/.local/bin/nlm and works regardless of MCP server state.

The primary intent behind these tools is to enrich your context-awareness so you align with the existing systems your work touches. Being context-aware radically improves alignment, which radically reduces how much human input is required — the scarcest resource on any project — and reduces hallucinated proposals and artifacts that have to be rewritten to become aligned. When someone asks you to "check the notebooks" or similar, they usually mean: consult our institutionalized memory as a proxy for asking me directly, to enrich your understanding and get your questions answered before you act.

Each oracle is effectively a knowledge base loaded with however many documents of curated material, and you don't know in advance whether it holds what you need. If it can't help, say what would help and propose what data sources might. If it can help but falls short, say what should be added to it, and for what purpose.

Extraction markers (if you're feeding a shared corpus)

If your setup pipes oracle Q&A into a shared data store (an optional refinement, not required to use oracles at all), give each oracle its own marker pair so extraction can route outputs to separate stores. Example scheme — invent your own names to match your own oracles:

Oracle (example name) Opening marker Closing marker
Agent Steering ## ORACLE_AGENT_STEERING ## END_ORACLE_AGENT_STEERING
Product Intent ## ORACLE_PRODUCT_INTENT ## END_ORACLE_PRODUCT_INTENT
Session History ## ORACLE_SESSION_HISTORY ## END_ORACLE_SESSION_HISTORY

Print the marker on its own line before your output, and the closing marker on its own line after — only if you've set this extraction pipeline up; otherwise skip the markers and just answer normally.

Whenever you call an oracle, create observability by printing in this format:

## ORACLE_{ORACLE_NAME}
📚 ── Oracle: {Oracle Name} ──────────────────────────
🔧 Command run: nlm notebook query {id} "{exact question text}" --profile {profile}
❓ Why I asked this: {what you were trying to find out and why right now}
💭 Intent: {what you hoped the oracle would unlock}
📋 Response from {Oracle Name} (verbatim — never summarize):
{everything it returned, word for word}
────────────────────────────────────────────────────────
## END_ORACLE_{ORACLE_NAME}

Never summarize the response — verbatim is what feeds any downstream extraction, and it's also just more honest to the person reading it.

You can call an oracle many times to dig deeper into a topic, and complement it with your institutional-memory search tool (agent_find or whatever your setup uses — see /agentic-find) to pull from a different kind of memory: a semantic search across whatever documents you've indexed, rather than a curated notebook.

Find the Right Oracle — build your own version of this table

The value of this skill is having a routing table like the one below for your own oracles, so you (or any agent) can pick the right one at a glance instead of guessing. When you set oracles up via harness-setup, write your own version of this table into your project's own notes. Categories that generalize across most setups:

For situations like... Query this kind of oracle
Know if what I'm about to do follows the rules An "agent steering" oracle — operating protocol, banned antipatterns, standing corrections
Understand what a feature is supposed to do for users A "product intent" oracle — UX intents, why decisions were made
Know what was tried before and what happened A "session history" oracle — past decisions, past incidents
Domain-specific expertise your product depends on A domain-expertise oracle (a common example is a coaching-principles vault — see the example below)
Explain the business to an investor or partner An "investor/business context" oracle
Know the right tone or constraints for user communication A "communication design" oracle (email, in-app messaging, etc.)
Synthesize insights that span multiple domains at once A "cross-domain" oracle built from all the others combined
Know how the person you're working with THINKS about something, in their own words A "voice/reasoning posture" oracle built from raw transcripts, if one exists
Predict how the person would react to your work before presenting it A reaction-predictor skill (see /jonathan-check2) rather than a notebook oracle

Related: a reaction-predictor skill — "what would they say to this?"

Not a notebook — a skill that predicts what the person you're working with would say to YOUR output, ideally built from real past agent-to-person exchanges if you have them. /jonathan-check2 is one example, built on a notebook of thousands of real agent-to-person conversations; if you don't have an equivalent, /jonathan-check2's own fallback reasons from the person's stated preferences and past sessions instead (see that skill).

Use it first when:

  • you've finished work and want to simulate a review before presenting — if it takes issue with your work, treat the feedback seriously: fix what it names or push back if you disagree, but don't ignore it
  • you have a question for the person you're working with — always try this first, before asking them directly, including several focused calls

A good reaction-predictor knows almost every way you could fall into hallucination or half-finishing a task without realizing it (like forgetting to validate a user-facing change in the browser); if you describe exactly what you did, why you think it's done, and what steps you took, it can give you instant feedback on gaps you missed.

Don't use it for: domain knowledge queries (use the oracles above). This is specifically for predicting a specific person's response to your output.

Example: a fully fleshed-out oracle set (opt-in reference — replace with your own domains)

This section shows what a fully fleshed-out set of oracles looks like in practice, built for a coaching-software company. None of these notebooks ship with the plugin or exist for you — they're here so you can see the shape of a good oracle description (what it knows, what to ask it, what NOT to ask it) and copy the pattern for your own domains.

Agent Steering — "The rules of the road"

This example notebook knows the entire operating protocol — every rule, every antipattern, every standing correction, every workflow definition. It tells you how agents should behave, what processes to follow, what mistakes to avoid, and what gets the person frustrated. When you're about to act and want to know "am I doing this right?", this is the kind of oracle to ask.

Ask it:

nlm notebook query <id> "your question" --profile <profile>

Good questions:

  • "When an agent finds unused code, what should it do?"
  • "What are the rules about committing changes?"
  • "What process should I follow before implementing a non-trivial feature?"

Don't ask it: What features to build (Product Intent), what happened in past sessions (Session History), or domain-clinical/expert questions (a domain vault).

Product Intent — "What we're building and why"

This example notebook knows every UX intent — each with testable conditions and expected outcomes — plus the company's strategic direction: mission, vision, values, pricing philosophy, growth strategy. It can tell you what a feature is SUPPOSED to do, which is different from what it currently does. In practice, this kind of oracle has found real implementation bugs by comparing intended placeholder text against what was actually built.

Ask it:

nlm notebook query <id> "your question" --profile <profile>

Good questions:

  • "What is the intended UX when a new user first arrives?"
  • "Why did we choose this pricing model?"
  • "What should happen when a user reaches the paywall?"

Don't ask it: How agents should behave (Agent Steering) or what happened in specific sessions (Session History).

Session History — "What happened and what was decided"

This example notebook is institutional memory: the highest-leverage work sessions ever recorded, personal playbook entries on sales and strategy, and thousands of typed knowledge atoms — corrections, findings, patterns, decisions, mental models, workflows, and open questions. When you need to know "has anyone tried this before?", this is the kind of oracle to check.

Ask it:

nlm notebook query <id> "your question" --profile <profile>

Good questions:

  • "What decisions were made about the coaching quality evaluation system?"
  • "What problems did we hit when working on authentication?"
  • "What mental models have been documented about agent alignment?"

Don't ask it: Protocol rules (Agent Steering) or domain-clinical approaches (a domain vault).

Domain-Expertise Vault (example: a coaching-principles vault) — "The depth behind the domain"

This example notebook has clinical precision no general-purpose notebook matches — it holds hundreds of principles across dozens of therapeutic lineages (CBT, ACT, motivational interviewing, Socratic questioning, somatic approaches, and more), each with evidence citations, leverage scores, and warnings about when a technique helps versus when it backfires. Whatever your own product's deep domain expertise is (legal, medical, financial, pedagogical, whatever), this is the oracle shape for it: not just "use technique X" but which specific technique, and what to watch out for.

Ask it:

nlm notebook query <id> "your question" --profile <profile>

Good questions (coaching example):

  • "What therapeutic approach should the coach use when a user is stuck in rumination?"
  • "What's the clinical evidence for using Socratic questioning with resistant clients?"
  • "When does direct cognitive challenge backfire?"

Don't ask it: The technical pipeline that delivers the domain content (that's code) or individual user sessions. It's a different domain than an "Agent Principles Vault" (below) — this holds expertise for the end-user-facing domain; that one holds operational patterns for how agents should behave.

Investor / Business Context — "Why this business exists"

This example notebook answers the "why" questions: full strategic intent — mission, vision, values, growth thesis — plus hard-won lessons about sales, markets, and leadership, and any published essays explaining the technical moat, unit economics thesis, and product overview. When you need to articulate what the product is and why it matters to someone who isn't living in the codebase, this is the kind of oracle to use.

Ask it:

nlm notebook query <id> "your question" --profile <profile>

Good questions:

  • "What is this product's competitive moat and why is it defensible?"
  • "What's the thesis behind the pricing strategy?"
  • "How does the quality system create a flywheel?"

Don't ask it: Operational details, agent rules, or technical implementation.

Communication Design (example: Email Design) — "How we talk to users"

This example notebook knows the full communication playbook: canonical voice rules, the user-journey stages that determine what kind of message someone gets, any personalization pipeline, re-engagement triggers, anti-spam/anti-annoyance constraints, template catalog, and governance rules.

Ask it:

nlm notebook query <id> "your question" --profile <profile>

Good questions:

  • "What tone should re-engagement emails use for users who haven't opened the app in 2 weeks?"
  • "What are the subject line constraints?"
  • "How does the personalization pipeline work for this channel?"

Don't ask it: Individual user data or domain content that goes inside the message (a domain vault).

Cross-Domain Deep — "How everything connects"

This is a meta-notebook built from content across ALL the other domains at once — UX intents, strategic intents, domain principles, and recent session history. Use it when a question spans multiple domains and you need synthesis, not depth. "How does the domain philosophy influence product decisions?" "How do agent rules connect to business strategy?" This kind of oracle can answer because it was built to see across the boundaries the single-domain oracles respect.

Ask it:

nlm notebook query <id> "your question" --profile <profile>

Good questions:

  • "How does the domain philosophy connect to product decisions and agent behavior?"
  • "What patterns appear across both the domain and product intent?"
  • "How do recent sessions relate to our strategic direction?"

Don't ask it: Domain-specific depth — for that, use the domain notebook. This one is jack-of-all-trades, not deep expertise.

Voice / Reasoning Posture (example: "Silver Grail") — "How they actually think, unfiltered"

This is the only example notebook built from raw interview transcripts rather than documentation. Every other notebook here sounds like documentation (accurate but neutral); this one sounds like an actual person talking — their specific phrases, their actual reasoning posture, not a paraphrase of it. When you need to understand how the person you're working with THINKS about something — not the rules, but the reasoning and posture behind the rules — this is the kind of oracle to use, if you've built one.

Ask it:

nlm notebook query <id> "your question" --profile <profile>

Good questions:

  • "What matters most to this person when agents communicate about their work?"
  • "What are the most common mistakes that frustrate them?"
  • "How do they think about trustworthy AI agents?"

Don't ask it: Specific protocol rules or scoring thresholds (Agent Steering). This is philosophy, not operations.

Agent Principles Vault — "What we already learned the hard way"

This is the operating memory of everything that's been corrected, validated, or discovered across many past sessions — principles that surfaced from real failures, not rules someone wrote in advance. An example built this way knows things like: which metric is the authorized ground truth for a quality measure and why naive proxies are gameable; which third-party analytics numbers are known to be wrong and must be cross-referenced against a source of truth; what "intentional debt" looks like versus an actual bug; and exactly what a fail-open safety net is for, and why treating it as a product feature is dangerous. Before touching any high-stakes domain (payments, a core user experience, communications, ads, access tiers), this is the kind of oracle to ask what the known failure modes already are.

Ask it:

nlm notebook query <id> "your question" --profile <profile>

Good questions:

  • "What are the known failure modes when modifying the payment webhook?"
  • "What's the ground truth metric for [core quality measure] and why?"
  • "What does intentional debt look like in [a specific subsystem]?"

Don't ask it: What to build next (Product Intent), which protocol rules govern agent behavior (Agent Steering). It's a different domain than a domain-expertise vault — this is agent operational patterns learned from real failures, not expertise for the end-user-facing domain.

Workflow Construction Oracle — "How to build pipelines that don't hallucinate"

This example was built from a session where an early pipeline hallucinated in nearly half its outputs, and a redesign fixed it — the failure modes documented here are all real, from that system. It knows validated pipeline stages (adversarial design, cross-verification, an oracle gate, a scope guardian, etc.), the anti-patterns that cause scope reduction and destructive interpretation, and how to extract a working methodology from a successful session before it's lost to compaction. The critical insight, true for any such oracle: verification requires external evidence (curl, UI state, DB query) — an agent's self-assessment is not verification.

Ask it:

nlm notebook query <id> "your question" --profile <profile>

Good questions:

  • "How do I design a pipeline to prevent scope reduction?"
  • "Why did this agent pipeline fail, and how do I patch it?"
  • "How do I turn a successful manual session into an autonomous workflow?"

Don't ask it: Single-agent task execution, risk scoring, or domain-specific pipeline design.

Strategic Blueprint — "Why the system is built this way"

This example notebook is the philosophical and architectural blueprint behind a product — the "why" behind the system's design, distinct from the raw voice-texture notebook above. It might contain a core growth mechanism and the numbers behind it, a scoring algorithm and what it optimizes for, a named core technical/business mechanism defined precisely, and the thesis that mission and unit economics are one system rather than two.

Ask it:

nlm notebook query <id> "your question" --profile <profile>

Good questions:

  • "What is the core growth mechanism and why does it work?"
  • "How does the scoring algorithm work and what does it optimize for?"
  • "What is [the named core mechanism] and why is it central?"

Don't ask it: Voice texture (the Voice/Reasoning Posture oracle), operational failure modes (Agent Principles Vault), or specific UX intents (Product Intent).

Operational Audit — "Financial intelligence and tactical roadmap"

Granular financial performance intelligence: payback curves per cohort, ROAS, LTV by acquisition channel, segment-specific insights, a strategic execution roadmap with leverage ideas, and architectural standards for building production-grade agentic systems. The place to go when you need the actual numbers, not the thesis.

Ask it:

nlm notebook query <id> "your question" --profile <profile>

Good questions:

  • "What payback period do mature cohorts reach and at what day?"
  • "Which acquisition channels perform best by LTV/CAC ratio?"
  • "What architectural standards apply to production agentic systems?"

Don't ask it: The strategic thesis behind the numbers (Investor/Business Context), domain-clinical techniques (a domain vault), or agent behavioral rules (Agent Steering).

Don't Know Which Oracle? Search all of them at once

If you have multiple oracles set up, fan a question out across all of them:

# Via MCP (if a notebooklm MCP server is running locally):
mcp__notebooklm__search_recent({ question: "your question", max_notebooks: 8 })

# Via CLI (queries your most recently used notebooks):
nlm cross query "your question" --max 8

Note: nlm cross query may not support every --profile. If it fails, pick your broadest cross-domain notebook (if you have one) as a manual target instead.

Full Consumption Guides (example)

Keep a detailed guide per oracle — 12-15 use cases, answer format, boundary descriptions, maintenance info — in your own repo; it doesn't need to ship with this plugin. If you build out several oracles, a per-oracle guide like that is worth writing for your own team; there's nothing plugin-specific about the practice.

Keeping Oracles Fresh (example)

Oracles go stale the moment the underlying documents change. Refresh them by re-running a set of small export scripts in your own repo (one per oracle: corrections/knowledge, intents, domain principles, business context, knowledge atoms, recent session compactions) and re-uploading the output. If you build your own oracles, write the equivalent for your own data sources — the pattern is "one script per oracle, each producing the current export of whatever that oracle should know," not the specific scripts themselves.