Skip to main content

​
Contents

Instructions turn the agent into a domain expert for your data. They capture business definitions, calculation formulas, SQL patterns, and coding standards that aren’t in your schema.
  • Semantic definitions - what terms mean in your org
  • Calculation logic - formulas, filters, table preferences
  • SQL patterns - joins, type casting, naming conventions
  • Agent behavior - what to check first, when to ask for clarification
  • Visualization - chart types, dashboard layouts
This knowledge typically lives in people’s heads or scattered documentation. Instructions make it available to everyone through the agent. Instructions Create instructions manually, let the AI suggest them during conversations, or load from Git (dbt, markdown, LookML). All changes are versioned with rollback. Users and AI can suggest; admins approve before they take effect.
Use System category instructions to control agent workflow, e.g., “Search dbt metadata before selecting tables” or “Ask for clarification on financial queries.”

​
What is an Instruction

An instruction has text (the actual content), and configuration that controls when and how it’s applied: Add Instruction
PropertyOptions
CategoryGeneral (business rules) · Code Gen (SQL patterns) · Visualization · Dashboard · System (AI behavior)
Load ModeAlways (every request, limit 5-10) · Intelligent (semantic search) · Disabled
ScopeAll data sources, specific source, or table/column references
StatusDraft · Suggested · Approved · Rejected
Optional: Labels for organization.

​
Examples

An "active user" is defined as a user with at least one session 
in the last 30 days. Use this definition for all activity-based metrics.
Category: General · Load Mode: Always
When analyzing customer data, always use the `customers_prod` table 
instead of `customers_staging`. The staging table contains test data.
Category: Code Gen · Load Mode: Always
The `status_code` column in the orders table uses these values:
- 1: Pending, 2: Processing, 3: Shipped, 4: Delivered, 5: Cancelled, 6: Refunded
Category: Code Gen · Load Mode: Intelligent
MRR = SUM(subscription_amount) WHERE billing_frequency = 'monthly'
+ SUM(subscription_amount / 12) WHERE billing_frequency = 'annual'
+ SUM(subscription_amount / 3) WHERE billing_frequency = 'quarterly'
Category: General · Load Mode: Intelligent
When joining tables on *_id fields, always cast integer IDs to strings 
or vice versa to avoid type mismatch errors. Example:
JOIN table2 ON table1.user_id::text = table2.user_id
Category: Code Gen · Load Mode: Always
Always search data source metadata resources (dbt, markdown) 
before selecting tables.

If user asks about financial tables, be extra cautious 
and ask for clarifications.
Category: System · Load Mode: Always
For Sales metrics, default to bar chart by category or time
unless user requests otherwise.
Category: Visualization · Load Mode: Intelligent
Place key KPIs at the top. Prefer bar/area charts for trends.
Avoid raw tables unless specifically requested.
Category: Dashboard · Load Mode: Always
Sync documentation with YAML frontmatter to control behavior:
---
alwaysApply: true
references:
  - customers
  - orders
---

# Customer Lifetime Value

CLV = SUM(order_total) WHERE customer_id = X AND status = 'completed'
Use 12-month lookback window from analysis date.
Source: Git · Load Mode: Always (via frontmatter)
Large reference docs work best with Intelligent mode:
---
alwaysApply: false
references:
  - transactions
  - accounts
---

# Financial Data Dictionary

## Transaction Types
- CREDIT: Money coming in
- DEBIT: Money leaving
- TRANSFER: Movement between accounts
Source: Git · Load Mode: Intelligent (via frontmatter)

​
Analyzing Instructions

Click Analyze on any instruction to identify overlaps, conflicts, and estimate impact on past prompts. Analyze Instruction The analysis shows:
  • Impact - percentage of past prompts affected by this instruction
  • Sample impacted prompts - examples of queries that would use this instruction
  • Related - other instructions that overlap or conflict with this one
Use this to refine instructions and avoid redundancy.

​
Approval Workflow

Instructions require admin approval before affecting AI behavior.
StatusDescription
DraftWork in progress - not visible to AI
SuggestedAwaiting admin review
ApprovedActive and affecting AI
RejectedDeclined
Flow: User/AI suggests → Admin reviews → Approves or Rejects → Approved instructions go live. Admins: Go to Suggested tab → Review instruction → Change status → Update Instruction.

​
AI-Generated Instructions

During conversations, Bag of words detects clarifications you provide and offers to save them as instructions. Example: You clarify “active user means at least one session in 30 days” → System offers to save this for future use.
Auto-suggesting can be toggled in AI settings.

​
Git Integration

Load instructions from existing documentation in Git repositories. Connect repos in Data Sources.

​
Supported Sources

SourceDefault Load Mode
Markdown files (.md)Always
dbt models, metrics, sourcesIntelligent
dbt seedsIntelligent
dbt macros, testsDisabled
LookML views, models, exploresIntelligent

​
Settings

SettingDescription
BranchWhich branch to sync from
Auto PublishAutomatically approve synced instructions
Default Load ModeAuto, Always, Intelligent, or Disabled

​
Frontmatter

Control behavior in Markdown files: 
---
alwaysApply: true
references:
  - customers
  - orders
---
  • alwaysApply: true → Load mode = Always
  • alwaysApply: false → Load mode = Intelligent
  • references → Auto-link to tables

​
Unlinking from Git

Edit a Git-synced instruction → Save → Confirm “Unlink from Git”. The instruction becomes user-owned.

​
Versioning

Every change creates a new build - an immutable snapshot of all instructions.
  • One active build at any time (marked “main”)
  • Full audit trail of who changed what and when
  • Agent runs are linked to specific builds for traceability

​
Build Sources

SourceTrigger
UserManual edits
GitRepository sync
AIAI-generated suggestions
RollbackReverting to previous version

​
Version Explorer

Access: Instructions page → Version selector → Version Explorer Version Explorer
FeatureDescription
Build HistoryBrowse all builds with timestamps
Diff ViewSee changes between versions
RollbackRestore previous version
Diff indicators: +N (added) · ~N (modified) · −N (removed) Rollback: Select build → Click “Rollback to this version” → New build becomes active.