fix: update gtm commands

.claude/commands/gtm-audit.md

@@ -1,46 +1,68 @@
 ---
-description: Gtm Audit command
+description: GTM page audit - scan fired tags, gap analysis, tag design from DOM, and report generation
 ---
 
 # GTM Audit
 
-Lightweight Google Tag Manager audit tool.
+Comprehensive Google Tag Manager audit using Playwright to scan live pages for container health, tag firing, dataLayer events, form tracking, and e-commerce checkout flows.
 
 ## Triggers
-- "audit GTM", "check dataLayer", "GTM 검사"
+- "audit GTM", "check dataLayer", "GTM 검사", "scan GTM tags", "audit tags on page", "check tag firing"
 
 ## Capabilities
 
-1. **Container Analysis** - Tags, triggers, variables inventory
+1. **Container Analysis** — Verify GTM container loads, detect container ID, inventory tags/triggers/variables
-2. **DataLayer Validation** - Check event structure
+2. **Tag Destination Detection** — Identify fired tags by network requests (GA4, Google Ads, Meta Pixel, LinkedIn, TikTok, Kakao, Naver, etc.)
-3. **Form Tracking** - Verify form submission events
+3. **DataLayer Validation** — Check event structure, required fields, GA4 naming conventions
-4. **E-commerce Check** - Validate purchase/cart events
+4. **Form Tracking** — Verify form submission events and field capture
+5. **E-commerce Checkout Flow** — Validate purchase/cart/checkout events and required e-commerce parameters
+6. **Journey-based Audit** — Target specific user journeys: `pageview`, `scroll`, `click`, `form`, `checkout`, `datalayer`, or `full`
 
-## Scripts
+## Script
 
 ```bash
-# Audit GTM container
+AUDIT_SCRIPT="/Users/ourdigital/Project/our-claude-skills/custom-skills/60-gtm-audit/code/scripts/gtm_audit.py"
-python /Users/ourdigital/Project/our-claude-skills/custom-skills/20-gtm-audit/code/scripts/gtm_audit.py \
-  --url https://example.com
 
-# With detailed dataLayer check
+# Basic page audit
-python /Users/ourdigital/Project/our-claude-skills/custom-skills/20-gtm-audit/code/scripts/gtm_audit.py \
+python "$AUDIT_SCRIPT" --url "https://example.com"
-  --url https://example.com --check-datalayer --output report.json
+
+# Audit with expected container ID and specific journey
+python "$AUDIT_SCRIPT" --url "https://example.com" --container GTM-XXXXXX --journey full
+
+# E-commerce checkout flow audit with JSON report
+python "$AUDIT_SCRIPT" --url "https://example.com/checkout" --journey checkout --output report.json
 ```
 
+### Script Options
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--url` | Target URL to audit (required) | — |
+| `--container` | Expected GTM container ID (e.g., GTM-XXXXXX) | auto-detect |
+| `--journey` | Audit scope: `pageview`, `scroll`, `click`, `form`, `checkout`, `datalayer`, `full` | `pageview` |
+| `--output` | Output file path for JSON report | `gtm_audit_report.json` |
+| `--timeout` | Page load timeout in ms | `30000` |
+| `--headless` | Run in headless mode | `True` |
+
 ## Audit Checklist
 
 ### Container Health
-- [ ] GTM container loads correctly
+- [ ] GTM container loads without JavaScript errors
-- [ ] No JavaScript errors from GTM
+- [ ] Container ID matches expected value
-- [ ] Container ID matches expected
+- [ ] No duplicate container installations
+
+### Tag Firing & Destinations
+- [ ] GA4 measurement requests detected
+- [ ] Ad platform pixels fire correctly (Google Ads, Meta, etc.)
+- [ ] No orphaned or misfiring tags
 
 ### DataLayer Events
 - [ ] `page_view` fires on all pages
-- [ ] `purchase` event has required fields
+- [ ] `purchase` event has required e-commerce fields
-- [ ] Form submissions tracked
+- [ ] Form submissions tracked with correct parameters
+- [ ] Event names follow GA4 snake_case convention
 
 ### Common Issues
-- Missing ecommerce object
+- Missing or malformed ecommerce object
-- Incorrect event names (GA4 format)
+- Incorrect event names (not GA4 format)
 - Duplicate event firing
+- Tags firing before dataLayer is ready

.claude/commands/gtm-editor.md

@@ -6,6 +6,18 @@ description: GTM tag/trigger/variable creation via API with ES5 Custom HTML and
 
 Create, modify, and deploy GTM configurations via API. Generates ES5-compliant Custom HTML tags.
 
+## Pre-Flight
+
+**BEFORE any API write operation**, read the relevant gotcha files at:
+`~/Project/dintel-gtm-agent/docs/log/gotcha/` (see `README.md` for index)
+
+Priority reads per task:
+- **Creating triggers** → `gotcha/triggers.md` (scrollDepth/timer limits, negate placement, naming)
+- **Creating variables** → `gotcha/variables.md` (RegEx Table column names)
+- **Writing regex conditions** → `gotcha/regex.md` (RE2 limitations)
+- **Batch changes / publishing** → `gotcha/compilation.md` (workspace lifecycle)
+- **Using DTM CLI** → `gotcha/dtm-cli.md` (commands that don't actually work)
+
 ## Triggers
 - "create GTM tag", "generate dataLayer", "modify trigger"
 - "update variable", "write custom HTML", "manage GTM"

.claude/commands/gtm-manager.md

@@ -1,53 +0,0 @@
----
-description: Gtm Manager command
----
-
-# GTM Manager
-
-Full GTM management with dataLayer injection and tag generation.
-
-## Triggers
-- "GTM manager", "generate dataLayer tag", "dataLayer 태그 생성"
-
-## Capabilities
-
-1. **Full Audit** - Everything in gtm-audit plus more
-2. **DataLayer Injector** - Generate custom HTML tags
-3. **Event Mapping** - Map site actions to GA4 events
-4. **Notion Export** - Save audit results to Notion
-
-## Scripts
-
-```bash
-# Full GTM management
-python /Users/ourdigital/Project/our-claude-skills/custom-skills/21-gtm-manager/code/scripts/gtm_manager.py \
-  --url https://example.com --full-audit
-
-# Generate dataLayer tag
-python /Users/ourdigital/Project/our-claude-skills/custom-skills/21-gtm-manager/code/scripts/gtm_manager.py \
-  --generate-tag purchase --output purchase_tag.html
-
-# Export to Notion
-python /Users/ourdigital/Project/our-claude-skills/custom-skills/21-gtm-manager/code/scripts/gtm_manager.py \
-  --url https://example.com --notion-export --database DATABASE_ID
-```
-
-## DataLayer Tag Templates
-
-### Purchase Event
-```html
-<script>
-dataLayer.push({
-  'event': 'purchase',
-  'ecommerce': {
-    'transaction_id': '{{Order ID}}',
-    'value': {{Order Total}},
-    'currency': 'KRW',
-    'items': [...]
-  }
-});
-</script>
-```
-
-## Environment
-- `NOTION_TOKEN` - For Notion export (optional)

.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