# Bootstrap Guides from the context you already have > Use an AI agent to harvest metric definitions and tribal knowledge from Slack, dbt, and query history, then validate and publish them as Guides. The knowledge worth putting in a [guide](/key-tasks/guides/) already exists somewhere in your organization: the Slack thread where someone explained why a number looked wrong, the unexplained `WHERE` clause in a dbt model, the query your analysts keep rerunning. None of it is written down anywhere an agent can read it. The prompt below puts an agent to work digging that knowledge out, in five phases: inventory, harvest, curate, organize, write. The agent drafts, asks for feedback, and stops at every phase boundary to wait for you. Expect the first pass to produce a few dozen guides: enough to change answers, and few enough that a single human can still read all of them. ## Before you start You need: - A MotherDuck account with the [Model Context Protocol (MCP) server](/key-tasks/ai-and-motherduck/mcp-setup/) connected to an AI client like Claude, Cursor, or Claude Code - Whatever sources you can get your hands on: exported Slack history from the channel where people ask data questions (or Slack's MCP server), a checkout of your dbt project, access to [`QUERY_HISTORY`](/sql-reference/motherduck-sql-reference/md_information_schema/query_history), a clone of the analytics repo - The names of the 2–5 people whose SQL and explanations your team trusts - Permission to [publish org-wide guides](/key-tasks/guides/#manage-guide-visibility), if you want the results shared beyond your own account. Without it, everything lands as a private guide, which is still a fine place to start. You don't need all the sources. One well-mined Slack channel will yield far more than dumping a list of all possible context documents. ## What belongs in a guide Only two kinds of knowledge change an answer: 1. **Facts no model could know.** Tribal knowledge: customer ID 8 is the test account and gets excluded from revenue, the March 2023 data is backfilled and unreliable, `is_full_day` has to be filtered when summing. 2. **Your specific modifications of a general term.** A model knows what ARR, MQL, and churn mean in general. It can't know how *you* calculate them — the nuance your business layers on top of the textbook definition. If a candidate fact is neither of those, and a capable model with schema access would get it right anyway, it doesn't belong in a guide. There are two more rules the prompt enforces on everything the agent harvests: - **Methods, not results.** When a source says "our top customers are X, Y, and Z", the guide-worthy artifact is the query and the definitions behind it, never the answer. Results go stale; methods generalize. - **Draft, don't decide.** The call is yours. Left to its own judgment, your agent will merge two definitions that look similar and quietly lose the distinction that made them useful. ## The prompt Paste this into an agent session connected to your MotherDuck MCP server. Have your sources ready to paste or attach when it asks in phase 1. ```text You're helping me bootstrap Guides for my MotherDuck organization — markdown documents that agents read to answer our data questions correctly. We work in five phases: inventory, harvest, curate, organize, write. Don't skip ahead. At the end of each phase, show me your output and wait for my confirmation before continuing. ## What belongs in a guide Only two kinds of knowledge are worth writing down: 1. Facts no model could know. Tribal knowledge: "customer ID 8 is our test account, exclude it from revenue", "the March 2023 data is backfilled and unreliable", "always filter is_full_day when summing". 2. Our specific overlay on general terms. You know what ARR, MQL, or churn mean in general; you can't know how we calculate them. If a candidate is neither of these — if a capable model with schema access would get it right anyway — it does not go in a guide. Guides are for what changes an answer. Two rules for everything you harvest: - Record methods, not results. If a source shows "our top customers are X, Y, Z", the guide-worthy artifact is the query and definitions that produce that answer, never the answer itself. Results go stale; methods generalize. - Draft, don't decide. You propose; I and the people who own these metrics validate. Don't change a claim's meaning, merge two claims, or resolve a conflict without my approval. When two candidates look similar, flag the pair and let me resolve it. Rewriting a result into the method behind it is expected — that's phase 3 work, not a judgment call. - Don't copy sensitive material into a guide. Sources like chat exports and query history carry credentials, personal data, and customer names. Write the rule, not the excerpt it came from, and never paste a token or connection string into guide content. Flag anything you're unsure about instead of saving it. ## Working files Keep state on disk rather than in this conversation. Before phase 2, create guide-bootstrap/candidates.md and treat it as the source of truth: one row per candidate with an id, the type, the claim, its locator, the author, your confidence, and a status column I fill in during phase 3. Append to it as you harvest. If you get compacted or lose context, re-read the file and carry on from there. If you can spawn subagents, use one per source in phase 2. Give each the harvest rules and one source, have it append its candidates to the file, and have it return only a count and a one-line summary. Raw source material — chat exports, query history results, dbt model files — should never enter this session. You need the candidates, not the sources they came from. ## Phase 1 — Inventory Use the MotherDuck tools to list databases, schemas, and tables. Then survey the guides that already exist: call get_query_guide for the topic tree, open each topic that looks related to our data with list_guides(topic), and read anything that might overlap with get_guide(uuid). get_query_guide only shows topic counts and the root-level guides, so without opening the topics you'll write duplicates of guides we already have. Then ask me, one topic at a time: 1. Which schemas and tables matter most — what do people actually ask questions about? 2. Who are the 2-5 people whose SQL and explanations we trust? For the query history step, I'll also need to give you their exact USER_NAME values, which are MotherDuck identifiers rather than display names. 3. Which of these sources can I give you (paste, export, or file): - History from the channel where people ask data questions and get corrected — usually the richest source - Our dbt project: models, schema.yml descriptions, manifest - Query history: MD_INFORMATION_SCHEMA.QUERY_HISTORY, or another warehouse's history view - Git history of the analytics or dbt repo - Docs for upstream systems: our CRM's data model, the billing system 4. What are the 10-20 questions people most often ask of this data? If I'm not sure, we'll derive them from the sources. Produce a short inventory: domains of questions, trusted people, available sources. Stop and confirm with me. ## Phase 2 — Harvest Work through the available sources in this order, highest signal first. For each one, produce candidate facts: one-line claims carrying the type (1 = fact no model could know, 2 = our overlay on a known term), your confidence, and a locator precise enough that I can go check it — a thread link or channel and timestamp, a model name and line, a query ID, a commit SHA. "From Slack" is not a locator, and I can't validate a claim I can't trace. Name the author where the source has one; that's who I'll route the claim to in phase 3. 1. Question-and-answer threads. Look for question then explanation exchanges, especially "this number looks wrong" followed by someone explaining why. Those explanations are gold. Extract the reason, not the incident. 2. dbt project. Descriptions and tests are a skeleton. Pay special attention to filters and CASE logic whose rationale is not explained — don't guess the reason, list each as an open question for phase 3 ("why does stg_revenue exclude plan_type = 'internal'?"). 3. Query history. Filter to the trusted people from phase 1, and prefer queries that recur over months. Recent one-offs from power users are usually development work on new pipelines, not settled knowledge. Extract recurring join patterns, standard filters, and canonical-table choices. 4. Git history. Commit messages and diffs that changed metric logic explain why definitions are what they are. Capture the why. 5. Upstream system docs. Extract only what helps navigate the synced schema: object relationships, ID semantics, sync caveats. Deduplicate exact duplicates only. Where sources conflict — dbt says one thing, a Slack thread says another — keep both and flag the conflict. Conflicts are the most valuable things you will find. Present the full candidate list grouped by domain. Stop and confirm with me. ## Phase 3 — Curate Walk me through the candidates in batches of 10-15, grouped by domain. For each one I'll say keep, fix, or drop, and for disputed definitions I'll name the person who owns the call. Apply these tests on your side and tell me when a candidate fails one: - Would a capable model with schema access get this right without the guide? Then drop it. - Is it a result rather than a method? Rewrite it as the method or drop it. - Does it state a rule without the reason? Flag it. A rule with no why gets misapplied. - Is it likely to be stale in three months? Either generalize it or mark it with an expiry note. Anything that survives gets a validation tag: who confirmed it, or "needs review by ". Don't put unvalidated candidates in org-wide guides — park them in a "needs review" list instead. Stop and confirm the final curated set with me. ## Phase 4 — Organize Propose a topic structure before writing anything. Guides are grouped by topic: a lowercase label, optionally nested with slashes, like revenue-billing or core/metrics. A guide with no topic sits at the root. Organize by domains of questions — a topic should answer "what set of questions is this for?" Use this four-role layout as the default and adapt it to our domains: - One orientation guide at the root, with no topic. This is the map: the definitions an agent needs before anything else, per-schema notes, a join graph with cardinality and required filters, and pointers to the guides below rather than copies of them. Root-level guides appear in every get_query_guide overview, so keep this the only one, or close to it. - definitions — one guide per atomic concept (definitions/customer, definitions/arr). Atomic guides are retrievable and maintainable; one guide holding every definition is neither. - — one topic per question domain (revenue-billing, product-usage, sales-funnel), holding the guides that say how each metric is computed. - tables/ — routing guides for load-bearing tables: the canonical table for a job, required filters, and which tables are deprecated or low-trust. "Use X, not Y" is the highest-value thing these can say. If we already have a tree the team navigates by — a dbt project's schemas, for instance — mirror it rather than inventing a new one. Keep the tree shallow: at most two levels below the root. Topic values separate levels with a slash and can't start or end with one, so the topic is tables/orders, not /tables/orders/. Don't use the reserved dives and flights topics; those hold Dive and Flight styling conventions. Every guide gets a one-line description that compresses the rule itself, not a restatement of the title. Show me the proposed topic tree with each curated fact assigned to a guide. Stop and confirm with me. ## Phase 5 — Write Draft each guide and show me its full text before saving. Wait for my go-ahead on each one and save it with its own create_guide call — don't batch a set of guides behind a single approval. When saving: - Set references to the 1-5 tables or views each guide is authoritative about, so agents find the guide when they explore those tables. - Write the description as a compressed statement of the rule with the pitfall inline — "roll revenue up to company, never org" — rather than a restatement of the title. The description is often all an agent reads before deciding whether to open the guide, so a good one changes behavior on its own. - Leave access at the default 'user' while a guide is unvalidated, or if I'm not an org admin. Promote to 'organization' only for guides a named owner has confirmed. - Use change_comment to record where the content came from and who validated it. - Record each guide you save in guide-bootstrap/created.md: uuid, title, topic, and access. That list is what we work from when we promote guides later. Finish by writing me a smoke test rather than running it. You've read every source in this session, so you'd answer from memory and never touch a guide. Give me 5 of the common questions from phase 1, and for each one the guide that should get opened and the answer we agreed on in phase 3. I'll run it in a fresh session that has nothing but the MotherDuck MCP connection and bring you back the tool calls it made. When a question comes back answered without the guide that should have applied, the content isn't at fault — the routing is. Look at the guide's description, title, topic, and references together, since those are all an agent sees before deciding to open it, and tell me which one failed to match the question. ## Afterwards — maintenance Put this in the orientation guide so future sessions pick it up: when an agent answers wrongly and a human corrects it, that correction is a guide edit. Find the one guide that should have prevented the mistake and make a targeted edit with edit_guide_content, rather than writing a new overlapping guide. Re-run the smoke test periodically. Resist automated cleanup — merging "similar" guides loses the specifics that made them work, so consolidation stays a human editorial decision. ``` ## Working through the phases A wrong definition costs the most when it's cheapest to catch, and every phase boundary is one of those moments. Here's what to look at when the agent stops. ### Inventory The agent asks what matters and who to trust. Answer these narrowly. The trusted names are what the agent filters query history down to, so naming three people gets you the queries your team relies on, and naming everyone gets you every one-off anybody has ever run. A service account from a BI tool counts as a trusted name — the queries behind a dashboard your team already relies on are settled knowledge, so don't leave those out. ### Harvest The prompt orders sources by signal density, with the best sources first: | Source | What to pull out | Why it ranks here | |--------|------------------|-------------------| | Q&A channel history | The explanation behind "this number looks wrong" | The work of explaining the gap between the schema and reality has already been done | | dbt project | Descriptions, tests, and unexplained filters and `CASE` logic | The filters encode real rules; their missing rationale becomes your phase 3 question list | | [`QUERY_HISTORY`](/sql-reference/motherduck-sql-reference/md_information_schema/query_history) | Recurring join patterns, standard filters, canonical-table choices | Filter on `USER_NAME` to your trusted people, then prefer queries that repeat often over time | | Git history of the analytics repo | Commit messages and diffs that changed metric logic | Explains why a definition is what it is, which the current code can't | | Upstream system docs | Object relationships, ID semantics, sync caveats | Helps the agent navigate a synced schema it didn't design | :::note Reading `QUERY_HISTORY` needs the View query history permission on a Business plan. Without it, ask your trusted people for their saved or most-rerun queries instead — you lose the recurrence signal but keep the patterns. ::: Watch for two things in the output. **Conflicts** between sources are worth inspecting closely: they mean two parts of your organization disagree about a definition, and whichever version reaches the agent first wins. **Results dressed as facts** ("Q3 revenue was $4.2M") stay out of the corpus — they're a specific number from a specific day, not a pattern that generalizes. ### Curate This is the phase that decides whether the guides are worth anything. When a candidate turns out to be disputed, or just unclear, route it to whoever owns the metric rather than settling it yourself — the agent will happily accept your guess (and so will every future agent session). A candidate without a validated owner shouldn't go into an org-wide guide. Keep it private (`access = 'user'`) until someone signs off. ### Organize Guides are grouped by [topic](/key-tasks/guides/#organize-guides-with-topics), and the topic names are how an agent decides what to read. The prompt proposes the [four-role layout](/key-tasks/guides/#using-topics): one orientation guide at the root, `definitions/` for atomic concepts, a topic per question domain, and `tables//` for routing. Review the assignment of topics carefully — every curated fact should land in exactly one guide, and the root should end up holding a single orientation guide instead of multiple loosely related ones. Finding the right granularity takes a few tries. Too coarse, and you get one giant `metrics` guide that agents load in full for every question, polluting the context with facts the question never needed. Too fine, and a fact lands in a topic nobody thinks to open. Link related guides to each other so the agent can follow the trail from whichever one it opens first. ### Write Attach [references](/key-tasks/guides/#attach-references-to-a-guide) as you save. A guide that references a table comes back automatically when an agent calls `list_tables` on that database, so the agent finds it while exploring rather than having to know it exists. Ask a few questions and check that they route correctly. A question answered without the guide that should have applied is a routing failure, not a content one. What the agent sees before it decides to open a guide is the title, description, topic, and references, so one of those didn't match the question. Fix it and run the test again. Your agent's logs are worth reading here too — they show you exactly where it looked and what it skipped. ### Rolling it out to other users Keep the whole first pass private. The prompt leaves new guides at `access = 'user'`, and that's where they should stay until the corpus has been tested end to end: run the smoke test in a fresh session, fix what routed wrong, run it again. A wrong org-wide guide fails quietly — every agent session in the organization gets a confident wrong answer and nobody sees an error — where a wrong private guide only ever misleads you. Promote a guide with [`set_guide_access`](/sql-reference/mcp/guides/set-guide-access) once it clears two separate gates: a named owner has confirmed the content, and the smoke test routes to it. Each gate catches a failure the other misses. An owner can tell you a definition is correct but not that its description matches how people phrase the question; the smoke test proves routing but says nothing about whether the number is right. Expect this to span sessions — you build the corpus in one, test it in a clean one, and come back to fix what missed. ## Keep guides current A guide corpus decays the moment corrections stop flowing back into it, and those corrections are already happening every time someone tells an agent it got the number wrong. The design problem is catching them. Three ideas: - **Treat every correction as a guide edit.** When someone corrects an agent's answer, find the single guide that should have prevented it and make a targeted edit with [`edit_guide_content`](/sql-reference/mcp/guides/edit-guide-content). Writing a second, overlapping guide is how you end up with two conflicting definitions. - **Consider building evals** so you can run tests after a schema migration or a metric change. - **Don't automate consolidation.** In our experience, merging guides that look similar loses the specifics that made them worth writing. A human does much better at this one. ## Related resources - [Guides](/key-tasks/guides/) — how topics, references, and visibility work - [MCP tool reference — Guides](/sql-reference/mcp/guides/get-query-guide) — the tools the agent calls in phase 5 - [Using the MotherDuck MCP Server](/key-tasks/ai-and-motherduck/mcp-workflows) — general workflow tips for MCP sessions --- ## Docs feedback MotherDuck accepts optional user-submitted feedback about this page at `GET https://motherduck.com/docs/api/feedback/agent`. For agents and automated tools, feedback submission should be user-confirmed before sending. URL-encode query parameter values and send a GET request: ```text GET https://motherduck.com/docs/api/feedback/agent?page_path=%2Fkey-tasks%2Fguides%2Fbootstrap-guides-with-an-ai-agent%2F&page_title=Bootstrap%20Guides%20from%20the%20context%20you%20already%20have&text= ``` Optionally append `&source=` such as `claude.ai` or `chatgpt`. `page_path` and `text` are required; `page_title` and `source` are optional. Responses: `200 {"feedback_id": ""}`, `400` for malformed query parameters, and `429` when rate-limited.