opencode-skills-collection 2.0.0 → 2.0.3

package/bundled-skills/monte-carlo-monitor-creation/references/validation-monitor.md

@@ -0,0 +1,404 @@
+# Validation Monitor Reference
+
+Detailed reference for building `createValidationMonitorMac` tool calls.
+
+## When to Use
+
+Use a validation monitor when the user wants to:
+
+- Check that specific fields are never null
+- Validate that values are within an allowed set (e.g., status in 'active', 'pending', 'inactive')
+- Enforce referential integrity (field values exist in another table)
+- Apply row-level business rules (e.g., "amount must be positive")
+- Combine multiple conditions with AND/OR logic
+
+---
+
+## Getting the Logic Right: Conditions Match INVALID Data
+
+This is the single most confusing aspect of validation monitors and the number one source of mistakes. **Conditions describe what INVALID data looks like -- the data you want to be alerted about.** They do NOT describe what valid data looks like.
+
+Think of it this way: the monitor scans rows and fires an alert when it finds rows matching the condition. So the condition must match the BAD rows.
+
+| User wants | Condition should match | Common mistake |
+|------------|----------------------|----------------|
+| "id should never be null" | id IS NULL (alert when null found) | id IS NOT NULL (would alert on every valid row) |
+| "status must be in [active, pending]" | status NOT IN [active, pending] (alert on unexpected values) | status IN [active, pending] (would alert on valid rows) |
+| "amount must be positive" | amount IS NEGATIVE (alert on bad values) | amount > 0 (would alert on valid rows) |
+| "email must not be empty" | email IS NULL **OR** email = '' (alert on missing) | email IS NOT NULL (would alert on valid rows) |
+
+**Before building any condition, ask yourself: "If a row matches this condition, is the row INVALID?" If the answer is no, the logic is backwards.**
+
+---
+
+## Pre-Step: Verify Field Existence
+
+Before constructing the `alert_condition`, verify that every field name you plan to reference exists in the table's column list. This is the number two source of validation monitor failures -- referencing columns that do not exist or are misspelled.
+
+1. You should already have the column list from `getTable` with `include_fields: true` (done in Step 2 of the main skill).
+2. For every field name in your planned conditions, confirm it appears in the column list exactly as spelled (field names are case-sensitive on most warehouses).
+3. If a field does not exist, stop and ask the user to clarify the correct column name. Do not guess.
+
+---
+
+## Required Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `name` | string | Unique identifier for the monitor. Use a descriptive slug (e.g., `orders_not_null_check`). |
+| `description` | string | Human-readable description of what the monitor checks. |
+| `table` | string | Table MCON (preferred) or `database:schema.table` format. If not MCON, also pass `warehouse`. |
+| `alert_condition` | object | Condition tree defining when to alert (see Alert Condition Structure below). |
+
+## Optional Parameters
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `warehouse` | string | Warehouse name or UUID. Required if `table` is not an MCON. |
+| `domain_id` | string (uuid) | Domain UUID (use `getDomains` to list). |
+
+---
+
+## Alert Condition Structure
+
+The top level of `alert_condition` must always be a GROUP node. This GROUP contains one or more conditions combined with AND or OR logic.
+
+```json
+{
+  "type": "GROUP",
+  "operator": "AND",
+  "conditions": [...]
+}
+```
+
+### Condition Types
+
+There are four condition types: UNARY, BINARY, SQL, and GROUP.
+
+#### UNARY (single-value checks)
+
+Used for predicates that operate on a single field with no comparison value.
+
+```json
+{
+  "type": "UNARY",
+  "predicate": {"name": "null", "negated": false},
+  "value": [{"type": "FIELD", "field": "column_name"}]
+}
+```
+
+- `predicate.name` -- the predicate to apply (see Predicates Reference below).
+- `predicate.negated` -- set to `true` to invert the predicate (e.g., `null` with `negated: true` means "is NOT null").
+- `value` -- an array with a single value descriptor (usually a FIELD reference).
+
+#### BINARY (comparison checks)
+
+Used for predicates that compare a field against a value.
+
+```json
+{
+  "type": "BINARY",
+  "predicate": {"name": "greater_than", "negated": false},
+  "left": [{"type": "FIELD", "field": "column_name"}],
+  "right": [{"type": "LITERAL", "literal": "0"}]
+}
+```
+
+- `left` -- the left-hand side of the comparison (typically a FIELD reference).
+- `right` -- the right-hand side (typically a LITERAL value, SQL expression, or FIELD reference).
+- Both `left` and `right` are arrays of value descriptors.
+
+#### SQL (custom SQL expression)
+
+Used for complex conditions that are difficult to express with UNARY/BINARY nodes. The SQL expression should evaluate to true for INVALID rows.
+
+```json
+{
+  "type": "SQL",
+  "sql": "amount > 0 AND amount < 1000000"
+}
+```
+
+#### GROUP (nested conditions)
+
+Used to combine multiple conditions with AND or OR logic. Groups can be nested.
+
+```json
+{
+  "type": "GROUP",
+  "operator": "OR",
+  "conditions": [
+    {"type": "UNARY", "...": "..."},
+    {"type": "BINARY", "...": "..."}
+  ]
+}
+```
+
+---
+
+## Value Types
+
+Value descriptors appear in the `value`, `left`, and `right` arrays of UNARY and BINARY conditions.
+
+| Type | Field | Description | Example |
+|------|-------|-------------|---------|
+| `FIELD` | `"field": "column_name"` | References a column in the table. | `{"type": "FIELD", "field": "user_id"}` |
+| `LITERAL` | `"literal": "value"` | A static value (always a string, even for numbers). | `{"type": "LITERAL", "literal": "100"}` |
+| `SQL` | `"sql": "SELECT ..."` | A SQL expression or subquery. | `{"type": "SQL", "sql": "SELECT MAX(id) FROM ref_table"}` |
+
+---
+
+## Predicates Reference
+
+Before building conditions, call `getValidationPredicates` to get the full list of supported predicates for the connected warehouse. The list below covers common predicates but may not be exhaustive.
+
+### Unary Predicates
+
+These predicates take no comparison value -- they check a property of the field itself.
+
+| Predicate | Description | Example use |
+|-----------|-------------|-------------|
+| `null` | Field value is null. | Alert on null ids. |
+| `is_negative` | Field value is negative. | Alert on negative amounts. |
+| `is_between_0_and_1` | Field value is between 0 and 1 (inclusive). | Alert on rates that should be percentages (0-100). |
+| `is_future_date` | Field value is a date/timestamp in the future. | Alert on future-dated records. |
+| `is_uuid` | Field value matches UUID format. | Alert on non-UUID values in a UUID field (use with `negated: true`). |
+
+### Binary Predicates
+
+These predicates compare a field against a value.
+
+| Predicate | Right-hand side | Description | Example use |
+|-----------|----------------|-------------|-------------|
+| `equal` | Single LITERAL | Field equals the given value. | Alert when `status` equals `'deleted'`. |
+| `greater_than` | Single LITERAL | Field is greater than the given value. | Alert when `discount_pct` exceeds 100. |
+| `less_than` | Single LITERAL | Field is less than the given value. | Alert when `quantity` is below 0. |
+| `in_set` | Multiple LITERALs | Field value is in the given set. | Alert when `status` is in an invalid set (see example below). |
+| `contains` | Single LITERAL | Field value contains the given substring. | Alert when `email` contains `'test@'`. |
+| `starts_with` | Single LITERAL | Field value starts with the given prefix. | Alert when `phone` starts with `'000'`. |
+| `between` | Two LITERALs | Field value is between the two given values (inclusive). | Alert when `score` is between 0 and 10 (if that range is invalid). |
+
+### Using `negated` to Invert Predicates
+
+Any predicate can be inverted by setting `"negated": true` in the predicate object. This is essential for "must be in set" validations:
+
+- **"status must be in [active, pending]"** becomes `in_set` with values `["active", "pending"]` and `negated: true` -- meaning "alert when status is NOT in [active, pending]".
+- **"id must not be null"** becomes `null` with `negated: false` -- meaning "alert when id IS null" (no inversion needed since the condition already matches invalid data).
+
+---
+
+## Examples
+
+### Alert when id is null
+
+Verify that `id` exists in the table schema from `getTable` before proceeding.
+
+```json
+{
+  "name": "orders_id_not_null",
+  "description": "Alert when order id is null",
+  "table": "MCON++a1b2c3d4-e5f6-7890-abcd-ef1234567890++1++1++analytics:core.orders",
+  "alert_condition": {
+    "type": "GROUP",
+    "operator": "AND",
+    "conditions": [
+      {
+        "type": "UNARY",
+        "predicate": {"name": "null", "negated": false},
+        "value": [{"type": "FIELD", "field": "id"}]
+      }
+    ]
+  }
+}
+```
+
+The condition matches rows where `id` IS NULL -- these are the invalid rows we want to be alerted about.
+
+### Alert when status is not in allowed set
+
+Verify that `status` exists in the table schema from `getTable` before proceeding.
+
+```json
+{
+  "name": "orders_status_allowed_values",
+  "description": "Alert when order status is outside the allowed set",
+  "table": "MCON++a1b2c3d4-e5f6-7890-abcd-ef1234567890++1++1++analytics:core.orders",
+  "alert_condition": {
+    "type": "GROUP",
+    "operator": "AND",
+    "conditions": [
+      {
+        "type": "BINARY",
+        "predicate": {"name": "in_set", "negated": true},
+        "left": [{"type": "FIELD", "field": "status"}],
+        "right": [
+          {"type": "LITERAL", "literal": "active"},
+          {"type": "LITERAL", "literal": "pending"},
+          {"type": "LITERAL", "literal": "inactive"}
+        ]
+      }
+    ]
+  }
+}
+```
+
+Note `negated: true` -- the predicate is `in_set`, but we want to alert when the value is NOT in the set. This catches any unexpected status values.
+
+### Alert when amount is negative
+
+Verify that `amount` exists in the table schema from `getTable` before proceeding.
+
+```json
+{
+  "name": "orders_positive_amount",
+  "description": "Alert when order amount is negative",
+  "table": "MCON++a1b2c3d4-e5f6-7890-abcd-ef1234567890++1++1++analytics:core.orders",
+  "alert_condition": {
+    "type": "GROUP",
+    "operator": "AND",
+    "conditions": [
+      {
+        "type": "UNARY",
+        "predicate": {"name": "is_negative", "negated": false},
+        "value": [{"type": "FIELD", "field": "amount"}]
+      }
+    ]
+  }
+}
+```
+
+The condition matches rows where `amount` is negative -- these are the invalid rows.
+
+### Combined conditions: null OR negative
+
+Verify that both `amount` and `quantity` exist in the table schema from `getTable` before proceeding.
+
+```json
+{
+  "name": "orders_amount_quality",
+  "description": "Alert when amount is null or quantity is negative",
+  "table": "MCON++a1b2c3d4-e5f6-7890-abcd-ef1234567890++1++1++analytics:core.orders",
+  "alert_condition": {
+    "type": "GROUP",
+    "operator": "OR",
+    "conditions": [
+      {
+        "type": "UNARY",
+        "predicate": {"name": "null", "negated": false},
+        "value": [{"type": "FIELD", "field": "amount"}]
+      },
+      {
+        "type": "UNARY",
+        "predicate": {"name": "is_negative", "negated": false},
+        "value": [{"type": "FIELD", "field": "quantity"}]
+      }
+    ]
+  }
+}
+```
+
+The OR operator means an alert fires if either condition matches -- the row has a null amount OR a negative quantity.
+
+### Between check with nested AND/OR
+
+Verify that `score` and `status` exist in the table schema from `getTable` before proceeding.
+
+```json
+{
+  "name": "records_score_validation",
+  "description": "Alert when score is outside 0-100 range for active records",
+  "table": "MCON++a1b2c3d4-e5f6-7890-abcd-ef1234567890++1++1++warehouse:metrics.records",
+  "alert_condition": {
+    "type": "GROUP",
+    "operator": "AND",
+    "conditions": [
+      {
+        "type": "BINARY",
+        "predicate": {"name": "equal", "negated": false},
+        "left": [{"type": "FIELD", "field": "status"}],
+        "right": [{"type": "LITERAL", "literal": "active"}]
+      },
+      {
+        "type": "BINARY",
+        "predicate": {"name": "between", "negated": true},
+        "left": [{"type": "FIELD", "field": "score"}],
+        "right": [
+          {"type": "LITERAL", "literal": "0"},
+          {"type": "LITERAL", "literal": "100"}
+        ]
+      }
+    ]
+  }
+}
+```
+
+This uses `between` with `negated: true` to alert when score is outside the 0-100 range, but only for active records (the AND operator requires both conditions to match).
+
+### Referential integrity with SQL subquery
+
+Verify that `customer_id` exists in the table schema from `getTable` before proceeding.
+
+```json
+{
+  "name": "orders_valid_customer",
+  "description": "Alert when customer_id does not exist in customers table",
+  "table": "MCON++a1b2c3d4-e5f6-7890-abcd-ef1234567890++1++1++analytics:core.orders",
+  "alert_condition": {
+    "type": "GROUP",
+    "operator": "AND",
+    "conditions": [
+      {
+        "type": "SQL",
+        "sql": "customer_id IS NOT NULL AND customer_id NOT IN (SELECT id FROM analytics.core.customers)"
+      }
+    ]
+  }
+}
+```
+
+The SQL condition type is useful for referential integrity checks that require subqueries. The `customer_id IS NOT NULL` guard avoids alerting on null values (which should be caught by a separate null check if needed).
+
+### Contains and starts_with checks
+
+Verify that `email` and `phone` exist in the table schema from `getTable` before proceeding.
+
+```json
+{
+  "name": "contacts_format_validation",
+  "description": "Alert when email contains test data or phone has invalid prefix",
+  "table": "MCON++a1b2c3d4-e5f6-7890-abcd-ef1234567890++1++1++warehouse:crm.contacts",
+  "alert_condition": {
+    "type": "GROUP",
+    "operator": "OR",
+    "conditions": [
+      {
+        "type": "BINARY",
+        "predicate": {"name": "contains", "negated": false},
+        "left": [{"type": "FIELD", "field": "email"}],
+        "right": [{"type": "LITERAL", "literal": "@test.example.com"}]
+      },
+      {
+        "type": "BINARY",
+        "predicate": {"name": "starts_with", "negated": false},
+        "left": [{"type": "FIELD", "field": "phone"}],
+        "right": [{"type": "LITERAL", "literal": "000"}]
+      }
+    ]
+  }
+}
+```
+
+---
+
+## Fallback: Custom SQL Monitor
+
+If `createValidationMonitorMac` fails -- for example because a referenced column does not exist yet in the live table, or the warehouse does not support a particular predicate -- fall back to `createCustomSqlMonitorMac` with an explicit SQL query instead.
+
+A custom SQL monitor lets you express any validation logic as a SQL query that returns rows or a count. This is always available as a backup when the structured validation condition tree cannot express what you need or encounters an API error.
+
+When falling back:
+
+1. Translate the intended validation logic into a SQL query.
+2. The SQL should select rows that violate the rule (matching the same "conditions match INVALID data" principle).
+3. Use `createCustomSqlMonitorMac` with the translated query.
+4. Inform the user that you used a custom SQL monitor as a fallback and explain why.

