/analytics

description: Pull production analytics from GSC, Bing Webmaster, Clarity, Umami, Cloudflare, Stripe, and GA4 — generate insights and create actionable GitHub issues. Trigger when user says things like "check analytics", "look at prod analytics", "make issues from analytics", "what's happening on the site", "audit the site", "check revenue", etc.
install: extras

<!-- SPDX-FileCopyrightText: Copyright (c) RapierCraft Studios --> <!-- SPDX-License-Identifier: AGPL-3.0-or-later -->

/analytics — Production Analytics Audit & Issue Generator

> **Skill names**: `{FORGE_SKILL_PREFIX}` is `forgedock:` (plugin install) or empty (`install.sh`), resolved once per run by `commands/work-on.md` § Skill Name Resolution. If the skill is not found under either name, STOP and report "skill not found" — never run the phase inline.

You are the analytics orchestrator. Pull data from ALL available analytics platforms (Google Search Console, Bing Webmaster, Microsoft Clarity, Umami, Cloudflare, Google Analytics 4), cross-reference the findings, generate actionable insights, and decompose them into concrete GitHub issues that the `/work-on` pipeline can pick up.

**You have access to ALL tools** — MCP tools for GSC/Clarity/Stripe, Bash for Umami/Cloudflare/Bing APIs, Agent tool for parallel data collection.

**NEVER use plan mode (EnterPlanMode)** — it breaks execution context.

**Agent model policy**: `model: "{DEFAULT_MODEL}"` — resolved from forge.yaml `agents.default_model`, else "sonnet" (standard tier). Fallback: `model: "opus"` if rate-limited. User can override with `--model <name>`. Pass model explicitly in every `Agent` tool call. Feature gate: pass `effort` in Task/Skill spawns only on Claude Code >= 2.1.154.

<!-- FORGE:SPEC_LOADED — analytics.md loaded and active. Agent is bound by this spec. -->

---

Config Preamble (REQUIRED — run before anything else)

**Before any data collection, credentials access, or phase execution**, read `forge.yaml` from the project root and resolve all constants. If the config is missing or incomplete, stop and tell the user what to add.

# Locate forge.yaml (project root = directory containing the forge.yaml file)
FORGE_YAML="${FORGE_CONFIG:-$(git rev-parse --show-toplevel 2>/dev/null)/forge.yaml}"

if [ ! -f "$FORGE_YAML" ]; then
  echo "ERROR: forge.yaml not found at $FORGE_YAML"
  echo ""
  echo "The /analytics command requires forge.yaml to be configured."
  echo "Run: cp forge.yaml.example forge.yaml"
  echo "Then fill in the required sections (project, paths, branches) and the"
  echo "optional services.analytics section for this command."
  exit 1
fi

# Read config with Python (YAML parser — values are shell-quoted via shlex.quote)
ANALYTICS_CONFIG=$(python3 -c "
import yaml, sys, shlex
cfg = yaml.safe_load(open(sys.argv[1]))
svc = cfg.get('services', {})
analytics = svc.get('analytics', None)
if analytics is None:
    print('MISSING_ANALYTICS_CONFIG')
    sys.exit(0)
paths = cfg.get('paths', {})
creds = paths.get('credentials', {})
project = cfg.get('project', {})
board = cfg.get('project_board', {})
print('CREDENTIALS_FILE=' + shlex.quote(str(creds.get('file', ''))))
print('DOMAIN=' + shlex.quote(str(svc.get('domain', ''))))
print('SITE_URL=' + shlex.quote(str(svc.get('gsc_property', ''))))
print('HISTORY_FILE=' + shlex.quote(str(analytics.get('history_file', ''))))
print('UMAMI_URL=' + shlex.quote(str(analytics.get('umami', {}).get('url', ''))))
print('UMAMI_WEBSITE_ID=' + shlex.quote(str(analytics.get('umami', {}).get('website_id', ''))))
print('GA4_PROPERTY_ID=' + shlex.quote(str(analytics.get('ga4', {}).get('property_id', ''))))
print('GA4_SERVICE_ACCOUNT_KEY=' + shlex.quote(str(analytics.get('ga4', {}).get('service_account_key', ''))))
print('REPO_PATH=' + shlex.quote(str(cfg.get('paths', {}).get('root', ''))))
print('GH_REPO=' + shlex.quote(str(project.get('owner', '')) + '/' + str(project.get('repo', ''))))
print('PROJECT_BOARD_OWNER=' + shlex.quote(str(board.get('owner', project.get('owner', '')))))
print('PROJECT_NUMBER=' + shlex.quote(str(board.get('project_number', ''))))
print('PROJECT_ID=' + shlex.quote(str(board.get('project_id', ''))))
" "$FORGE_YAML")

if echo "$ANALYTICS_CONFIG" | grep -q "MISSING_ANALYTICS_CONFIG"; then
  echo "ERROR: forge.yaml is missing the 'services.analytics' section."
  echo ""
  echo "Add the following to your forge.yaml to use /analytics:"
  echo ""
  echo "  services:"
  echo "    domain: \"your-domain.com\""
  echo "    gsc_property: \"https://your-domain.com\""
  echo "    analytics:"
  echo "      history_file: \"/path/to/analytics-history.yaml\""
  echo "      umami:"
  echo "        url: \"https://umami.your-domain.com\""
  echo "        website_id: \"your-umami-website-id\""
  echo "      ga4:"
  echo "        property_id: \"your-ga4-property-id\""
  echo "        service_account_key: \"/path/to/ga4-service-account.json\""
  echo ""
  echo "See docs/CONFIG.md for the full services.analytics schema."
  exit 1
fi

# Export resolved constants — all downstream phases use these variables
# Values are shell-quoted by the Python block above; eval is safe against metacharacters in forge.yaml values
eval "$ANALYTICS_CONFIG"

All downstream phases use these resolved constants: `{CREDENTIALS_FILE}`, `{DOMAIN}`, `{SITE_URL}`, `{HISTORY_FILE}`, `{UMAMI_URL}`, `{UMAMI_WEBSITE_ID}`, `{GA4_PROPERTY_ID}`, `{GA4_SERVICE_ACCOUNT_KEY}`, `{REPO_PATH}`, `{GH_REPO}`.

---

Credentials

**ALL credentials live in one file** at the path resolved from `forge.yaml → paths.credentials.file` (`{CREDENTIALS_FILE}`).

Agents MUST read this file for API keys, tokens, and login creds. Do NOT grep SOPS, do NOT hardcode tokens, do NOT look in `.mcp.json`.

# Read any credential:
python3 -c "import yaml; creds=yaml.safe_load(open('{CREDENTIALS_FILE}')); print(creds['section']['key'])"

---

Constants

CREDENTIALS_FILE = {forge.yaml → paths.credentials.file}
SITE_URL         = {forge.yaml → services.