// Gather business context from Notion before dbt builds. Searches pages, extracts definitions/decisions/constraints, writes structured context for the build agent and notion-verify subagent.
| name | notion-context |
| description | Gather business context from Notion before dbt builds. Searches pages, extracts definitions/decisions/constraints, writes structured context for the build agent and notion-verify subagent. |
Gather business context from Notion using SignalPilot's governed Notion tools.
Call list_database_connections — this also lists Notion integrations. Pick
the integration to use:
Verify the integration works with a test search:
notion_search
integration_name: "<name>"
query: "test"
Save the working integration_name for all subsequent calls.
Extract keywords from the task instruction — table names, metric names, business terms not defined in YML.
notion_search
integration_name: "<name>"
query: "<keywords>"
No results? Try in order:
If still nothing -> write No relevant Notion context found. to
notion_context.md (include the # Integration: header) and return.
For each matching page (up to 5):
notion_fetch_page
integration_name: "<name>"
page_id: "<id>"
If the page lists child pages but has no content — it's a container page. Fetch the child pages that look relevant to the task (by title). Meeting notes and transcripts are typically one level down from the container.
If the page has content — extract from it directly.
Scan page content for three categories:
| Category | Signal phrases | Example |
|---|---|---|
| DEFINITION | "X means Y", "X is defined as", "X = Y" | "active customer = 1+ orders in 90 days" |
| DECISION | "we decided", "agreed to", "going with" | "grain is (shop_id, date)" |
| CONSTRAINT | "exclude", "only include", "must filter" | "exclude test orders where source = 'internal'" |
For each item record:
Check for contradictions between items. If two sources disagree, flag both
with CONFLICT:. Do NOT silently pick one.
Write notion_context.md in the working directory:
# NOTION CONTEXT
# Integration: <integration_name>
# Task: <task summary>
# Sources: <N> pages searched, <M> items extracted
## DEFINITIONS
- [DEF-1] "<term>" = <definition>
Source: <page_title> — https://notion.so/<page_id>
## DECISIONS
- [DEC-1] <decision statement>
Source: <page_title> — https://notion.so/<page_id>
## CONSTRAINTS
- [CON-1] <constraint>
Source: <page_title> — https://notion.so/<page_id>
## CONFLICTS
- <item A> (from <page_A>) vs <item B> (from <page_B>)
## SOURCES CONSULTED
- <page_title> — https://notion.so/<page_id> — <N> items extracted
Each item gets a stable ID (DEF-1, DEC-1, CON-1, etc.) so the verify agent can reference them in the traceability matrix. This file is read by the notion-verify subagent after the build.
Return DEFINITIONS, DECISIONS, and CONSTRAINTS to the calling agent. The agent MUST:
-- NOTION: [DEF-1] <brief reason> comments in SQL for every decision
influenced by Notion context. Use the item ID from notion_context.md.Load at Step 1 before exploring the project. Covers Notion context gathering, output shape inference, incremental model handling, and what to trust in YML.
Load when dbt run or dbt parse fails. Covers YML duplicate patches, ref errors, passthrough model warnings, current_date fixes, DuckDB error messages, and zero-row diagnosis.
Load at Step 4 when writing SQL models. Covers column naming, type preservation, JOIN defaults, lookup joins, sibling models, materialization, packages, and filtering rules.
Load when hitting DuckDB syntax errors or writing DuckDB-specific SQL. Covers gotchas that differ from PostgreSQL/MySQL.
BigQuery-specific SQL patterns: UNNEST for array expansion, STRUCT, ARRAY_AGG, DATE_DIFF/DATE_ADD, backtick-quoted table references, EXCEPT/REPLACE in SELECT, approximate aggregation, partitioned and wildcard tables.
Use this skill before writing any SQL query. Covers: output shape inference (cardinality clues from the question), efficient schema exploration, iterative CTE-based query building, structured verification loop (row count, NULL audit, fan-out check, sample inspection), error recovery protocol, saving output to result.sql and result.csv, turn budget management, and common benchmark traps.