package/bundled-skills/monte-carlo-prevent/SKILL.md

@@ -0,0 +1,252 @@
+---
+name: monte-carlo-prevent
+description: "Surfaces Monte Carlo data observability context (table health, alerts, lineage, blast radius) before SQL/dbt edits."
+category: data
+risk: safe
+source: community
+source_repo: monte-carlo-data/mc-agent-toolkit
+source_type: community
+date_added: "2026-04-08"
+author: monte-carlo-data
+tags: [data-observability, dbt, schema, monte-carlo, lineage]
+tools: [claude, cursor, codex]
+---
+
+# Monte Carlo Prevent Skill
+
+This skill brings Monte Carlo's data observability context directly into your editor. When you're modifying a dbt model or SQL pipeline, use it to surface table health, lineage, active alerts, and to generate monitors-as-code without leaving Claude Code.
+
+Reference files live next to this skill file. **Use the Read tool** (not MCP resources) to access them:
+
+- Full workflow step-by-step instructions: `references/workflows.md` (relative to this file)
+- MCP parameter details: `references/parameters.md` (relative to this file)
+- Troubleshooting: `references/TROUBLESHOOTING.md` (relative to this file)
+
+## When to activate this skill
+
+**Do not wait to be asked.** Run the appropriate workflow automatically whenever the user:
+
+- References or opens a `.sql` file or dbt model (files in `models/`) → run Workflow 1
+- Mentions a table name, dataset, or dbt model name in passing → run Workflow 1
+
+- Describes a planned change to a model (new column, join update, filter change, refactor) → **STOP — run Workflow 4 before writing any code**
+-
+- Adds a new column, metric, or output expression to an existing
+  model → run Workflow 4 first, then ALWAYS offer Workflow 2
+  regardless of risk tier — do not skip the monitor offer
+- Asks about data quality, freshness, row counts, or anomalies → run Workflow 1
+- Wants to triage or respond to a data quality alert → run Workflow 3
+
+Present the results as context the engineer needs before proceeding — not as a response to a question.
+
+## When NOT to activate this skill
+
+Do not invoke Monte Carlo tools for:
+
+- Seed files (files in seeds/ directory)
+- Analysis files (files in analyses/ directory)
+- One-off or ad-hoc SQL scripts not part of a dbt project
+- Configuration files (dbt_project.yml, profiles.yml, packages.yml)
+- Test files unless the user is specifically asking about data quality
+
+If uncertain whether a file is a dbt model, check for {{ ref() }} or {{ source() }}
+Jinja references — if absent, do not activate.
+
+### Macros and snapshots — gate edits, skip auto-context
+
+Macro files (`macros/`) and snapshot files (`snapshots/`) are **not** models, so
+do not auto-fetch Monte Carlo context (Workflow 1) when they are opened. However,
+macros are inlined into every model that calls them at compile time — a one-line
+macro change can silently alter dozens of models. Snapshots control historical
+tracking and are similarly sensitive.
+
+**The pre-edit hook gates these files.** If the hook fires for a macro or snapshot,
+identify which models are affected and run the change impact assessment (Workflow 4)
+for those models before proceeding with the edit.
+
+---
+
+## REQUIRED: Change impact assessment before any SQL edit
+
+**Before editing or writing any SQL for a dbt model or pipeline, you MUST run Workflow 4.**
+
+This applies whenever the user expresses intent to modify a model — including phrases like:
+
+- "I want to add a column…"
+- "Let me add / I'm adding…"
+- "I'd like to change / update / rename…"
+- "Can you add / modify / refactor…"
+- "Let's add…" / "Add a `<column>` column"
+- Any other description of a planned schema or logic change
+- "Exclude / filter out / remove [records/customers/rows]…"
+- "Adjust / increase / decrease [threshold/parameter/value]…"
+- "Fix / bugfix / patch [issue/bug]…"
+- "Revert / restore / undo [change/previous behavior]…"
+- "Disable / enable [feature/logic/flag]…"
+- "Clean up / remove [references/columns/code]…"
+- "Implement [backend/feature] for…"
+- "Create [models/dbt models] for…" (when modifying existing referenced tables)
+- "Increase / decrease / change [max_tokens/threshold/date constant/numeric parameter]…"
+- Any change to a hardcoded value, constant, or configuration parameter within SQL
+- "Drop / remove / delete [column/field/table]"
+- "Rename [column/field] to [new name]"
+- "Add [column]" (short imperative form, e.g. "add a created_at column")
+- Any single-verb imperative command targeting a column, table, or model
+  (e.g. "drop X", "rename Y", "add Z", "remove W")
+
+Parameter changes (threshold values, date constants, numeric limits) appear
+safe but silently change model output. Treat them the same as logic changes
+for impact assessment purposes.
+
+**Do not write or edit any SQL until the change impact assessment (Workflow 4) has been presented to the user.** The assessment must come first — not after the edit, not in parallel.
+
+---
+
+## Pre-edit gate — check before modifying any file
+
+**Before calling Edit, Write, or MultiEdit on any `.sql` or dbt model
+file, you MUST check:**
+
+1. Has the synthesis step been run for THIS SPECIFIC CHANGE in the
+   current prompt?
+2. **If YES** → proceed with the edit
+3. **If NO** → stop immediately, run Workflow 4, present the full
+   report with synthesis connected to this specific change.
+   **If risk is High or Medium:** ask "Do you want me to proceed
+   with the edit?" and wait for explicit confirmation.
+   **If risk is Low:** use judgment — proceed if straightforward
+   and no concerns found, otherwise ask before editing.
+
+**Important: "Workflow 4 already ran this session" is NOT sufficient
+to proceed.** Each distinct change prompt requires its own synthesis
+step connecting the MC findings to that specific change.
+
+The synthesis must reference the specific columns, filters, or logic
+being changed in the current prompt — not just general table health.
+
+Example:
+
+- ✅ "Given 34 downstream models depend on is_paying_workspace,
+  adding 'MC Internal' to the exclusion list will exclude these
+  workspaces from all downstream health scores and exports.
+  Confirm?"
+- ❌ "Workflow 4 already ran. Making the edit now."
+
+The only exception: if the user explicitly acknowledges the risk
+and confirms they want to skip (e.g. "I know the risks, just make
+the change") — proceed but note the skipped assessment.
+
+## Available MCP tools
+
+All tools are available via the `monte-carlo` MCP server.
+
+| Tool                         | Purpose                                                              |
+| ---------------------------- | -------------------------------------------------------------------- |
+| `testConnection`             | Verify auth and connectivity                                         |
+| `search`                     | Find tables/assets by name                                           |
+| `getTable`                   | Schema, stats, metadata for a table                                  |
+| `getAssetLineage`            | Upstream/downstream dependencies (call with mcons array + direction) |
+| `getAlerts`                  | Active incidents and alerts                                          |
+| `getMonitors`                | Monitor configs — filter by table using mcons array                  |
+| `getQueriesForTable`         | Recent query history                                                 |
+| `getQueryData`               | Full SQL for a specific query                                        |
+| `createValidationMonitorMac` | Generate validation monitors-as-code YAML                            |
+| `createMetricMonitorMac`     | Generate metric monitors-as-code YAML                                |
+| `createComparisonMonitorMac` | Generate comparison monitors-as-code YAML                            |
+| `createCustomSqlMonitorMac`  | Generate custom SQL monitors-as-code YAML                            |
+| `getValidationPredicates`    | List available validation rule types                                 |
+| `updateAlert`                | Update alert status/severity                                         |
+| `setAlertOwner`              | Assign alert ownership                                               |
+| `createOrUpdateAlertComment` | Add comments to alerts                                               |
+| `getAudiences`               | List notification audiences                                          |
+| `getDomains`                 | List MC domains                                                      |
+| `getUser`                    | Current user info                                                    |
+| `getCurrentTime`             | ISO timestamp for API calls                                          |
+
+## Core workflows
+
+Each workflow has detailed step-by-step instructions in `references/workflows.md` (Read tool).
+
+### 1. Table health check
+
+**When:** User opens a dbt model or mentions a table.
+**What:** Surfaces health, lineage, alerts, and risk signals. Auto-escalates to Workflow 4 if change intent is detected and risk signals are present.
+
+### 2. Add a monitor
+
+**When:** New column, filter, or business rule is added to a model.
+**What:** Suggests and generates monitors-as-code YAML using the appropriate `create*MonitorMac` tool. Saves to `monitors/<table_name>.yml`.
+
+### 3. Alert triage
+
+**When:** User is investigating an active data quality incident.
+**What:** Lists open alerts, checks table state, traces lineage for root cause, reviews recent queries.
+
+### 4. Change impact assessment — REQUIRED before modifying a model
+
+**When:** Any intent to modify a dbt model's logic, columns, joins, or filters.
+**What:** Surfaces blast radius, downstream dependencies, active incidents, monitor coverage, and query exposure. Produces a risk-tiered report with synthesis connecting findings to specific code recommendations. See `references/workflows.md` for the full assessment sequence, report format, and synthesis rules.
+
+### 5. Change validation queries
+
+**When:** Explicit engineer request only (e.g. "validate this change", "ready to commit").
+**What:** Generates 3-5 targeted SQL queries to verify the change behaved as intended. Uses Workflow 4 context — requires both impact assessment and file edit in session.
+
+---
+
+## Post-synthesis confirmation rules
+
+Always end the synthesis with one clear, specific recommendation in plain English:
+"Given the above, I recommend: [specific action]"
+
+**If the risk is High or Medium:** STOP and wait for confirmation before editing
+any file. You must ask the engineer and receive an explicit "yes", "go ahead",
+"proceed", or similar confirmation before making code changes.
+Say: "Do you want me to proceed with the edit?"
+Do NOT say: "Proceeding with the edit." — that skips the engineer's decision.
+
+**If the risk is Low:** Use your judgment based on the synthesis findings. If
+the change is straightforward and the synthesis found no concerns, you may
+proceed. If anything is surprising or worth flagging, ask before editing.
+
+---
+
+## Session markers
+
+These markers coordinate between the skill and the plugin's hooks. Output each
+on its own line when the condition is met.
+
+### Impact check complete
+
+After the engineer confirms (High/Medium) or after presenting the synthesis (Low),
+output one marker per assessed table. **IMPORTANT: use only the table/model name, not the full MCON:**
+
+<!-- MC_IMPACT_CHECK_COMPLETE: <table_name> -->
+
+(Use the model filename without .sql extension — NOT "acme.analytics.orders" or "prod.public.client_hub")
+
+How many markers to emit depends on how the assessment was triggered:
+
+**Hook-triggered** (the pre-edit hook blocked an edit and instructed you to run
+the assessment): Be strict — only emit markers for tables whose lineage **and**
+monitor coverage were fetched directly via Monte Carlo tools in this session. If
+the engineer describes changes to multiple tables but only one was formally
+assessed, emit only one marker. The pre-edit hook will gate the other tables and
+prompt for their own Workflow 4 runs.
+
+**Voluntarily invoked** (the engineer proactively asked for an impact assessment):
+Be looser — emit markers for all tables the assessment meaningfully covered, even
+if some were assessed via lineage context rather than direct MC tool calls. The
+engineer is already safety-conscious; don't force redundant assessments for tables
+they clearly considered.
+
+### Monitor coverage gap
+
+When Workflow 4 finds zero custom monitors on a table's affected columns, output:
+
+<!-- MC_MONITOR_GAP: <table_name> -->
+
+Use only the table/model name (NOT the full MCON). This allows the plugin's hooks
+to remind the engineer about monitor coverage at commit time. Only output this
+marker when the gap is specifically about the columns or logic being changed —
+not for general table-level monitor absence.

package/bundled-skills/monte-carlo-prevent/references/TROUBLESHOOTING.md

@@ -0,0 +1,23 @@
+## Troubleshooting
+
+### MCP connection fails:
+```bash
+# Verify the server is reachable
+curl -s -o /dev/null -w "%{http_code}" https://integrations.getmontecarlo.com/mcp/
+```
+
+**If using the plugin (OAuth):** Run `/mcp` in Claude Code, select the `monte-carlo` server, and re-authenticate. If the browser flow doesn't complete, copy the callback URL from your browser's address bar into the URL prompt that appears in Claude Code.
+
+**Legacy (header-based auth, for MCP clients without HTTP transport):** Check that `x-mcd-id` and `x-mcd-token` are set correctly in your MCP config. The key format is `<KEY_ID>:<KEY_SECRET>` — these are split across two separate headers.
+
+
+### Monitor creation errors:
+
+**`montecarlo monitors apply` fails with "Unknown field":**
+Monitor definition files must have `montecarlo:` as the root key — do not copy the `validation:` or `custom_sql:` output from the MCP tools directly. Reformat using the `montecarlo: > custom_sql:` structure shown in Workflow 2.
+
+**`montecarlo monitors apply` fails with "Not a Monte Carlo project":**
+Ensure `montecarlo.yml` (the project config) exists in the working directory. This file must contain only `version`, `namespace`, and `default_resource` — not monitor definitions.
+
+**`createValidationMonitorMac` fails with a Snowflake error:**
+This tool validates the condition SQL against the live table. If the column doesn't exist yet (e.g. you're writing the monitor before deploying the model change), fall back to `createCustomSqlMonitorMac` with an explicit SQL query instead.