Instructions

Instructions transform the AI agent into a domain expert by encoding business definitions, SQL patterns, calculation formulas, and coding standards that aren't captured in database schemas alone.

What Instructions Can Contain

• Semantic definitions — Organizational terminology and business glossary
• Calculation logic — Formulas, filters, and metric definitions
• SQL patterns — Preferred joins, naming conventions, and query standards
• Agent behavior — Workflow preferences and response formatting
• Visualization guidance — Chart types, color schemes, and dashboard design rules

Configuration

Each instruction includes text content plus configuration controlling how it's applied:

Load Modes

• Always — Included in every agent run regardless of the question
• Intelligent — MetricChat selects relevant instructions based on the query context
• Disabled — Stored but not used in agent runs

Creating Instructions

Manual Creation

Create instructions directly through the UI. Define the text content, category, load mode, and scope.

AI Suggestions

During conversations, MetricChat can suggest new instructions when it identifies recurring patterns or business rules. These suggestions go through admin approval before activation.

Git Integration

Sync instructions from dbt, markdown, or LookML files in connected Git repositories. Markdown files support YAML frontmatter to control load behavior:

---
alwaysApply: true
references: ["orders", "revenue"]
status: approved
category: code_gen
---

Approval Workflow

Instructions follow a governance process:

1. Instructions are suggested (by AI or team members)
2. Admins review and approve or reject
3. Approved instructions become active in agent runs

Versioning & Audit

MetricChat maintains immutable build snapshots containing all instructions. This provides complete audit trails and the ability to roll back to previous versions.