our-claude-skills/custom-skills/20-gtm-audit/desktop/SKILL.md

---
name: gtm-audit
description: Automated Google Tag Manager audit and validation toolkit. Use when auditing GTM container installations, verifying tag firing, debugging dataLayer events, form tracking validation, e-commerce checkout flow testing, or generating tag implementation reports. Triggers on GTM audit, tag debugging, dataLayer inspection, form submission tracking, checkout funnel analysis, conversion tracking validation, GA4/Meta/LinkedIn pixel verification requests.
---

# GTM Audit Skill

Automated audit workflow for GTM containers using Playwright browser automation.

## Workflow Overview

```
1. Setup & Container Detection
2. DataLayer Validation & Monitoring
3. Form Analysis & Submission Tracking
4. E-commerce Checkout Flow Testing
5. Tag Firing Verification
6. Issue Analysis & Recommendations
7. Report Generation
```

## Quick Start

```bash
# Full audit with all features
python scripts/gtm_audit.py --url "https://example.com" --journey full

# Form tracking audit
python scripts/gtm_audit.py --url "https://example.com/contact" --journey form

# E-commerce checkout flow
python scripts/gtm_audit.py --url "https://example.com/cart" --journey checkout

# DataLayer deep inspection
python scripts/gtm_audit.py --url "https://example.com" --journey datalayer

# With expected container validation
python scripts/gtm_audit.py --url "https://example.com" --container "GTM-XXXXXX"
```

## Core Components

### 1. Container Detection

Verify GTM installation:
- Check for `gtm.js` or `gtag/js` script presence
- Validate container ID format (GTM-XXXXXX)
- Detect multiple containers (potential conflicts)
- Check script placement (head vs body)

### 2. DataLayer Inspection

Monitor `window.dataLayer` array:
- Capture all push events
- Validate event structure against GA4 specs
- Check e-commerce object schemas
- Identify malformed or missing parameters

### 3. Form Analysis & Tracking

Comprehensive form validation:
- **Discovery**: Find all forms on page
- **Field Analysis**: Input types, required fields, validation rules
- **Interaction Simulation**: Focus, input, blur, submit
- **Event Verification**: form_start, form_submit, generate_lead
- **Error Tracking**: Validation failures, abandonment points

### 4. E-commerce Checkout Flow

Multi-step checkout simulation:
- **Cart**: view_cart, remove_from_cart
- **Checkout Start**: begin_checkout
- **Shipping**: add_shipping_info
- **Payment**: add_payment_info
- **Purchase**: purchase event validation
- **Funnel Analysis**: Drop-off detection between steps

### 5. DataLayer Deep Inspection

Advanced dataLayer validation:
- **Structure Validation**: Schema compliance checking
- **Real-time Monitoring**: Capture all pushes during journey
- **Event Sequencing**: Verify correct order of events
- **Parameter Validation**: Type checking, required fields
- **Diff Analysis**: Before/after state comparison

### 4. Network Monitoring

Capture outbound requests to:
| Destination | Endpoint Pattern |
|-------------|------------------|
| GA4 | `google-analytics.com/g/collect` |
| Meta Pixel | `facebook.com/tr` |
| LinkedIn | `px.ads.linkedin.com` |
| Google Ads | `googleads.g.doubleclick.net` |
| TikTok | `analytics.tiktok.com` |

### 5. Tag Verification

For each expected tag:
- Confirm firing on correct trigger
- Validate required parameters present
- Check parameter values match dataLayer
- Identify timing/sequencing issues

## Reference Files

- **references/ga4_events.md** - GA4 recommended event specifications
- **references/ecommerce_schema.md** - E-commerce dataLayer structures
- **references/form_tracking.md** - Form event specs and validation patterns
- **references/checkout_flow.md** - Checkout funnel event sequence
- **references/datalayer_validation.md** - DataLayer schema validation rules
- **references/common_issues.md** - Frequent problems and fixes
- **references/report_template.md** - Audit report format

## Audit Checklist

### Container Health
- [ ] GTM script loads without errors
- [ ] Container ID matches expected
- [ ] No duplicate containers
- [ ] Script in correct position

### DataLayer Quality
- [ ] dataLayer initialized before GTM
- [ ] Event names follow conventions
- [ ] Required parameters present
- [ ] Data types correct (string/number)
- [ ] E-commerce objects cleared before new push
- [ ] No duplicate events firing

### Form Tracking
- [ ] form_start fires on first interaction
- [ ] form_submit fires on successful submission
- [ ] generate_lead fires with value (if applicable)
- [ ] Form field errors tracked
- [ ] Form abandonment detectable

### E-commerce Checkout
- [ ] view_cart fires with correct items
- [ ] begin_checkout has all required params
- [ ] add_shipping_info includes shipping_tier
- [ ] add_payment_info includes payment_type
- [ ] purchase has unique transaction_id
- [ ] purchase value matches cart total

### Tag Firing
- [ ] Pageview fires on all pages
- [ ] Events fire on correct triggers
- [ ] E-commerce events have required params
- [ ] Conversion tags fire once (not duplicate)

### Performance
- [ ] Tags don't block page render
- [ ] No excessive network requests
- [ ] Tag sequencing optimized

## Output Format

Audit generates JSON report:

```json
{
  "audit_metadata": {
    "url": "https://example.com",
    "timestamp": "2025-01-15T10:30:00Z",
    "container_id": "GTM-XXXXXX"
  },
  "container_status": {
    "installed": true,
    "valid": true,
    "position": "head",
    "issues": []
  },
  "tags_fired": [...],
  "tags_not_fired": [...],
  "issues": [...],
  "recommendations": [...]
}
```

## Common Fix Patterns

**Tag Not Firing**
1. Check trigger conditions in GTM
2. Verify dataLayer event name matches exactly
3. Confirm trigger timing (DOM Ready vs Window Loaded)
4. Test in GTM Preview mode

**Missing Parameters**
1. Verify dataLayer.push() includes all required fields
2. Check variable configuration in GTM
3. Confirm data types match expectations

**Duplicate Firing**
1. Check for multiple triggers on same action
2. Verify tag firing options (once per event/page)
3. Look for duplicate GTM containers

## Integration Notes

Works with:
- Playwright MCP tools for browser automation
- Desktop Commander for local script execution
- Can export reports to Notion via MCP