fix: update gtm commands

.claude/commands/gtm-validator.md

@@ -6,6 +6,16 @@ description: GTM QA - tag firing verification, trigger testing, naming conventio
 
 Verify GTM implementations on live pages. Test triggers, validate dataLayer, check naming conventions.
 
+## Pre-Flight
+
+**BEFORE starting validation**, read the relevant gotcha files at:
+`~/Project/dintel-gtm-agent/docs/log/gotcha/` (see `README.md` for index)
+
+Priority reads per task:
+- **Trigger validation** → `gotcha/triggers.md` + `gotcha/regex.md`
+- **Post-API-change QA** → `gotcha/compilation.md`
+- **Variable inspection** → `gotcha/variables.md`
+
 ## Triggers
 - "validate tags", "QA GTM", "debug GTM"
 - "naming conventions", "GTM best practice"
@@ -35,6 +45,59 @@ GTM snippet placement, dataLayer init, consent mode, ES5 compliance, sGTM endpoi
 ### 7. Version Comparison
 Compare tag counts and changes between container versions
 
+## Gotchas (Hard-Won Lessons)
+
+### GTM Has Two Validation Layers — API CRUD vs Preview/Publish
+
+GTM API validates **schema only** during create/update calls (field names, types, required params). Regex patterns are stored as opaque strings and **never compiled** at edit time. Preview/Publish performs **full container compilation** — all regex is compiled by Google RE2, all variable references resolved, cross-resource dependencies checked. A resource can pass API validation but break Preview.
+
+**Rule**: After batch API changes, always attempt Preview before declaring success.
+
+### RE2 Does Not Support Lookaheads
+
+GTM's regex engine (RE2) is linear-time and deliberately omits:
+- Negative lookahead `(?!...)`
+- Positive lookahead `(?=...)`
+- Lookbehind `(?<=...)` / `(?<!...)`
+- Backreferences `\1`
+
+**Wrong** (breaks at Preview/Publish with "내부 오류"):
+```
+^(?!.*(jamie\.clinic|tel:)).*$
+```
+
+**Right** — use separate conditions with `negate` parameter:
+```json
+{
+  "type": "contains",
+  "parameter": [
+    {"type": "template", "key": "arg0", "value": "{{Click URL}}"},
+    {"type": "template", "key": "arg1", "value": "jamie.clinic"},
+    {"type": "boolean", "key": "negate", "value": "true"}
+  ]
+}
+```
+
+### The `negate` Parameter Is Inside the Condition Array
+
+GTM API negation is NOT a top-level field on the condition object — it's a `{"type": "boolean", "key": "negate", "value": "true"}` entry inside the condition's `parameter` array, alongside `arg0` and `arg1`. Setting `negate: true` at the condition top level is **silently ignored** by the API.
+
+### RegEx Table Variable Column Names
+
+The `remm` (RegEx Table) variable type uses `key` and `value` as column names in its map entries, NOT `pattern` and `outputValue`. Also requires `{"type": "boolean", "key": "setDefaultValue", "value": "true"}` to enable the default value.
+
+### Empty Template Fields Can Break Compilation
+
+When creating `linkClick` triggers via API, setting `waitForTags`, `checkValidation`, `waitForTagsTimeout` via the `parameter` array sometimes produces empty top-level template stubs (`{"type": "template"}` with no value). These empty stubs can cause compilation issues. Either set them correctly at the top level or omit them and let GTM use defaults.
+
+### Timer Triggers Cannot Use `customEventFilter`
+
+Timer triggers fire on `gtm.timer` — they are NOT custom events. Use `filter` (not `customEventFilter`) to add page-level conditions to timer triggers. `customEventFilter` is only valid on `customEvent` type triggers.
+
+### Colon `:` Is Not Allowed in Trigger Names
+
+GTM trigger names cannot contain `:`. Use `-` or other separators instead.
+
 ## Key Rules
 - Test on LIVE published version (not preview, unless debugging)
 - Test on both desktop and mobile viewports