diff --git a/packages/mosaic/framework/skills/README.md b/packages/mosaic/framework/skills/README.md index 2646e614..6c2d1788 100644 --- a/packages/mosaic/framework/skills/README.md +++ b/packages/mosaic/framework/skills/README.md @@ -6,13 +6,13 @@ Complete agent skill fleet for Mosaic Stack. 95 skills across 12 domains — cod All skills were reviewed on 2026-02-16. Findings: -| ID | Severity | Skill | Issue | Action | -|----|----------|-------|-------|--------| -| C-001 | **CRITICAL** | `vercel-deploy` | Uploads entire project to external endpoint via `curl` | **REMOVED** | -| C-002 | **ANNOTATED** | `docx`, `pptx`, `xlsx` | LD_PRELOAD shim compiles C at runtime to hook `socket()` | Security warnings added — legitimate sandbox workaround, should never activate on Docker Swarm | -| W-001 | WARNING | `using-superpowers` | Forces aggressive auto-loading via `` tags | Awareness only — review before enabling | -| W-002 | WARNING | `mcp-builder` | Can connect to arbitrary MCP servers | Awareness only — review server URLs | -| W-003 | WARNING | `create-agent` | Uses `Function()` constructor (eval equivalent) | Awareness only — review generated code | +| ID | Severity | Skill | Issue | Action | +| ----- | ------------- | ---------------------- | --------------------------------------------------------------- | ---------------------------------------------------------------------------------------------- | +| C-001 | **CRITICAL** | `vercel-deploy` | Uploads entire project to external endpoint via `curl` | **REMOVED** | +| C-002 | **ANNOTATED** | `docx`, `pptx`, `xlsx` | LD_PRELOAD shim compiles C at runtime to hook `socket()` | Security warnings added — legitimate sandbox workaround, should never activate on Docker Swarm | +| W-001 | WARNING | `using-superpowers` | Forces aggressive auto-loading via `` tags | Awareness only — review before enabling | +| W-002 | WARNING | `mcp-builder` | Can connect to arbitrary MCP servers | Awareness only — review server URLs | +| W-003 | WARNING | `create-agent` | Uses `Function()` constructor (eval equivalent) | Awareness only — review generated code | 88 of 93 audited skills passed all checks as clean instruction-only SKILL.md files. @@ -20,179 +20,179 @@ All skills were reviewed on 2026-02-16. Findings: ### Code Quality & Review (6) -| Skill | Purpose | Origin | -|-------|---------|--------| -| `lint` | Zero-tolerance linting — detect linter, fix ALL violations, never disable rules | Mosaic Stack | -| `pr-reviewer` | Structured PR code review workflow (Gitea/GitHub) | Adapted from SpillwaveSolutions | -| `code-review-excellence` | Code review methodology and checklists | awesome-skills | -| `verification-before-completion` | Evidence-based completion claims | obra/superpowers | -| `receiving-code-review` | How to receive and respond to code reviews | obra/superpowers | -| `requesting-code-review` | How to request effective code reviews | obra/superpowers | +| Skill | Purpose | Origin | +| -------------------------------- | ------------------------------------------------------------------------------- | ------------------------------- | +| `lint` | Zero-tolerance linting — detect linter, fix ALL violations, never disable rules | Mosaic Stack | +| `pr-reviewer` | Structured PR code review workflow (Gitea/GitHub) | Adapted from SpillwaveSolutions | +| `code-review-excellence` | Code review methodology and checklists | awesome-skills | +| `verification-before-completion` | Evidence-based completion claims | obra/superpowers | +| `receiving-code-review` | How to receive and respond to code reviews | obra/superpowers | +| `requesting-code-review` | How to request effective code reviews | obra/superpowers | ### Frontend & UI (8) -| Skill | Purpose | Origin | -|-------|---------|--------| -| `next-best-practices` | Next.js 15+ — RSC, async, self-hosting, data patterns | vercel-labs/next-skills | -| `vercel-react-best-practices` | React/Next.js performance (57 rules) | vercel-labs | -| `vercel-composition-patterns` | React composition and component patterns | vercel-labs | -| `vercel-react-native-skills` | React Native development patterns | vercel-labs | -| `shadcn-ui` | Component patterns — forms, dialogs, tables, charts | developer-kit | -| `tailwind-design-system` | Tailwind CSS v4 design system patterns | wshobson | -| `ui-animation` | Motion design — performance, accessibility, easing | mblode | -| `web-design-guidelines` | Web design principles and guidelines | vercel-labs | +| Skill | Purpose | Origin | +| ----------------------------- | ----------------------------------------------------- | ----------------------- | +| `next-best-practices` | Next.js 15+ — RSC, async, self-hosting, data patterns | vercel-labs/next-skills | +| `vercel-react-best-practices` | React/Next.js performance (57 rules) | vercel-labs | +| `vercel-composition-patterns` | React composition and component patterns | vercel-labs | +| `vercel-react-native-skills` | React Native development patterns | vercel-labs | +| `shadcn-ui` | Component patterns — forms, dialogs, tables, charts | developer-kit | +| `tailwind-design-system` | Tailwind CSS v4 design system patterns | wshobson | +| `ui-animation` | Motion design — performance, accessibility, easing | mblode | +| `web-design-guidelines` | Web design principles and guidelines | vercel-labs | ### Backend & API (4) -| Skill | Purpose | Origin | -|-------|---------|--------| -| `nestjs-best-practices` | NestJS — 40 rules, 10 categories, priority-ranked | kadajett | -| `fastapi` | FastAPI + Pydantic v2 + async SQLAlchemy 2.0 | jezweb | -| `architecture-patterns` | Clean Architecture, Hexagonal, DDD | wshobson | -| `python-performance-optimization` | Profiling, memory, parallelization | wshobson | +| Skill | Purpose | Origin | +| --------------------------------- | ------------------------------------------------- | -------- | +| `nestjs-best-practices` | NestJS — 40 rules, 10 categories, priority-ranked | kadajett | +| `fastapi` | FastAPI + Pydantic v2 + async SQLAlchemy 2.0 | jezweb | +| `architecture-patterns` | Clean Architecture, Hexagonal, DDD | wshobson | +| `python-performance-optimization` | Profiling, memory, parallelization | wshobson | ### Authentication (5) -| Skill | Purpose | Origin | -|-------|---------|--------| -| `better-auth-best-practices` | Better-Auth — Drizzle, sessions, plugins, security | better-auth | -| `create-auth-skill` | Creating custom Better-Auth skills | better-auth | -| `email-and-password-best-practices` | Email/password auth patterns | better-auth | -| `organization-best-practices` | Multi-org/team auth patterns | better-auth | -| `two-factor-authentication-best-practices` | 2FA implementation patterns | better-auth | +| Skill | Purpose | Origin | +| ------------------------------------------ | -------------------------------------------------- | ----------- | +| `better-auth-best-practices` | Better-Auth — Drizzle, sessions, plugins, security | better-auth | +| `create-auth-skill` | Creating custom Better-Auth skills | better-auth | +| `email-and-password-best-practices` | Email/password auth patterns | better-auth | +| `organization-best-practices` | Multi-org/team auth patterns | better-auth | +| `two-factor-authentication-best-practices` | 2FA implementation patterns | better-auth | ### AI & Agent Building (7) -| Skill | Purpose | Origin | -|-------|---------|--------| -| `ai-sdk` | Vercel AI SDK — streaming, multi-provider, agents | vercel/ai | -| `create-agent` | Modular agent with OpenRouter multi-model access | openrouterteam | -| `proactive-agent` | WAL Protocol, compaction recovery, self-improvement | halthelobster | -| `dispatching-parallel-agents` | Launching and managing parallel subagents | obra/superpowers | -| `subagent-driven-development` | Development workflow using subagents | obra/superpowers | -| `executing-plans` | Executing multi-step implementation plans | obra/superpowers | -| `using-superpowers` | Overview of the superpowers skill system | obra/superpowers | +| Skill | Purpose | Origin | +| ----------------------------- | --------------------------------------------------- | ---------------- | +| `ai-sdk` | Vercel AI SDK — streaming, multi-provider, agents | vercel/ai | +| `create-agent` | Modular agent with OpenRouter multi-model access | openrouterteam | +| `proactive-agent` | WAL Protocol, compaction recovery, self-improvement | halthelobster | +| `dispatching-parallel-agents` | Launching and managing parallel subagents | obra/superpowers | +| `subagent-driven-development` | Development workflow using subagents | obra/superpowers | +| `executing-plans` | Executing multi-step implementation plans | obra/superpowers | +| `using-superpowers` | Overview of the superpowers skill system | obra/superpowers | ### Development Workflow (6) -| Skill | Purpose | Origin | -|-------|---------|--------| -| `test-driven-development` | TDD Red-Green-Refactor discipline | obra/superpowers | -| `systematic-debugging` | Structured debugging methodology | obra/superpowers | -| `using-git-worktrees` | Git worktree patterns for parallel work | obra/superpowers | -| `finishing-a-development-branch` | Branch cleanup, squash, merge patterns | obra/superpowers | -| `writing-plans` | Writing effective implementation plans | obra/superpowers | -| `brainstorming` | Structured brainstorming methodology | obra/superpowers | +| Skill | Purpose | Origin | +| -------------------------------- | --------------------------------------- | ---------------- | +| `test-driven-development` | TDD Red-Green-Refactor discipline | obra/superpowers | +| `systematic-debugging` | Structured debugging methodology | obra/superpowers | +| `using-git-worktrees` | Git worktree patterns for parallel work | obra/superpowers | +| `finishing-a-development-branch` | Branch cleanup, squash, merge patterns | obra/superpowers | +| `writing-plans` | Writing effective implementation plans | obra/superpowers | +| `brainstorming` | Structured brainstorming methodology | obra/superpowers | ### Document Generation (6) -| Skill | Purpose | Origin | -|-------|---------|--------| -| `pdf` | PDF document generation | anthropics | -| `docx` | Word document generation | anthropics | -| `pptx` | PowerPoint presentation generation | anthropics | -| `xlsx` | Excel spreadsheet generation | anthropics | -| `doc-coauthoring` | Collaborative document writing | anthropics | -| `internal-comms` | Internal communications drafting | anthropics | +| Skill | Purpose | Origin | +| ----------------- | ---------------------------------- | ---------- | +| `pdf` | PDF document generation | anthropics | +| `docx` | Word document generation | anthropics | +| `pptx` | PowerPoint presentation generation | anthropics | +| `xlsx` | Excel spreadsheet generation | anthropics | +| `doc-coauthoring` | Collaborative document writing | anthropics | +| `internal-comms` | Internal communications drafting | anthropics | ### Design & Creative (7) -| Skill | Purpose | Origin | -|-------|---------|--------| -| `brand-guidelines` | Brand identity enforcement | anthropics | -| `frontend-design` | Frontend design patterns and principles | anthropics | -| `canvas-design` | Canvas/visual design patterns | anthropics | -| `algorithmic-art` | Generative/algorithmic art creation | anthropics | -| `theme-factory` | Theme generation and customization | anthropics | -| `slack-gif-creator` | Animated GIF creation for Slack | anthropics | -| `web-artifacts-builder` | Self-contained HTML artifact building | anthropics | +| Skill | Purpose | Origin | +| ----------------------- | --------------------------------------- | ---------- | +| `brand-guidelines` | Brand identity enforcement | anthropics | +| `frontend-design` | Frontend design patterns and principles | anthropics | +| `canvas-design` | Canvas/visual design patterns | anthropics | +| `algorithmic-art` | Generative/algorithmic art creation | anthropics | +| `theme-factory` | Theme generation and customization | anthropics | +| `slack-gif-creator` | Animated GIF creation for Slack | anthropics | +| `web-artifacts-builder` | Self-contained HTML artifact building | anthropics | ### Marketing & Business (25) -| Skill | Purpose | Origin | -|-------|---------|--------| -| `marketing-ideas` | 139 ideas across 14 categories | coreyhaines31 | -| `pricing-strategy` | SaaS pricing — value metrics, tiers, research | coreyhaines31 | -| `programmatic-seo` | SEO at scale — templates, playbooks | coreyhaines31 | -| `competitor-alternatives` | Competitor comparison pages | coreyhaines31 | -| `referral-program` | Referral & affiliate programs | coreyhaines31 | -| `seo-audit` | Comprehensive SEO audit methodology | coreyhaines31 | -| `copywriting` | Marketing copywriting patterns | coreyhaines31 | -| `copy-editing` | Copy editing and proofreading | coreyhaines31 | -| `content-strategy` | Content strategy and planning | coreyhaines31 | -| `social-content` | Social media content creation | coreyhaines31 | -| `email-sequence` | Email sequence design and automation | coreyhaines31 | -| `launch-strategy` | Product launch planning | coreyhaines31 | -| `marketing-psychology` | Psychology-driven marketing | coreyhaines31 | -| `product-marketing-context` | Product marketing positioning | coreyhaines31 | -| `paid-ads` | Paid advertising campaigns | coreyhaines31 | -| `schema-markup` | Schema.org structured data | coreyhaines31 | -| `analytics-tracking` | Analytics setup and tracking | coreyhaines31 | -| `ab-test-setup` | A/B testing methodology | coreyhaines31 | -| `page-cro` | Landing page conversion optimization | coreyhaines31 | -| `form-cro` | Form conversion optimization | coreyhaines31 | -| `signup-flow-cro` | Signup flow conversion optimization | coreyhaines31 | -| `onboarding-cro` | User onboarding optimization | coreyhaines31 | -| `popup-cro` | Popup/modal conversion optimization | coreyhaines31 | -| `paywall-upgrade-cro` | Paywall/upgrade conversion optimization | coreyhaines31 | -| `free-tool-strategy` | Free tool as marketing strategy | coreyhaines31 | +| Skill | Purpose | Origin | +| --------------------------- | --------------------------------------------- | ------------- | +| `marketing-ideas` | 139 ideas across 14 categories | coreyhaines31 | +| `pricing-strategy` | SaaS pricing — value metrics, tiers, research | coreyhaines31 | +| `programmatic-seo` | SEO at scale — templates, playbooks | coreyhaines31 | +| `competitor-alternatives` | Competitor comparison pages | coreyhaines31 | +| `referral-program` | Referral & affiliate programs | coreyhaines31 | +| `seo-audit` | Comprehensive SEO audit methodology | coreyhaines31 | +| `copywriting` | Marketing copywriting patterns | coreyhaines31 | +| `copy-editing` | Copy editing and proofreading | coreyhaines31 | +| `content-strategy` | Content strategy and planning | coreyhaines31 | +| `social-content` | Social media content creation | coreyhaines31 | +| `email-sequence` | Email sequence design and automation | coreyhaines31 | +| `launch-strategy` | Product launch planning | coreyhaines31 | +| `marketing-psychology` | Psychology-driven marketing | coreyhaines31 | +| `product-marketing-context` | Product marketing positioning | coreyhaines31 | +| `paid-ads` | Paid advertising campaigns | coreyhaines31 | +| `schema-markup` | Schema.org structured data | coreyhaines31 | +| `analytics-tracking` | Analytics setup and tracking | coreyhaines31 | +| `ab-test-setup` | A/B testing methodology | coreyhaines31 | +| `page-cro` | Landing page conversion optimization | coreyhaines31 | +| `form-cro` | Form conversion optimization | coreyhaines31 | +| `signup-flow-cro` | Signup flow conversion optimization | coreyhaines31 | +| `onboarding-cro` | User onboarding optimization | coreyhaines31 | +| `popup-cro` | Popup/modal conversion optimization | coreyhaines31 | +| `paywall-upgrade-cro` | Paywall/upgrade conversion optimization | coreyhaines31 | +| `free-tool-strategy` | Free tool as marketing strategy | coreyhaines31 | ### Vue/Vite Ecosystem (16) -| Skill | Purpose | Origin | -|-------|---------|--------| -| `vue` | Vue.js development patterns | antfu | -| `vue-best-practices` | Vue.js best practices and conventions | antfu | -| `vue-router-best-practices` | Vue Router patterns and guards | antfu | -| `vue-testing-best-practices` | Vue component testing patterns | antfu | -| `vueuse-functions` | VueUse composable function patterns | antfu | -| `nuxt` | Nuxt.js framework patterns | antfu | -| `vite` | Vite build tool configuration and plugins | antfu | -| `vitest` | Vitest testing framework patterns | antfu | -| `vitepress` | VitePress documentation site patterns | antfu | -| `slidev` | Slidev presentation framework | antfu | -| `pnpm` | pnpm package manager patterns | antfu | -| `turborepo` | Turborepo monorepo patterns | antfu | -| `unocss` | UnoCSS atomic CSS engine | antfu | -| `tsdown` | tsdown TypeScript bundler | antfu | -| `pinia` | Pinia state management | antfu | -| `antfu` | Anthony Fu's coding conventions | antfu | +| Skill | Purpose | Origin | +| ---------------------------- | ----------------------------------------- | ------ | +| `vue` | Vue.js development patterns | antfu | +| `vue-best-practices` | Vue.js best practices and conventions | antfu | +| `vue-router-best-practices` | Vue Router patterns and guards | antfu | +| `vue-testing-best-practices` | Vue component testing patterns | antfu | +| `vueuse-functions` | VueUse composable function patterns | antfu | +| `nuxt` | Nuxt.js framework patterns | antfu | +| `vite` | Vite build tool configuration and plugins | antfu | +| `vitest` | Vitest testing framework patterns | antfu | +| `vitepress` | VitePress documentation site patterns | antfu | +| `slidev` | Slidev presentation framework | antfu | +| `pnpm` | pnpm package manager patterns | antfu | +| `turborepo` | Turborepo monorepo patterns | antfu | +| `unocss` | UnoCSS atomic CSS engine | antfu | +| `tsdown` | tsdown TypeScript bundler | antfu | +| `pinia` | Pinia state management | antfu | +| `antfu` | Anthony Fu's coding conventions | antfu | ### Orchestration (1) -| Skill | Purpose | Origin | -|-------|---------|--------| +| Skill | Purpose | Origin | +| ----------- | ------------------------------------------------------------------------------------------ | ------------ | | `kickstart` | Launch orchestrator for milestone/issue/task — auto-discovers context, bootstraps tracking | Mosaic Stack | ### Meta / Skill Authoring (4) -| Skill | Purpose | Origin | -|-------|---------|--------| -| `writing-skills` | TDD-based skill authoring methodology | obra/superpowers | -| `skill-creator` | Anthropic's skill creation guide | anthropics | -| `mcp-builder` | Building MCP (Model Context Protocol) servers | anthropics | -| `webapp-testing` | Web application testing patterns | anthropics | +| Skill | Purpose | Origin | +| ---------------- | --------------------------------------------- | ---------------- | +| `writing-skills` | TDD-based skill authoring methodology | obra/superpowers | +| `skill-creator` | Anthropic's skill creation guide | anthropics | +| `mcp-builder` | Building MCP (Model Context Protocol) servers | anthropics | +| `webapp-testing` | Web application testing patterns | anthropics | ## Source Repositories -| Repository | Skills | Domain Focus | -|-----------|--------|-------------| -| [anthropics/skills](https://github.com/anthropics/skills) | 16 | Documents, design, MCP, testing | -| [obra/superpowers](https://github.com/obra/superpowers) | 14 | Agent workflows, TDD, code review, planning | -| [coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills) | 25 | Marketing, CRO, SEO, growth | -| [antfu/skills](https://github.com/antfu/skills) | 16 | Vue, Vite, Vitest, pnpm, Nuxt | -| [better-auth/skills](https://github.com/better-auth/skills) | 5 | Authentication patterns | -| [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) | 4 | React, design | -| [vercel-labs/next-skills](https://github.com/vercel-labs/next-skills) | 1 | Next.js 15+ | -| [vercel/ai](https://github.com/vercel/ai) | 1 | AI SDK | -| [halthelobster/proactive-agent](https://github.com/halthelobster/proactive-agent) | 1 | Agent architecture | -| [openrouterteam/agent-skills](https://github.com/openrouterteam/agent-skills) | 1 | Agent building | -| [kadajett/agent-nestjs-skills](https://github.com/kadajett/agent-nestjs-skills) | 1 | NestJS | -| [jezweb/claude-skills](https://github.com/jezweb/claude-skills) | 1 | FastAPI | -| [wshobson/agents](https://github.com/wshobson/agents) | 3 | Architecture, Python, Tailwind | -| [mblode/agent-skills](https://github.com/mblode/agent-skills) | 1 | UI animation | -| [giuseppe-trisciuoglio/developer-kit](https://github.com/giuseppe-trisciuoglio/developer-kit) | 1 | shadcn/ui | -| Mosaic Stack (original) | 4 | PR review, code review, orchestration, linting | +| Repository | Skills | Domain Focus | +| --------------------------------------------------------------------------------------------- | ------ | ---------------------------------------------- | +| [anthropics/skills](https://github.com/anthropics/skills) | 16 | Documents, design, MCP, testing | +| [obra/superpowers](https://github.com/obra/superpowers) | 14 | Agent workflows, TDD, code review, planning | +| [coreyhaines31/marketingskills](https://github.com/coreyhaines31/marketingskills) | 25 | Marketing, CRO, SEO, growth | +| [antfu/skills](https://github.com/antfu/skills) | 16 | Vue, Vite, Vitest, pnpm, Nuxt | +| [better-auth/skills](https://github.com/better-auth/skills) | 5 | Authentication patterns | +| [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) | 4 | React, design | +| [vercel-labs/next-skills](https://github.com/vercel-labs/next-skills) | 1 | Next.js 15+ | +| [vercel/ai](https://github.com/vercel/ai) | 1 | AI SDK | +| [halthelobster/proactive-agent](https://github.com/halthelobster/proactive-agent) | 1 | Agent architecture | +| [openrouterteam/agent-skills](https://github.com/openrouterteam/agent-skills) | 1 | Agent building | +| [kadajett/agent-nestjs-skills](https://github.com/kadajett/agent-nestjs-skills) | 1 | NestJS | +| [jezweb/claude-skills](https://github.com/jezweb/claude-skills) | 1 | FastAPI | +| [wshobson/agents](https://github.com/wshobson/agents) | 3 | Architecture, Python, Tailwind | +| [mblode/agent-skills](https://github.com/mblode/agent-skills) | 1 | UI animation | +| [giuseppe-trisciuoglio/developer-kit](https://github.com/giuseppe-trisciuoglio/developer-kit) | 1 | shadcn/ui | +| Mosaic Stack (original) | 4 | PR review, code review, orchestration, linting | ## Installation diff --git a/packages/mosaic/framework/skills/ab-test-setup/SKILL.md b/packages/mosaic/framework/skills/ab-test-setup/SKILL.md index 706e060d..9236c925 100644 --- a/packages/mosaic/framework/skills/ab-test-setup/SKILL.md +++ b/packages/mosaic/framework/skills/ab-test-setup/SKILL.md @@ -24,20 +24,24 @@ Before designing a test, understand: ## Core Principles ### 1. Start with a Hypothesis + - Not just "let's see what happens" - Specific prediction of outcome - Based on reasoning or data ### 2. Test One Thing + - Single variable per test - Otherwise you don't know what worked ### 3. Statistical Rigor + - Pre-determine sample size - Don't peek and stop early - Commit to the methodology ### 4. Measure What Matters + - Primary metric tied to business value - Secondary metrics for context - Guardrail metrics to prevent harm @@ -66,12 +70,12 @@ We'll know this is true when [metrics]. ## Test Types -| Type | Description | Traffic Needed | -|------|-------------|----------------| -| A/B | Two versions, single change | Moderate | -| A/B/n | Multiple variants | Higher | -| MVT | Multiple changes in combinations | Very high | -| Split URL | Different URLs for variants | Moderate | +| Type | Description | Traffic Needed | +| --------- | -------------------------------- | -------------- | +| A/B | Two versions, single change | Moderate | +| A/B/n | Multiple variants | Higher | +| MVT | Multiple changes in combinations | Very high | +| Split URL | Different URLs for variants | Moderate | --- @@ -79,14 +83,15 @@ We'll know this is true when [metrics]. ### Quick Reference -| Baseline | 10% Lift | 20% Lift | 50% Lift | -|----------|----------|----------|----------| -| 1% | 150k/variant | 39k/variant | 6k/variant | -| 3% | 47k/variant | 12k/variant | 2k/variant | -| 5% | 27k/variant | 7k/variant | 1.2k/variant | -| 10% | 12k/variant | 3k/variant | 550/variant | +| Baseline | 10% Lift | 20% Lift | 50% Lift | +| -------- | ------------ | ----------- | ------------ | +| 1% | 150k/variant | 39k/variant | 6k/variant | +| 3% | 47k/variant | 12k/variant | 2k/variant | +| 5% | 27k/variant | 7k/variant | 1.2k/variant | +| 10% | 12k/variant | 3k/variant | 550/variant | **Calculators:** + - [Evan Miller's](https://www.evanmiller.org/ab-testing/sample-size.html) - [Optimizely's](https://www.optimizely.com/sample-size-calculator/) @@ -97,19 +102,23 @@ We'll know this is true when [metrics]. ## Metrics Selection ### Primary Metric + - Single metric that matters most - Directly tied to hypothesis - What you'll use to call the test ### Secondary Metrics + - Support primary metric interpretation - Explain why/how the change worked ### Guardrail Metrics + - Things that shouldn't get worse - Stop test if significantly negative ### Example: Pricing Page Test + - **Primary**: Plan selection rate - **Secondary**: Time on page, plan distribution - **Guardrail**: Support tickets, refund rate @@ -120,14 +129,15 @@ We'll know this is true when [metrics]. ### What to Vary -| Category | Examples | -|----------|----------| -| Headlines/Copy | Message angle, value prop, specificity, tone | -| Visual Design | Layout, color, images, hierarchy | -| CTA | Button copy, size, placement, number | -| Content | Information included, order, amount, social proof | +| Category | Examples | +| -------------- | ------------------------------------------------- | +| Headlines/Copy | Message angle, value prop, specificity, tone | +| Visual Design | Layout, color, images, hierarchy | +| CTA | Button copy, size, placement, number | +| Content | Information included, order, amount, social proof | ### Best Practices + - Single, meaningful change - Bold enough to make a difference - True to the hypothesis @@ -136,13 +146,14 @@ We'll know this is true when [metrics]. ## Traffic Allocation -| Approach | Split | When to Use | -|----------|-------|-------------| -| Standard | 50/50 | Default for A/B | -| Conservative | 90/10, 80/20 | Limit risk of bad variant | -| Ramping | Start small, increase | Technical risk mitigation | +| Approach | Split | When to Use | +| ------------ | --------------------- | ------------------------- | +| Standard | 50/50 | Default for A/B | +| Conservative | 90/10, 80/20 | Limit risk of bad variant | +| Ramping | Start small, increase | Technical risk mitigation | **Considerations:** + - Consistency: Users see same variant on return - Balanced exposure across time of day/week @@ -151,11 +162,13 @@ We'll know this is true when [metrics]. ## Implementation ### Client-Side + - JavaScript modifies page after load - Quick to implement, can cause flicker - Tools: PostHog, Optimizely, VWO ### Server-Side + - Variant determined before render - No flicker, requires dev work - Tools: PostHog, LaunchDarkly, Split @@ -165,6 +178,7 @@ We'll know this is true when [metrics]. ## Running the Test ### Pre-Launch Checklist + - [ ] Hypothesis documented - [ ] Primary metric defined - [ ] Sample size calculated @@ -175,16 +189,19 @@ We'll know this is true when [metrics]. ### During the Test **DO:** + - Monitor for technical issues - Check segment quality - Document external factors **DON'T:** + - Peek at results and stop early - Make changes to variants - Add traffic from new sources ### The Peeking Problem + Looking at results before reaching sample size and stopping early leads to false positives and wrong decisions. Pre-commit to sample size and trust the process. --- @@ -192,6 +209,7 @@ Looking at results before reaching sample size and stopping early leads to false ## Analyzing Results ### Statistical Significance + - 95% confidence = p-value < 0.05 - Means <5% chance result is random - Not a guarantee—just a threshold @@ -207,18 +225,19 @@ Looking at results before reaching sample size and stopping early leads to false ### Interpreting Results -| Result | Conclusion | -|--------|------------| -| Significant winner | Implement variant | -| Significant loser | Keep control, learn why | +| Result | Conclusion | +| ------------------------- | -------------------------------- | +| Significant winner | Implement variant | +| Significant loser | Keep control, learn why | | No significant difference | Need more traffic or bolder test | -| Mixed signals | Dig deeper, maybe segment | +| Mixed signals | Dig deeper, maybe segment | --- ## Documentation Document every test with: + - Hypothesis - Variants (with screenshots) - Results (sample, metrics, significance) @@ -231,16 +250,19 @@ Document every test with: ## Common Mistakes ### Test Design + - Testing too small a change (undetectable) - Testing too many things (can't isolate) - No clear hypothesis ### Execution + - Stopping early - Changing things mid-test - Not checking implementation ### Analysis + - Ignoring confidence intervals - Cherry-picking segments - Over-interpreting inconclusive results diff --git a/packages/mosaic/framework/skills/ab-test-setup/references/sample-size-guide.md b/packages/mosaic/framework/skills/ab-test-setup/references/sample-size-guide.md index c934b02c..25ef9121 100644 --- a/packages/mosaic/framework/skills/ab-test-setup/references/sample-size-guide.md +++ b/packages/mosaic/framework/skills/ab-test-setup/references/sample-size-guide.md @@ -16,6 +16,7 @@ Reference for calculating sample sizes and test duration. **Baseline conversion rate**: If your page converts at 5%, that's your baseline. **MDE (Minimum Detectable Effect)**: The smallest improvement you care about detecting. Set this based on: + - Business impact (is a 5% lift meaningful?) - Implementation cost (worth the effort?) - Realistic expectations (what have past tests shown?) @@ -30,53 +31,53 @@ Reference for calculating sample sizes and test duration. ### Conversion Rate: 1% -| Lift to Detect | Sample per Variant | Total Sample | -|----------------|-------------------|--------------| -| 5% (1% → 1.05%) | 1,500,000 | 3,000,000 | -| 10% (1% → 1.1%) | 380,000 | 760,000 | -| 20% (1% → 1.2%) | 97,000 | 194,000 | -| 50% (1% → 1.5%) | 16,000 | 32,000 | -| 100% (1% → 2%) | 4,200 | 8,400 | +| Lift to Detect | Sample per Variant | Total Sample | +| --------------- | ------------------ | ------------ | +| 5% (1% → 1.05%) | 1,500,000 | 3,000,000 | +| 10% (1% → 1.1%) | 380,000 | 760,000 | +| 20% (1% → 1.2%) | 97,000 | 194,000 | +| 50% (1% → 1.5%) | 16,000 | 32,000 | +| 100% (1% → 2%) | 4,200 | 8,400 | ### Conversion Rate: 3% -| Lift to Detect | Sample per Variant | Total Sample | -|----------------|-------------------|--------------| -| 5% (3% → 3.15%) | 480,000 | 960,000 | -| 10% (3% → 3.3%) | 120,000 | 240,000 | -| 20% (3% → 3.6%) | 31,000 | 62,000 | -| 50% (3% → 4.5%) | 5,200 | 10,400 | -| 100% (3% → 6%) | 1,400 | 2,800 | +| Lift to Detect | Sample per Variant | Total Sample | +| --------------- | ------------------ | ------------ | +| 5% (3% → 3.15%) | 480,000 | 960,000 | +| 10% (3% → 3.3%) | 120,000 | 240,000 | +| 20% (3% → 3.6%) | 31,000 | 62,000 | +| 50% (3% → 4.5%) | 5,200 | 10,400 | +| 100% (3% → 6%) | 1,400 | 2,800 | ### Conversion Rate: 5% -| Lift to Detect | Sample per Variant | Total Sample | -|----------------|-------------------|--------------| -| 5% (5% → 5.25%) | 280,000 | 560,000 | -| 10% (5% → 5.5%) | 72,000 | 144,000 | -| 20% (5% → 6%) | 18,000 | 36,000 | -| 50% (5% → 7.5%) | 3,100 | 6,200 | -| 100% (5% → 10%) | 810 | 1,620 | +| Lift to Detect | Sample per Variant | Total Sample | +| --------------- | ------------------ | ------------ | +| 5% (5% → 5.25%) | 280,000 | 560,000 | +| 10% (5% → 5.5%) | 72,000 | 144,000 | +| 20% (5% → 6%) | 18,000 | 36,000 | +| 50% (5% → 7.5%) | 3,100 | 6,200 | +| 100% (5% → 10%) | 810 | 1,620 | ### Conversion Rate: 10% -| Lift to Detect | Sample per Variant | Total Sample | -|----------------|-------------------|--------------| -| 5% (10% → 10.5%) | 130,000 | 260,000 | -| 10% (10% → 11%) | 34,000 | 68,000 | -| 20% (10% → 12%) | 8,700 | 17,400 | -| 50% (10% → 15%) | 1,500 | 3,000 | -| 100% (10% → 20%) | 400 | 800 | +| Lift to Detect | Sample per Variant | Total Sample | +| ---------------- | ------------------ | ------------ | +| 5% (10% → 10.5%) | 130,000 | 260,000 | +| 10% (10% → 11%) | 34,000 | 68,000 | +| 20% (10% → 12%) | 8,700 | 17,400 | +| 50% (10% → 15%) | 1,500 | 3,000 | +| 100% (10% → 20%) | 400 | 800 | ### Conversion Rate: 20% -| Lift to Detect | Sample per Variant | Total Sample | -|----------------|-------------------|--------------| -| 5% (20% → 21%) | 60,000 | 120,000 | -| 10% (20% → 22%) | 16,000 | 32,000 | -| 20% (20% → 24%) | 4,000 | 8,000 | -| 50% (20% → 30%) | 700 | 1,400 | -| 100% (20% → 40%) | 200 | 400 | +| Lift to Detect | Sample per Variant | Total Sample | +| ---------------- | ------------------ | ------------ | +| 5% (20% → 21%) | 60,000 | 120,000 | +| 10% (20% → 22%) | 16,000 | 32,000 | +| 20% (20% → 24%) | 4,000 | 8,000 | +| 50% (20% → 30%) | 700 | 1,400 | +| 100% (20% → 40%) | 200 | 400 | --- @@ -91,18 +92,21 @@ Duration (days) = (Sample per variant × Number of variants) / (Daily traffic × ### Examples **Scenario 1: High-traffic page** + - Need: 10,000 per variant (2 variants = 20,000 total) - Daily traffic: 5,000 visitors - 100% exposed to test - Duration: 20,000 / 5,000 = **4 days** **Scenario 2: Medium-traffic page** + - Need: 30,000 per variant (60,000 total) - Daily traffic: 2,000 visitors - 100% exposed - Duration: 60,000 / 2,000 = **30 days** **Scenario 3: Low-traffic with partial exposure** + - Need: 15,000 per variant (30,000 total) - Daily traffic: 500 visitors - 50% exposed to test @@ -112,6 +116,7 @@ Duration (days) = (Sample per variant × Number of variants) / (Daily traffic × ### Minimum Duration Rules Even with sufficient sample size, run tests for at least: + - **1 full week**: To capture day-of-week variation - **2 business cycles**: If B2B (weekday vs. weekend patterns) - **Through paydays**: If e-commerce (beginning/end of month) @@ -119,6 +124,7 @@ Even with sufficient sample size, run tests for at least: ### Maximum Duration Guidelines Avoid running tests longer than 4-8 weeks: + - Novelty effects wear off - External factors intervene - Opportunity cost of other tests @@ -131,21 +137,25 @@ Avoid running tests longer than 4-8 weeks: **Evan Miller's Calculator** https://www.evanmiller.org/ab-testing/sample-size.html + - Simple interface - Bookmark-worthy **Optimizely's Calculator** https://www.optimizely.com/sample-size-calculator/ + - Business-friendly language - Duration estimates **AB Test Guide Calculator** https://www.abtestguide.com/calc/ + - Includes Bayesian option - Multiple test types **VWO Duration Calculator** https://vwo.com/tools/ab-test-duration-calculator/ + - Duration-focused - Good for planning @@ -155,14 +165,15 @@ https://vwo.com/tools/ab-test-duration-calculator/ With more than 2 variants (A/B/n tests), you need more sample: -| Variants | Multiplier | -|----------|------------| -| 2 (A/B) | 1x | -| 3 (A/B/C) | ~1.5x | -| 4 (A/B/C/D) | ~2x | -| 5+ | Consider reducing variants | +| Variants | Multiplier | +| ----------- | -------------------------- | +| 2 (A/B) | 1x | +| 3 (A/B/C) | ~1.5x | +| 4 (A/B/C/D) | ~2x | +| 5+ | Consider reducing variants | **Why?** More comparisons increase chance of false positives. You're comparing: + - A vs B - A vs C - B vs C (sometimes) @@ -174,22 +185,27 @@ Apply Bonferroni correction or use tools that handle this automatically. ## Common Sample Size Mistakes ### 1. Underpowered tests + **Problem**: Not enough sample to detect realistic effects **Fix**: Be realistic about MDE, get more traffic, or don't test ### 2. Overpowered tests + **Problem**: Waiting for sample size when you already have significance **Fix**: This is actually fine—you committed to sample size, honor it ### 3. Wrong baseline rate + **Problem**: Using wrong conversion rate for calculation **Fix**: Use the specific metric and page, not site-wide averages ### 4. Ignoring segments + **Problem**: Calculating for full traffic, then analyzing segments **Fix**: If you plan segment analysis, calculate sample for smallest segment ### 5. Testing too many things + **Problem**: Dividing traffic too many ways **Fix**: Prioritize ruthlessly, run fewer concurrent tests @@ -214,19 +230,23 @@ Options when you can't get enough traffic: If you must check results before reaching sample size: ### What is it? + Statistical method that adjusts for multiple looks at data. ### When to use + - High-risk changes - Need to stop bad variants early - Time-sensitive decisions ### Tools that support it + - Optimizely (Stats Accelerator) - VWO (SmartStats) - PostHog (Bayesian approach) ### Tradeoff + - More flexibility to stop early - Slightly larger sample size requirement - More complex analysis diff --git a/packages/mosaic/framework/skills/ab-test-setup/references/test-templates.md b/packages/mosaic/framework/skills/ab-test-setup/references/test-templates.md index a504421b..302432f9 100644 --- a/packages/mosaic/framework/skills/ab-test-setup/references/test-templates.md +++ b/packages/mosaic/framework/skills/ab-test-setup/references/test-templates.md @@ -8,6 +8,7 @@ Templates for planning, documenting, and analyzing experiments. # A/B Test: [Name] ## Overview + - **Owner**: [Name] - **Test ID**: [ID in testing tool] - **Page/Feature**: [What's being tested] @@ -23,24 +24,28 @@ We'll know this is true when [metrics]. ## Test Design -| Element | Details | -|---------|---------| -| Test type | A/B / A/B/n / MVT | -| Duration | X weeks | -| Sample size | X per variant | -| Traffic allocation | 50/50 | -| Tool | [Tool name] | -| Implementation | Client-side / Server-side | +| Element | Details | +| ------------------ | ------------------------- | +| Test type | A/B / A/B/n / MVT | +| Duration | X weeks | +| Sample size | X per variant | +| Traffic allocation | 50/50 | +| Tool | [Tool name] | +| Implementation | Client-side / Server-side | ## Variants ### Control (A) + [Screenshot] + - Current experience - [Key details about current state] ### Variant (B) + [Screenshot or mockup] + - [Specific change #1] - [Specific change #2] - Rationale: [Why we think this will win] @@ -48,32 +53,38 @@ We'll know this is true when [metrics]. ## Metrics ### Primary + - **Metric**: [metric name] - **Definition**: [how it's calculated] - **Current baseline**: [X%] - **Minimum detectable effect**: [X%] ### Secondary + - [Metric 1]: [what it tells us] - [Metric 2]: [what it tells us] - [Metric 3]: [what it tells us] ### Guardrails + - [Metric that shouldn't get worse] - [Another safety metric] ## Segment Analysis Plan + - Mobile vs. desktop - New vs. returning visitors - Traffic source - [Other relevant segments] ## Success Criteria + - Winner: [Primary metric improves by X% with 95% confidence] - Loser: [Primary metric decreases significantly] - Inconclusive: [What we'll do if no significant result] ## Pre-Launch Checklist + - [ ] Hypothesis documented and reviewed - [ ] Primary metric defined and trackable - [ ] Sample size calculated @@ -93,46 +104,50 @@ We'll know this is true when [metrics]. # A/B Test Results: [Name] ## Summary -| Element | Value | -|---------|-------| -| Test ID | [ID] | -| Dates | [Start] - [End] | -| Duration | X days | -| Result | Winner / Loser / Inconclusive | -| Decision | [What we're doing] | + +| Element | Value | +| -------- | ----------------------------- | +| Test ID | [ID] | +| Dates | [Start] - [End] | +| Duration | X days | +| Result | Winner / Loser / Inconclusive | +| Decision | [What we're doing] | ## Hypothesis (Reminder) + [Copy from test plan] ## Results ### Sample Size + | Variant | Target | Actual | % of target | -|---------|--------|--------|-------------| -| Control | X | Y | Z% | -| Variant | X | Y | Z% | +| ------- | ------ | ------ | ----------- | +| Control | X | Y | Z% | +| Variant | X | Y | Z% | ### Primary Metric: [Metric Name] -| Variant | Value | 95% CI | vs. Control | -|---------|-------|--------|-------------| -| Control | X% | [X%, Y%] | — | -| Variant | X% | [X%, Y%] | +X% | + +| Variant | Value | 95% CI | vs. Control | +| ------- | ----- | -------- | ----------- | +| Control | X% | [X%, Y%] | — | +| Variant | X% | [X%, Y%] | +X% | **Statistical significance**: p = X.XX (95% = sig / not sig) **Practical significance**: [Is this lift meaningful for the business?] ### Secondary Metrics -| Metric | Control | Variant | Change | Significant? | -|--------|---------|---------|--------|--------------| -| [Metric 1] | X | Y | +Z% | Yes/No | -| [Metric 2] | X | Y | +Z% | Yes/No | +| Metric | Control | Variant | Change | Significant? | +| ---------- | ------- | ------- | ------ | ------------ | +| [Metric 1] | X | Y | +Z% | Yes/No | +| [Metric 2] | X | Y | +Z% | Yes/No | ### Guardrail Metrics -| Metric | Control | Variant | Change | Concern? | -|--------|---------|---------|--------|----------| -| [Metric 1] | X | Y | +Z% | Yes/No | +| Metric | Control | Variant | Change | Concern? | +| ---------- | ------- | ------- | ------ | -------- | +| [Metric 1] | X | Y | +Z% | Yes/No | ### Segment Analysis @@ -151,12 +166,15 @@ We'll know this is true when [metrics]. ## Interpretation ### What happened? + [Explanation of results in plain language] ### Why do we think this happened? + [Analysis and reasoning] ### Caveats + [Any limitations, external factors, or concerns] ## Decision @@ -170,14 +188,17 @@ We'll know this is true when [metrics]. ## Learnings ### What we learned + - [Key insight 1] - [Key insight 2] ### What to test next + - [Follow-up test idea 1] - [Follow-up test idea 2] ### Impact + - **Projected lift**: [X% improvement in Y metric] - **Business impact**: [Revenue, conversions, etc.] ``` @@ -189,11 +210,11 @@ We'll know this is true when [metrics]. For tracking all tests in a central location: ```markdown -| Test ID | Name | Page | Dates | Primary Metric | Result | Lift | Link | -|---------|------|------|-------|----------------|--------|------|------| -| 001 | Hero headline test | Homepage | 1/1-1/15 | CTR | Winner | +12% | [Link] | -| 002 | Pricing table layout | Pricing | 1/10-1/31 | Plan selection | Loser | -5% | [Link] | -| 003 | Signup form fields | Signup | 2/1-2/14 | Completion | Inconclusive | +2% | [Link] | +| Test ID | Name | Page | Dates | Primary Metric | Result | Lift | Link | +| ------- | -------------------- | -------- | --------- | -------------- | ------------ | ---- | ------ | +| 001 | Hero headline test | Homepage | 1/1-1/15 | CTR | Winner | +12% | [Link] | +| 002 | Pricing table layout | Pricing | 1/10-1/31 | Plan selection | Loser | -5% | [Link] | +| 003 | Signup form fields | Signup | 2/1-2/14 | Completion | Inconclusive | +2% | [Link] | ``` --- @@ -225,15 +246,18 @@ For simple tests that don't need full documentation: **Current sample**: X% of target ### Preliminary observations + [What we're seeing - without making decisions yet] ### Next steps + [What happens next] ### Timeline + - [Date]: Analysis complete - [Date]: Decision and recommendation -- [Date]: Implementation (if winner) +- [Date]: Implementation 'if winner' ``` --- @@ -242,14 +266,14 @@ For simple tests that don't need full documentation: For deciding which tests to run: -| Factor | Weight | Test A | Test B | Test C | -|--------|--------|--------|--------|--------| -| Potential impact | 30% | | | | -| Confidence in hypothesis | 25% | | | | -| Ease of implementation | 20% | | | | -| Risk if wrong | 15% | | | | -| Strategic alignment | 10% | | | | -| **Total** | | | | | +| Factor | Weight | Test A | Test B | Test C | +| ------------------------ | ------ | ------ | ------ | ------ | +| Potential impact | 30% | | | | +| Confidence in hypothesis | 25% | | | | +| Ease of implementation | 20% | | | | +| Risk if wrong | 15% | | | | +| Strategic alignment | 10% | | | | +| **Total** | | | | | Scoring: 1-5 (5 = best) @@ -260,9 +284,9 @@ Scoring: 1-5 (5 = best) For collecting test ideas: ```markdown -| ID | Page/Area | Observation | Hypothesis | Potential Impact | Status | -|----|-----------|-------------|------------|------------------|--------| -| H1 | Homepage | Low scroll depth | Shorter hero will increase scroll | High | Testing | -| H2 | Pricing | Users compare plans | Comparison table will help | Medium | Backlog | -| H3 | Signup | Drop-off at email | Social login will increase completion | Medium | Backlog | +| ID | Page/Area | Observation | Hypothesis | Potential Impact | Status | +| --- | --------- | ------------------- | ------------------------------------- | ---------------- | ------- | +| H1 | Homepage | Low scroll depth | Shorter hero will increase scroll | High | Testing | +| H2 | Pricing | Users compare plans | Comparison table will help | Medium | Backlog | +| H3 | Signup | Drop-off at email | Social login will increase completion | Medium | Backlog | ``` diff --git a/packages/mosaic/framework/skills/ai-sdk/references/common-errors.md b/packages/mosaic/framework/skills/ai-sdk/references/common-errors.md index 529521eb..d628927e 100644 --- a/packages/mosaic/framework/skills/ai-sdk/references/common-errors.md +++ b/packages/mosaic/framework/skills/ai-sdk/references/common-errors.md @@ -225,7 +225,7 @@ export default function Page() { transport: new DefaultChatTransport({ api: '/api/chat' }), }); - const handleSubmit = e => { + const handleSubmit = (e) => { e.preventDefault(); sendMessage({ text: input }); setInput(''); @@ -233,7 +233,7 @@ export default function Page() { return (
- setInput(e.target.value)} /> + setInput(e.target.value)} />
); @@ -259,18 +259,14 @@ Typed tool parts also use different property names: case 'text': return
{part.text}
; case 'tool-invocation': // deprecated: use typed tool parts instead - return ( - 
-            {JSON.stringify(part.toolInvocation, null, 2)}
-
- ); + return 
{JSON.stringify(part.toolInvocation, null, 2)}
; } }); } // ✅ Correct - using typed tool parts (recommended) { - message.parts.map(part => { + message.parts.map((part) => { switch (part.type) { case 'text': return part.text; @@ -288,7 +284,7 @@ Typed tool parts also use different property names: import { isToolUIPart } from 'ai'; { - message.parts.map(part => { + message.parts.map((part) => { if (part.type === 'text') { return part.text; } diff --git a/packages/mosaic/framework/skills/ai-sdk/references/type-safe-agents.md b/packages/mosaic/framework/skills/ai-sdk/references/type-safe-agents.md index 17d7a6fd..94f22ef2 100644 --- a/packages/mosaic/framework/skills/ai-sdk/references/type-safe-agents.md +++ b/packages/mosaic/framework/skills/ai-sdk/references/type-safe-agents.md @@ -85,7 +85,7 @@ export function Chat() { return (
- {messages.map(message => ( + {messages.map((message) => ( ))}
@@ -161,11 +161,7 @@ Then import only the type in your component: // components/weather-tool.tsx import type { WeatherToolInvocation } from '@/lib/tools/weather-tool'; -export function WeatherToolComponent({ - invocation, -}: { - invocation: WeatherToolInvocation; -}) { +export function WeatherToolComponent({ invocation }: { invocation: WeatherToolInvocation }) { // invocation.input and invocation.output are fully typed if (invocation.state === 'output-available') { return ( diff --git a/packages/mosaic/framework/skills/algorithmic-art/SKILL.md b/packages/mosaic/framework/skills/algorithmic-art/SKILL.md index 634f6fa4..8d31a4f1 100644 --- a/packages/mosaic/framework/skills/algorithmic-art/SKILL.md +++ b/packages/mosaic/framework/skills/algorithmic-art/SKILL.md @@ -7,6 +7,7 @@ license: Complete terms in LICENSE.txt Algorithmic philosophies are computational aesthetic movements that are then expressed through code. Output .md files (philosophy), .html files (interactive viewer), and .js files (generative algorithms). This happens in two steps: + 1. Algorithmic Philosophy Creation (.md file) 2. Express by creating p5.js generative art (.html + .js files) @@ -15,17 +16,20 @@ First, undertake this task: ## ALGORITHMIC PHILOSOPHY CREATION To begin, create an ALGORITHMIC PHILOSOPHY (not static images or templates) that will be interpreted through: + - Computational processes, emergent behavior, mathematical beauty - Seeded randomness, noise fields, organic systems - Particles, flows, fields, forces - Parametric variation and controlled chaos ### THE CRITICAL UNDERSTANDING + - What is received: Some subtle input or instructions by the user to take into account, but use as a foundation; it should not constrain creative freedom. - What is created: An algorithmic philosophy/generative aesthetic movement. - What happens next: The same version receives the philosophy and EXPRESSES IT IN CODE - creating p5.js sketches that are 90% algorithmic generation, 10% essential parameters. Consider this approach: + - Write a manifesto for a generative art movement - The next phase involves writing the algorithm that brings it to life @@ -38,6 +42,7 @@ The philosophy must emphasize: Algorithmic expression. Emergent behavior. Comput **Articulate the philosophy** (4-6 paragraphs - concise but complete): To capture the ALGORITHMIC essence, express how this philosophy manifests through: + - Computational processes and mathematical relationships? - Noise functions and randomness patterns? - Particle behaviors and field dynamics? @@ -45,6 +50,7 @@ To capture the ALGORITHMIC essence, express how this philosophy manifests throug - Parametric variation and emergent complexity? **CRITICAL GUIDELINES:** + - **Avoid redundancy**: Each algorithmic aspect should be mentioned once. Avoid repeating concepts about noise theory, particle dynamics, or mathematical principles unless adding new depth. - **Emphasize craftsmanship REPEATEDLY**: The philosophy MUST stress multiple times that the final algorithm should appear as though it took countless hours to develop, was refined with care, and comes from someone at the absolute top of their field. This framing is essential - repeat phrases like "meticulously crafted algorithm," "the product of deep computational expertise," "painstaking optimization," "master-level implementation." - **Leave creative space**: Be specific about the algorithmic direction, but concise enough that the next Claude has room to make interpretive implementation choices at an extremely high level of craftsmanship. @@ -73,9 +79,10 @@ Algorithmic expression: Vector fields constructed from mathematical functions or Philosophy: Random processes crystallizing into ordered structures. Algorithmic expression: Randomized circle packing or Voronoi tessellation. Start with random points, let them evolve through relaxation algorithms. Cells push apart until equilibrium. Color based on cell size, neighbor count, or distance from center. The organic tiling that emerges feels both random and inevitable. Every seed produces unique crystalline beauty - the mark of a master-level generative algorithm. -*These are condensed examples. The actual algorithmic philosophy should be 4-6 substantial paragraphs.* +_These are condensed examples. The actual algorithmic philosophy should be 4-6 substantial paragraphs._ ### ESSENTIAL PRINCIPLES + - **ALGORITHMIC PHILOSOPHY**: Creating a computational worldview to be expressed through code - **PROCESS OVER PRODUCT**: Always emphasize that beauty emerges from the algorithm's execution - each run is unique - **PARAMETRIC EXPRESSION**: Ideas communicate through mathematical relationships, forces, behaviors - not static composition @@ -113,12 +120,14 @@ With the philosophy AND conceptual framework established, express it through cod 5. **Replace only the VARIABLE sections** marked in the file's comments (algorithm, parameters, UI controls for parameters) **Avoid:** + - ❌ Creating HTML from scratch - ❌ Inventing custom styling or color schemes - ❌ Using system fonts or dark themes - ❌ Changing the sidebar structure **Follow these practices:** + - ✅ Copy the template's exact HTML structure - ✅ Keep Anthropic branding (Poppins/Lora fonts, light colors, gradient backdrop) - ✅ Maintain the sidebar layout (Seed → Parameters → Colors? → Actions) @@ -133,6 +142,7 @@ To create gallery-quality computational art that lives and breathes, use the alg ### TECHNICAL REQUIREMENTS **Seeded Randomness (Art Blocks Pattern)**: + ```javascript // ALWAYS use a seed for reproducibility let seed = 12345; // or hash from user input @@ -146,7 +156,7 @@ To establish parameters that emerge naturally from the algorithmic philosophy, c ```javascript let params = { - seed: 12345, // Always include seed for reproducibility + seed: 12345, // Always include seed for reproducibility // colors // Add parameters that control YOUR algorithm: // - Quantities (how many?) @@ -167,16 +177,19 @@ let params = { To express the philosophy through code, avoid thinking "which pattern should I use?" and instead think "how to express this philosophy through code?" If the philosophy is about **organic emergence**, consider using: + - Elements that accumulate or grow over time - Random processes constrained by natural rules - Feedback loops and interactions If the philosophy is about **mathematical beauty**, consider using: + - Geometric relationships and ratios - Trigonometric functions and harmonics - Precise calculations creating unexpected patterns If the philosophy is about **controlled chaos**, consider using: + - Random variation within strict boundaries - Bifurcation and phase transitions - Order emerging from disorder @@ -186,6 +199,7 @@ If the philosophy is about **controlled chaos**, consider using: To guide the implementation, let the conceptual essence inform creative and original choices. Build something that expresses the vision for this particular request. **Canvas Setup**: Standard p5.js structure: + ```javascript function setup() { createCanvas(1200, 1200); @@ -211,6 +225,7 @@ function draw() { ### OUTPUT FORMAT Output: + 1. **Algorithmic Philosophy** - As markdown or text explaining the generative aesthetic 2. **Single HTML Artifact** - Self-contained interactive generative art built from `templates/viewer.html` (see STEP 0 and next section) @@ -229,6 +244,7 @@ To allow exploration of the generative art, create a single, self-contained HTML The `templates/viewer.html` file is the foundation. It contains the exact structure and styling needed. **FIXED (always include exactly as shown):** + - Layout structure (header, sidebar, main canvas area) - Anthropic branding (UI colors, fonts, gradients) - Seed section in sidebar: @@ -241,6 +257,7 @@ The `templates/viewer.html` file is the foundation. It contains the exact struct - Reset button **VARIABLE (customize for each artwork):** + - The entire p5.js algorithm (setup/draw/classes) - The parameters object (define what the art needs) - The Parameters section in sidebar: @@ -259,12 +276,14 @@ The `templates/viewer.html` file is the foundation. It contains the exact struct ### REQUIRED FEATURES **1. Parameter Controls** + - Sliders for numeric parameters (particle count, noise scale, speed, etc.) - Color pickers for palette colors - Real-time updates when parameters change - Reset button to restore defaults **2. Seed Navigation** + - Display current seed number - "Previous" and "Next" buttons to cycle through seeds - "Random" button for random seed @@ -272,30 +291,31 @@ The `templates/viewer.html` file is the foundation. It contains the exact struct - Generate 100 variations when requested (seeds 1-100) **3. Single Artifact Structure** + ```html - - - - - - -
-
- -
- - + + + + + + +
+
+ +
+ + ``` @@ -306,30 +326,44 @@ The `templates/viewer.html` file is the foundation. It contains the exact struct The sidebar structure: **1. Seed (FIXED)** - Always include exactly as shown: + - Seed display - Prev/Next/Random/Jump buttons **2. Parameters (VARIABLE)** - Create controls for the art: + ```html
- - - ... + + + ...
``` + Add as many control-group divs as there are parameters. **3. Colors (OPTIONAL/VARIABLE)** - Include if the art needs adjustable colors: + - Add color pickers if users should control palette - Skip this section if the art uses fixed colors - Skip if the art is monochrome **4. Actions (FIXED)** - Always include exactly as shown: + - Regenerate button - Reset button - Download PNG button **Requirements**: + - Seed controls must work (prev/next/random/jump/display) - All parameters must have UI controls - Regenerate, Reset, Download buttons must work @@ -338,6 +372,7 @@ Add as many control-group divs as there are parameters. ### USING THE ARTIFACT The HTML artifact works immediately: + 1. **In claude.ai**: Displayed as an interactive artifact - runs instantly 2. **As a file**: Save and open in any browser - no server needed 3. **Sharing**: Send the HTML file - it's completely self-contained @@ -369,11 +404,13 @@ Each request is unique. The process involves: 5. **Build matching UI controls** - Sliders/inputs for those parameters **The constants**: + - Anthropic branding (colors, fonts, layout) - Seed navigation (always present) - Self-contained HTML artifact **Everything else is variable**: + - The algorithm itself - The parameters - The UI controls @@ -399,7 +436,8 @@ This skill includes helpful templates and documentation: - Embed algorithms inline in the HTML artifact (don't create separate .js files) **Critical reminder**: + - The **template is the STARTING POINT**, not inspiration - The **algorithm is where to create** something unique - Don't copy the flow field example - build what the philosophy demands -- But DO keep the exact UI structure and Anthropic branding from the template \ No newline at end of file +- But DO keep the exact UI structure and Anthropic branding from the template diff --git a/packages/mosaic/framework/skills/analytics-tracking/SKILL.md b/packages/mosaic/framework/skills/analytics-tracking/SKILL.md index 098e992d..fcd7fb33 100644 --- a/packages/mosaic/framework/skills/analytics-tracking/SKILL.md +++ b/packages/mosaic/framework/skills/analytics-tracking/SKILL.md @@ -24,21 +24,25 @@ Before implementing tracking, understand: ## Core Principles ### 1. Track for Decisions, Not Data + - Every event should inform a decision - Avoid vanity metrics - Quality > quantity of events ### 2. Start with the Questions + - What do you need to know? - What actions will you take based on this data? - Work backwards to what you need to track ### 3. Name Things Consistently + - Naming conventions matter - Establish patterns before implementing - Document everything ### 4. Maintain Data Quality + - Validate implementation - Monitor for issues - Clean data > more data @@ -56,12 +60,12 @@ Event Name | Category | Properties | Trigger | Notes ### Event Types -| Type | Examples | -|------|----------| -| Pageviews | Automatic, enhanced with metadata | -| User Actions | Button clicks, form submissions, feature usage | -| System Events | Signup completed, purchase, subscription changed | -| Custom Conversions | Goal completions, funnel stages | +| Type | Examples | +| ------------------ | ------------------------------------------------ | +| Pageviews | Automatic, enhanced with metadata | +| User Actions | Button clicks, form submissions, feature usage | +| System Events | Signup completed, purchase, subscription changed | +| Custom Conversions | Goal completions, funnel stages | **For comprehensive event lists**: See [references/event-library.md](references/event-library.md) @@ -80,6 +84,7 @@ checkout_payment_completed ``` ### Best Practices + - Lowercase with underscores - Be specific: `cta_hero_clicked` vs. `button_clicked` - Include context in properties, not event name @@ -92,21 +97,21 @@ checkout_payment_completed ### Marketing Site -| Event | Properties | -|-------|------------| -| cta_clicked | button_text, location | -| form_submitted | form_type | -| signup_completed | method, source | -| demo_requested | - | +| Event | Properties | +| ---------------- | --------------------- | +| cta_clicked | button_text, location | +| form_submitted | form_type | +| signup_completed | method, source | +| demo_requested | - | ### Product/App -| Event | Properties | -|-------|------------| +| Event | Properties | +| ------------------------- | ---------------------- | | onboarding_step_completed | step_number, step_name | -| feature_used | feature_name | -| purchase_completed | plan, value | -| subscription_cancelled | reason | +| feature_used | feature_name | +| purchase_completed | plan, value | +| subscription_cancelled | reason | **For full event library by business type**: See [references/event-library.md](references/event-library.md) @@ -116,14 +121,15 @@ checkout_payment_completed ### Standard Properties -| Category | Properties | -|----------|------------| -| Page | page_title, page_location, page_referrer | -| User | user_id, user_type, account_id, plan_type | -| Campaign | source, medium, campaign, content, term | -| Product | product_id, product_name, category, price | +| Category | Properties | +| -------- | ----------------------------------------- | +| Page | page_title, page_location, page_referrer | +| User | user_id, user_type, account_id, plan_type | +| Campaign | source, medium, campaign, content, term | +| Product | product_id, product_name, category, price | ### Best Practices + - Use consistent property names - Include relevant context - Don't duplicate automatic properties @@ -145,8 +151,8 @@ checkout_payment_completed ```javascript gtag('event', 'signup_completed', { - 'method': 'email', - 'plan': 'free' + method: 'email', + plan: 'free', }); ``` @@ -158,19 +164,19 @@ gtag('event', 'signup_completed', { ### Container Structure -| Component | Purpose | -|-----------|---------| -| Tags | Code that executes (GA4, pixels) | -| Triggers | When tags fire (page view, click) | +| Component | Purpose | +| --------- | --------------------------------------- | +| Tags | Code that executes (GA4, pixels) | +| Triggers | When tags fire (page view, click) | | Variables | Dynamic values (click text, data layer) | ### Data Layer Pattern ```javascript dataLayer.push({ - 'event': 'form_submitted', - 'form_name': 'contact', - 'form_location': 'footer' + event: 'form_submitted', + form_name: 'contact', + form_location: 'footer', }); ``` @@ -182,15 +188,16 @@ dataLayer.push({ ### Standard Parameters -| Parameter | Purpose | Example | -|-----------|---------|---------| -| utm_source | Traffic source | google, newsletter | -| utm_medium | Marketing medium | cpc, email, social | -| utm_campaign | Campaign name | spring_sale | -| utm_content | Differentiate versions | hero_cta | -| utm_term | Paid search keywords | running+shoes | +| Parameter | Purpose | Example | +| ------------ | ---------------------- | ------------------ | +| utm_source | Traffic source | google, newsletter | +| utm_medium | Marketing medium | cpc, email, social | +| utm_campaign | Campaign name | spring_sale | +| utm_content | Differentiate versions | hero_cta | +| utm_term | Paid search keywords | running+shoes | ### Naming Conventions + - Lowercase everything - Use underscores or hyphens consistently - Be specific but concise: `blog_footer_cta`, not `cta1` @@ -202,10 +209,10 @@ dataLayer.push({ ### Testing Tools -| Tool | Use For | -|------|---------| -| GA4 DebugView | Real-time event monitoring | -| GTM Preview Mode | Test triggers before publish | +| Tool | Use For | +| ------------------ | ---------------------------------- | +| GA4 DebugView | Real-time event monitoring | +| GTM Preview Mode | Test triggers before publish | | Browser Extensions | Tag Assistant, dataLayer Inspector | ### Validation Checklist @@ -219,23 +226,25 @@ dataLayer.push({ ### Common Issues -| Issue | Check | -|-------|-------| -| Events not firing | Trigger config, GTM loaded | -| Wrong values | Variable path, data layer structure | -| Duplicate events | Multiple containers, trigger firing twice | +| Issue | Check | +| ----------------- | ----------------------------------------- | +| Events not firing | Trigger config, GTM loaded | +| Wrong values | Variable path, data layer structure | +| Duplicate events | Multiple containers, trigger firing twice | --- ## Privacy and Compliance ### Considerations + - Cookie consent required in EU/UK/CA - No PII in analytics properties - Data retention settings - User deletion capabilities ### Implementation + - Use consent mode (wait for consent) - IP anonymization - Only collect what you need @@ -251,26 +260,27 @@ dataLayer.push({ # [Site/Product] Tracking Plan ## Overview + - Tools: GA4, GTM - Last updated: [Date] ## Events -| Event Name | Description | Properties | Trigger | -|------------|-------------|------------|---------| +| Event Name | Description | Properties | Trigger | +| ---------------- | --------------------- | ------------ | ------------ | | signup_completed | User completes signup | method, plan | Success page | ## Custom Dimensions -| Name | Scope | Parameter | -|------|-------|-----------| -| user_type | User | user_type | +| Name | Scope | Parameter | +| --------- | ----- | --------- | +| user_type | User | user_type | ## Conversions -| Conversion | Event | Counting | -|------------|-------|----------| -| Signup | signup_completed | Once per session | +| Conversion | Event | Counting | +| ---------- | ---------------- | ---------------- | +| Signup | signup_completed | Once per session | ``` --- @@ -290,13 +300,13 @@ dataLayer.push({ For implementation, see the [tools registry](../../tools/REGISTRY.md). Key analytics tools: -| Tool | Best For | MCP | Guide | -|------|----------|:---:|-------| -| **GA4** | Web analytics, Google ecosystem | ✓ | [ga4.md](../../tools/integrations/ga4.md) | -| **Mixpanel** | Product analytics, event tracking | - | [mixpanel.md](../../tools/integrations/mixpanel.md) | -| **Amplitude** | Product analytics, cohort analysis | - | [amplitude.md](../../tools/integrations/amplitude.md) | -| **PostHog** | Open-source analytics, session replay | - | [posthog.md](../../tools/integrations/posthog.md) | -| **Segment** | Customer data platform, routing | - | [segment.md](../../tools/integrations/segment.md) | +| Tool | Best For | MCP | Guide | +| ------------- | ------------------------------------- | :-: | ----------------------------------------------------- | +| **GA4** | Web analytics, Google ecosystem | ✓ | [ga4.md](../../tools/integrations/ga4.md) | +| **Mixpanel** | Product analytics, event tracking | - | [mixpanel.md](../../tools/integrations/mixpanel.md) | +| **Amplitude** | Product analytics, cohort analysis | - | [amplitude.md](../../tools/integrations/amplitude.md) | +| **PostHog** | Open-source analytics, session replay | - | [posthog.md](../../tools/integrations/posthog.md) | +| **Segment** | Customer data platform, routing | - | [segment.md](../../tools/integrations/segment.md) | --- diff --git a/packages/mosaic/framework/skills/analytics-tracking/references/event-library.md b/packages/mosaic/framework/skills/analytics-tracking/references/event-library.md index 586025e4..6acb779c 100644 --- a/packages/mosaic/framework/skills/analytics-tracking/references/event-library.md +++ b/packages/mosaic/framework/skills/analytics-tracking/references/event-library.md @@ -6,36 +6,36 @@ Comprehensive list of events to track by business type and context. ### Navigation & Engagement -| Event Name | Description | Properties | -|------------|-------------|------------| -| page_view | Page loaded (enhanced) | page_title, page_location, content_group | -| scroll_depth | User scrolled to threshold | depth (25, 50, 75, 100) | -| outbound_link_clicked | Click to external site | link_url, link_text | -| internal_link_clicked | Click within site | link_url, link_text, location | -| video_played | Video started | video_id, video_title, duration | -| video_completed | Video finished | video_id, video_title, duration | +| Event Name | Description | Properties | +| --------------------- | -------------------------- | ---------------------------------------- | +| page_view | Page loaded (enhanced) | page_title, page_location, content_group | +| scroll_depth | User scrolled to threshold | depth (25, 50, 75, 100) | +| outbound_link_clicked | Click to external site | link_url, link_text | +| internal_link_clicked | Click within site | link_url, link_text, location | +| video_played | Video started | video_id, video_title, duration | +| video_completed | Video finished | video_id, video_title, duration | ### CTA & Form Interactions -| Event Name | Description | Properties | -|------------|-------------|------------| -| cta_clicked | Call to action clicked | button_text, cta_location, page | -| form_started | User began form | form_name, form_location | -| form_field_completed | Field filled | form_name, field_name | -| form_submitted | Form successfully sent | form_name, form_location | -| form_error | Form validation failed | form_name, error_type | -| resource_downloaded | Asset downloaded | resource_name, resource_type | +| Event Name | Description | Properties | +| -------------------- | ---------------------- | ------------------------------- | +| cta_clicked | Call to action clicked | button_text, cta_location, page | +| form_started | User began form | form_name, form_location | +| form_field_completed | Field filled | form_name, field_name | +| form_submitted | Form successfully sent | form_name, form_location | +| form_error | Form validation failed | form_name, error_type | +| resource_downloaded | Asset downloaded | resource_name, resource_type | ### Conversion Events -| Event Name | Description | Properties | -|------------|-------------|------------| -| signup_started | Initiated signup | source, page | -| signup_completed | Finished signup | method, plan, source | -| demo_requested | Demo form submitted | company_size, industry | -| contact_submitted | Contact form sent | inquiry_type | -| newsletter_subscribed | Email list signup | source, list_name | -| trial_started | Free trial began | plan, source | +| Event Name | Description | Properties | +| --------------------- | ------------------- | ---------------------- | +| signup_started | Initiated signup | source, page | +| signup_completed | Finished signup | method, plan, source | +| demo_requested | Demo form submitted | company_size, industry | +| contact_submitted | Contact form sent | inquiry_type | +| newsletter_subscribed | Email list signup | source, list_name | +| trial_started | Free trial began | plan, source | --- @@ -43,37 +43,37 @@ Comprehensive list of events to track by business type and context. ### Onboarding -| Event Name | Description | Properties | -|------------|-------------|------------| -| signup_completed | Account created | method, referral_source | -| onboarding_started | Began onboarding | - | -| onboarding_step_completed | Step finished | step_number, step_name | -| onboarding_completed | All steps done | steps_completed, time_to_complete | -| onboarding_skipped | User skipped onboarding | step_skipped_at | -| first_key_action_completed | Aha moment reached | action_type | +| Event Name | Description | Properties | +| -------------------------- | ----------------------- | --------------------------------- | +| signup_completed | Account created | method, referral_source | +| onboarding_started | Began onboarding | - | +| onboarding_step_completed | Step finished | step_number, step_name | +| onboarding_completed | All steps done | steps_completed, time_to_complete | +| onboarding_skipped | User skipped onboarding | step_skipped_at | +| first_key_action_completed | Aha moment reached | action_type | ### Core Usage -| Event Name | Description | Properties | -|------------|-------------|------------| -| session_started | App session began | session_number | -| feature_used | Feature interaction | feature_name, feature_category | -| action_completed | Core action done | action_type, count | -| content_created | User created content | content_type | -| content_edited | User modified content | content_type | -| content_deleted | User removed content | content_type | -| search_performed | In-app search | query, results_count | -| settings_changed | Settings modified | setting_name, new_value | -| invite_sent | User invited others | invite_type, count | +| Event Name | Description | Properties | +| ---------------- | --------------------- | ------------------------------ | +| session_started | App session began | session_number | +| feature_used | Feature interaction | feature_name, feature_category | +| action_completed | Core action done | action_type, count | +| content_created | User created content | content_type | +| content_edited | User modified content | content_type | +| content_deleted | User removed content | content_type | +| search_performed | In-app search | query, results_count | +| settings_changed | Settings modified | setting_name, new_value | +| invite_sent | User invited others | invite_type, count | ### Errors & Support -| Event Name | Description | Properties | -|------------|-------------|------------| -| error_occurred | Error experienced | error_type, error_message, page | -| help_opened | Help accessed | help_type, page | -| support_contacted | Support request made | contact_method, issue_type | -| feedback_submitted | User feedback given | feedback_type, rating | +| Event Name | Description | Properties | +| ------------------ | -------------------- | ------------------------------- | +| error_occurred | Error experienced | error_type, error_message, page | +| help_opened | Help accessed | help_type, page | +| support_contacted | Support request made | contact_method, issue_type | +| feedback_submitted | User feedback given | feedback_type, rating | --- @@ -81,26 +81,26 @@ Comprehensive list of events to track by business type and context. ### Pricing & Checkout -| Event Name | Description | Properties | -|------------|-------------|------------| -| pricing_viewed | Pricing page seen | source | -| plan_selected | Plan chosen | plan_name, billing_cycle | -| checkout_started | Began checkout | plan, value | -| payment_info_entered | Payment submitted | payment_method | -| purchase_completed | Purchase successful | plan, value, currency, transaction_id | -| purchase_failed | Purchase failed | error_reason, plan | +| Event Name | Description | Properties | +| -------------------- | ------------------- | ------------------------------------- | +| pricing_viewed | Pricing page seen | source | +| plan_selected | Plan chosen | plan_name, billing_cycle | +| checkout_started | Began checkout | plan, value | +| payment_info_entered | Payment submitted | payment_method | +| purchase_completed | Purchase successful | plan, value, currency, transaction_id | +| purchase_failed | Purchase failed | error_reason, plan | ### Subscription Management -| Event Name | Description | Properties | -|------------|-------------|------------| -| trial_started | Trial began | plan, trial_length | -| trial_ended | Trial expired | plan, converted (bool) | -| subscription_upgraded | Plan upgraded | from_plan, to_plan, value | -| subscription_downgraded | Plan downgraded | from_plan, to_plan | -| subscription_cancelled | Cancelled | plan, reason, tenure | -| subscription_renewed | Renewed | plan, value | -| billing_updated | Payment method changed | - | +| Event Name | Description | Properties | +| ----------------------- | ---------------------- | ------------------------- | +| trial_started | Trial began | plan, trial_length | +| trial_ended | Trial expired | plan, converted (bool) | +| subscription_upgraded | Plan upgraded | from_plan, to_plan, value | +| subscription_downgraded | Plan downgraded | from_plan, to_plan | +| subscription_cancelled | Cancelled | plan, reason, tenure | +| subscription_renewed | Renewed | plan, value | +| billing_updated | Payment method changed | - | --- @@ -108,41 +108,41 @@ Comprehensive list of events to track by business type and context. ### Browsing -| Event Name | Description | Properties | -|------------|-------------|------------| -| product_viewed | Product page viewed | product_id, product_name, category, price | -| product_list_viewed | Category/list viewed | list_name, products[] | -| product_searched | Search performed | query, results_count | -| product_filtered | Filters applied | filter_type, filter_value | -| product_sorted | Sort applied | sort_by, sort_order | +| Event Name | Description | Properties | +| ------------------- | -------------------- | ----------------------------------------- | +| product_viewed | Product page viewed | product_id, product_name, category, price | +| product_list_viewed | Category/list viewed | list_name, products[] | +| product_searched | Search performed | query, results_count | +| product_filtered | Filters applied | filter_type, filter_value | +| product_sorted | Sort applied | sort_by, sort_order | ### Cart -| Event Name | Description | Properties | -|------------|-------------|------------| -| product_added_to_cart | Item added | product_id, product_name, price, quantity | -| product_removed_from_cart | Item removed | product_id, product_name, price, quantity | -| cart_viewed | Cart page viewed | cart_value, items_count | +| Event Name | Description | Properties | +| ------------------------- | ---------------- | ----------------------------------------- | +| product_added_to_cart | Item added | product_id, product_name, price, quantity | +| product_removed_from_cart | Item removed | product_id, product_name, price, quantity | +| cart_viewed | Cart page viewed | cart_value, items_count | ### Checkout -| Event Name | Description | Properties | -|------------|-------------|------------| -| checkout_started | Checkout began | cart_value, items_count | -| checkout_step_completed | Step finished | step_number, step_name | -| shipping_info_entered | Address entered | shipping_method | -| payment_info_entered | Payment entered | payment_method | -| coupon_applied | Coupon used | coupon_code, discount_value | -| purchase_completed | Order placed | transaction_id, value, currency, items[] | +| Event Name | Description | Properties | +| ----------------------- | --------------- | ---------------------------------------- | +| checkout_started | Checkout began | cart_value, items_count | +| checkout_step_completed | Step finished | step_number, step_name | +| shipping_info_entered | Address entered | shipping_method | +| payment_info_entered | Payment entered | payment_method | +| coupon_applied | Coupon used | coupon_code, discount_value | +| purchase_completed | Order placed | transaction_id, value, currency, items[] | ### Post-Purchase -| Event Name | Description | Properties | -|------------|-------------|------------| -| order_confirmed | Confirmation viewed | transaction_id | -| refund_requested | Refund initiated | transaction_id, reason | -| refund_completed | Refund processed | transaction_id, value | -| review_submitted | Product reviewed | product_id, rating | +| Event Name | Description | Properties | +| ---------------- | ------------------- | ---------------------- | +| order_confirmed | Confirmation viewed | transaction_id | +| refund_requested | Refund initiated | transaction_id, reason | +| refund_completed | Refund processed | transaction_id, value | +| review_submitted | Product reviewed | product_id, rating | --- @@ -150,30 +150,30 @@ Comprehensive list of events to track by business type and context. ### Team & Collaboration -| Event Name | Description | Properties | -|------------|-------------|------------| -| team_created | New team/org made | team_size, plan | -| team_member_invited | Invite sent | role, invite_method | -| team_member_joined | Member accepted | role | -| team_member_removed | Member removed | role | -| role_changed | Permissions updated | user_id, old_role, new_role | +| Event Name | Description | Properties | +| ------------------- | ------------------- | --------------------------- | +| team_created | New team/org made | team_size, plan | +| team_member_invited | Invite sent | role, invite_method | +| team_member_joined | Member accepted | role | +| team_member_removed | Member removed | role | +| role_changed | Permissions updated | user_id, old_role, new_role | ### Integration Events -| Event Name | Description | Properties | -|------------|-------------|------------| -| integration_viewed | Integration page seen | integration_name | -| integration_started | Setup began | integration_name | -| integration_connected | Successfully connected | integration_name | -| integration_disconnected | Removed integration | integration_name, reason | +| Event Name | Description | Properties | +| ------------------------ | ---------------------- | ------------------------ | +| integration_viewed | Integration page seen | integration_name | +| integration_started | Setup began | integration_name | +| integration_connected | Successfully connected | integration_name | +| integration_disconnected | Removed integration | integration_name, reason | ### Account Events -| Event Name | Description | Properties | -|------------|-------------|------------| -| account_created | New account | source, plan | -| account_upgraded | Plan upgrade | from_plan, to_plan | -| account_churned | Account closed | reason, tenure, mrr_lost | +| Event Name | Description | Properties | +| ------------------- | ----------------- | ------------------------- | +| account_created | New account | source, plan | +| account_upgraded | Plan upgrade | from_plan, to_plan | +| account_churned | Account closed | reason, tenure, mrr_lost | | account_reactivated | Returned customer | previous_tenure, new_plan | --- @@ -183,6 +183,7 @@ Comprehensive list of events to track by business type and context. ### Standard Properties to Include **User Context:** + ``` user_id: "12345" user_type: "free" | "trial" | "paid" @@ -191,6 +192,7 @@ plan_type: "starter" | "pro" | "enterprise" ``` **Session Context:** + ``` session_id: "sess_abc" session_number: 5 @@ -199,6 +201,7 @@ referrer: "https://google.com" ``` **Campaign Context:** + ``` source: "google" medium: "cpc" @@ -207,6 +210,7 @@ content: "hero_cta" ``` **Product Context (E-commerce):** + ``` product_id: "SKU123" product_name: "Product Name" @@ -217,6 +221,7 @@ currency: "USD" ``` **Timing:** + ``` timestamp: "2024-01-15T10:30:00Z" time_on_page: 45 @@ -228,6 +233,7 @@ session_duration: 300 ## Funnel Event Sequences ### Signup Funnel + 1. signup_started 2. signup_step_completed (email) 3. signup_step_completed (password) @@ -235,6 +241,7 @@ session_duration: 300 5. onboarding_started ### Purchase Funnel + 1. pricing_viewed 2. plan_selected 3. checkout_started @@ -242,6 +249,7 @@ session_duration: 300 5. purchase_completed ### E-commerce Funnel + 1. product_viewed 2. product_added_to_cart 3. cart_viewed diff --git a/packages/mosaic/framework/skills/analytics-tracking/references/ga4-implementation.md b/packages/mosaic/framework/skills/analytics-tracking/references/ga4-implementation.md index 2cf874f8..b09b8425 100644 --- a/packages/mosaic/framework/skills/analytics-tracking/references/ga4-implementation.md +++ b/packages/mosaic/framework/skills/analytics-tracking/references/ga4-implementation.md @@ -13,25 +13,27 @@ Detailed implementation guide for Google Analytics 4. ### Enhanced Measurement Events (Automatic) -| Event | Description | Configuration | -|-------|-------------|---------------| -| page_view | Page loads | Automatic | -| scroll | 90% scroll depth | Toggle on/off | -| outbound_click | Click to external domain | Automatic | -| site_search | Search query used | Configure parameter | -| video_engagement | YouTube video plays | Toggle on/off | -| file_download | PDF, docs, etc. | Configurable extensions | +| Event | Description | Configuration | +| ---------------- | ------------------------ | ----------------------- | +| page_view | Page loads | Automatic | +| scroll | 90% scroll depth | Toggle on/off | +| outbound_click | Click to external domain | Automatic | +| site_search | Search query used | Configure parameter | +| video_engagement | YouTube video plays | Toggle on/off | +| file_download | PDF, docs, etc. | Configurable extensions | ### Recommended Events Use Google's predefined events when possible for enhanced reporting: **All properties:** + - login, sign_up - share - search **E-commerce:** + - view_item, view_item_list - add_to_cart, remove_from_cart - begin_checkout @@ -39,6 +41,7 @@ Use Google's predefined events when possible for enhanced reporting: - purchase, refund **Games:** + - level_up, unlock_achievement - post_score, spend_virtual_currency @@ -53,31 +56,33 @@ Reference: https://support.google.com/analytics/answer/9267735 ```javascript // Basic event gtag('event', 'signup_completed', { - 'method': 'email', - 'plan': 'free' + method: 'email', + plan: 'free', }); // Event with value gtag('event', 'purchase', { - 'transaction_id': 'T12345', - 'value': 99.99, - 'currency': 'USD', - 'items': [{ - 'item_id': 'SKU123', - 'item_name': 'Product Name', - 'price': 99.99 - }] + transaction_id: 'T12345', + value: 99.99, + currency: 'USD', + items: [ + { + item_id: 'SKU123', + item_name: 'Product Name', + price: 99.99, + }, + ], }); // User properties gtag('set', 'user_properties', { - 'user_type': 'premium', - 'plan_name': 'pro' + user_type: 'premium', + plan_name: 'pro', }); // User ID (for logged-in users) gtag('config', 'GA_MEASUREMENT_ID', { - 'user_id': 'USER_ID' + user_id: 'USER_ID', }); ``` @@ -86,40 +91,42 @@ gtag('config', 'GA_MEASUREMENT_ID', { ```javascript // Custom event dataLayer.push({ - 'event': 'signup_completed', - 'method': 'email', - 'plan': 'free' + event: 'signup_completed', + method: 'email', + plan: 'free', }); // Set user properties dataLayer.push({ - 'user_id': '12345', - 'user_type': 'premium' + user_id: '12345', + user_type: 'premium', }); // E-commerce purchase dataLayer.push({ - 'event': 'purchase', - 'ecommerce': { - 'transaction_id': 'T12345', - 'value': 99.99, - 'currency': 'USD', - 'items': [{ - 'item_id': 'SKU123', - 'item_name': 'Product Name', - 'price': 99.99, - 'quantity': 1 - }] - } + event: 'purchase', + ecommerce: { + transaction_id: 'T12345', + value: 99.99, + currency: 'USD', + items: [ + { + item_id: 'SKU123', + item_name: 'Product Name', + price: 99.99, + quantity: 1, + }, + ], + }, }); // Clear ecommerce before sending (best practice) dataLayer.push({ ecommerce: null }); dataLayer.push({ - 'event': 'view_item', - 'ecommerce': { + event: 'view_item', + ecommerce: { // ... - } + }, }); ``` @@ -141,8 +148,8 @@ dataLayer.push({ ```javascript // Event with conversion value gtag('event', 'purchase', { - 'value': 99.99, - 'currency': 'USD' + value: 99.99, + currency: 'USD', }); ``` @@ -155,11 +162,13 @@ Or set default value in GA4 Admin when marking conversion. ### When to Use **Custom dimensions:** + - Properties you want to segment/filter by - User attributes (plan type, industry) - Content attributes (author, category) **Custom metrics:** + - Numeric values to aggregate - Scores, counts, durations @@ -175,11 +184,11 @@ Or set default value in GA4 Admin when marking conversion. ### Examples -| Dimension | Scope | Parameter | Description | -|-----------|-------|-----------|-------------| -| User Type | User | user_type | Free, trial, paid | -| Content Author | Event | author | Blog post author | -| Product Category | Item | item_category | E-commerce category | +| Dimension | Scope | Parameter | Description | +| ---------------- | ----- | ------------- | ------------------- | +| User Type | User | user_type | Free, trial, paid | +| Content Author | Event | author | Blog post author | +| Product Category | Item | item_category | E-commerce category | --- @@ -190,6 +199,7 @@ Or set default value in GA4 Admin when marking conversion. Admin > Data display > Audiences **Use cases:** + - Remarketing audiences (export to Ads) - Segment analysis - Trigger-based events @@ -197,15 +207,18 @@ Admin > Data display > Audiences ### Audience Examples **High-intent visitors:** + - Viewed pricing page - Did not convert - In last 7 days **Engaged users:** + - 3+ sessions - Or 5+ minutes total engagement **Purchasers:** + - Purchase event - For exclusion or lookalike @@ -216,6 +229,7 @@ Admin > Data display > Audiences ### DebugView Enable with: + - URL parameter: `?debug_mode=true` - Chrome extension: GA Debugger - gtag: `'debug_mode': true` in config @@ -230,16 +244,19 @@ Reports > Real-time ### Common Issues **Events not appearing:** + - Check DebugView first - Verify gtag/GTM firing - Check filter exclusions **Parameter values missing:** + - Custom dimension not created - Parameter name mismatch - Data still processing (24-48 hrs) **Conversions not recording:** + - Event not marked as conversion - Event name doesn't match - Counting method (once vs. every) @@ -253,6 +270,7 @@ Reports > Real-time Admin > Data streams > [Stream] > Configure tag settings > Define internal traffic **Exclude:** + - Internal IP addresses - Developer traffic - Testing environments @@ -285,6 +303,7 @@ Admin > Data streams > [Stream] > Configure tag settings ### Audience Export Audiences created in GA4 can be used in Google Ads for: + - Remarketing campaigns - Customer match - Similar audiences diff --git a/packages/mosaic/framework/skills/analytics-tracking/references/gtm-implementation.md b/packages/mosaic/framework/skills/analytics-tracking/references/gtm-implementation.md index 914ada19..68847250 100644 --- a/packages/mosaic/framework/skills/analytics-tracking/references/gtm-implementation.md +++ b/packages/mosaic/framework/skills/analytics-tracking/references/gtm-implementation.md @@ -9,6 +9,7 @@ Detailed guide for implementing tracking via Google Tag Manager. Tags are code snippets that execute when triggered. **Common tag types:** + - GA4 Configuration (base setup) - GA4 Event (custom events) - Google Ads Conversion @@ -21,6 +22,7 @@ Tags are code snippets that execute when triggered. Triggers define when tags fire. **Built-in triggers:** + - Page View: All Pages, DOM Ready, Window Loaded - Click: All Elements, Just Links - Form Submission @@ -29,6 +31,7 @@ Triggers define when tags fire. - Element Visibility **Custom triggers:** + - Custom Event (from dataLayer) - Trigger Groups (multiple conditions) @@ -37,12 +40,14 @@ Triggers define when tags fire. Variables capture dynamic values. **Built-in (enable as needed):** + - Click Text, Click URL, Click ID, Click Classes - Page Path, Page URL, Page Hostname - Referrer - Form Element, Form ID **User-defined:** + - Data Layer variables - JavaScript variables - Lookup tables @@ -88,9 +93,9 @@ window.dataLayer = window.dataLayer || []; // Push event dataLayer.push({ - 'event': 'event_name', - 'property1': 'value1', - 'property2': 'value2' + event: 'event_name', + property1: 'value1', + property2: 'value2', }); ``` @@ -100,24 +105,24 @@ dataLayer.push({ // Set on page load (before GTM container) window.dataLayer = window.dataLayer || []; dataLayer.push({ - 'pageType': 'product', - 'contentGroup': 'products', - 'user': { - 'loggedIn': true, - 'userId': '12345', - 'userType': 'premium' - } + pageType: 'product', + contentGroup: 'products', + user: { + loggedIn: true, + userId: '12345', + userType: 'premium', + }, }); ``` ### Form Submission ```javascript -document.querySelector('#contact-form').addEventListener('submit', function() { +document.querySelector('#contact-form').addEventListener('submit', function () { dataLayer.push({ - 'event': 'form_submitted', - 'formName': 'contact', - 'formLocation': 'footer' + event: 'form_submitted', + formName: 'contact', + formLocation: 'footer', }); }); ``` @@ -125,11 +130,11 @@ document.querySelector('#contact-form').addEventListener('submit', function() { ### Button Click ```javascript -document.querySelector('.cta-button').addEventListener('click', function() { +document.querySelector('.cta-button').addEventListener('click', function () { dataLayer.push({ - 'event': 'cta_clicked', - 'ctaText': this.innerText, - 'ctaLocation': 'hero' + event: 'cta_clicked', + ctaText: this.innerText, + ctaLocation: 'hero', }); }); ``` @@ -140,49 +145,55 @@ document.querySelector('.cta-button').addEventListener('click', function() { // Product view dataLayer.push({ ecommerce: null }); // Clear previous dataLayer.push({ - 'event': 'view_item', - 'ecommerce': { - 'items': [{ - 'item_id': 'SKU123', - 'item_name': 'Product Name', - 'price': 99.99, - 'item_category': 'Category', - 'quantity': 1 - }] - } + event: 'view_item', + ecommerce: { + items: [ + { + item_id: 'SKU123', + item_name: 'Product Name', + price: 99.99, + item_category: 'Category', + quantity: 1, + }, + ], + }, }); // Add to cart dataLayer.push({ ecommerce: null }); dataLayer.push({ - 'event': 'add_to_cart', - 'ecommerce': { - 'items': [{ - 'item_id': 'SKU123', - 'item_name': 'Product Name', - 'price': 99.99, - 'quantity': 1 - }] - } + event: 'add_to_cart', + ecommerce: { + items: [ + { + item_id: 'SKU123', + item_name: 'Product Name', + price: 99.99, + quantity: 1, + }, + ], + }, }); // Purchase dataLayer.push({ ecommerce: null }); dataLayer.push({ - 'event': 'purchase', - 'ecommerce': { - 'transaction_id': 'T12345', - 'value': 99.99, - 'currency': 'USD', - 'tax': 5.00, - 'shipping': 10.00, - 'items': [{ - 'item_id': 'SKU123', - 'item_name': 'Product Name', - 'price': 99.99, - 'quantity': 1 - }] - } + event: 'purchase', + ecommerce: { + transaction_id: 'T12345', + value: 99.99, + currency: 'USD', + tax: 5.0, + shipping: 10.0, + items: [ + { + item_id: 'SKU123', + item_name: 'Product Name', + price: 99.99, + quantity: 1, + }, + ], + }, }); ``` @@ -195,6 +206,7 @@ dataLayer.push({ **Tag Type:** Google Analytics: GA4 Configuration **Settings:** + - Measurement ID: G-XXXXXXXX - Send page view: Checked (for pageviews) - User Properties: Add any user-level dimensions @@ -206,6 +218,7 @@ dataLayer.push({ **Tag Type:** Google Analytics: GA4 Event **Settings:** + - Configuration Tag: Select your config tag - Event Name: {{DL - event_name}} or hardcode - Event Parameters: Add parameters from dataLayer @@ -218,14 +231,22 @@ dataLayer.push({ ```html @@ -240,7 +261,7 @@ dataLayer.push({ ```html ``` @@ -258,6 +279,7 @@ dataLayer.push({ 3. GTM debug panel opens at bottom **What to check:** + - Tags fired on this event - Tags not fired (and why) - Variables and their values @@ -266,16 +288,19 @@ dataLayer.push({ ### Debug Tips **Tag not firing:** + - Check trigger conditions - Verify data layer push - Check tag sequencing **Wrong variable value:** + - Check data layer structure - Verify variable path (nested objects) - Check timing (data may not exist yet) **Multiple firings:** + - Check trigger uniqueness - Look for duplicate tags - Check tag firing options @@ -287,6 +312,7 @@ dataLayer.push({ ### Workspaces Use workspaces for team collaboration: + - Default workspace for production - Separate workspaces for large changes - Merge when ready @@ -294,12 +320,14 @@ Use workspaces for team collaboration: ### Version Management **Best practices:** + - Name every version descriptively - Add notes explaining changes - Review changes before publish - Keep production version noted **Version notes example:** + ``` v15: Added purchase conversion tracking - New tag: GA4 - Event - Purchase @@ -317,15 +345,15 @@ v15: Added purchase conversion tracking ```javascript // Default state (before consent) gtag('consent', 'default', { - 'analytics_storage': 'denied', - 'ad_storage': 'denied' + analytics_storage: 'denied', + ad_storage: 'denied', }); // Update on consent function grantConsent() { gtag('consent', 'update', { - 'analytics_storage': 'granted', - 'ad_storage': 'granted' + analytics_storage: 'granted', + ad_storage: 'granted', }); } ``` @@ -346,6 +374,7 @@ function grantConsent() { Tag Configuration > Advanced Settings > Tag Sequencing **Use cases:** + - Config tag before event tags - Pixel initialization before tracking - Cleanup after conversion @@ -353,6 +382,7 @@ Tag Configuration > Advanced Settings > Tag Sequencing ### Exception Handling **Trigger exceptions** - Prevent tag from firing: + - Exclude certain pages - Exclude internal traffic - Exclude during testing diff --git a/packages/mosaic/framework/skills/antfu/SKILL.md b/packages/mosaic/framework/skills/antfu/SKILL.md index efefbc99..f5950e3e 100644 --- a/packages/mosaic/framework/skills/antfu/SKILL.md +++ b/packages/mosaic/framework/skills/antfu/SKILL.md @@ -3,7 +3,7 @@ name: antfu description: Anthony Fu's opinionated tooling and conventions for JavaScript/TypeScript projects. Use when setting up new projects, configuring ESLint/Prettier alternatives, monorepos, library publishing, or when the user mentions Anthony Fu's preferences. metadata: author: Anthony Fu - version: "2026.02.03" + version: '2026.02.03' --- ## Coding Practices @@ -48,15 +48,15 @@ metadata: ### @antfu/ni Commands -| Command | Description | -|---------|-------------| -| `ni` | Install dependencies | -| `ni ` / `ni -D ` | Add dependency / dev dependency | -| `nr ``` ### Props 响应性传递 + ```vue ``` ### Computed 副作用 + ```vue ``` ### 模板常见错误 + ```vue