chore: import upstream snapshot with attribution
Lint skills / Validate catalog structure (push) Has been cancelled
Lint skills / Validate catalog structure (push) Has been cancelled
This commit is contained in:
wehub-resource-sync
@@ -0,0 +1,35 @@
|
||||
{
|
||||
"name": "rampstack",
|
||||
"owner": { "name": "RampStack" },
|
||||
"description": "RampStack Claude Skills: the website lifecycle as installable skills.",
|
||||
"plugins": [
|
||||
{
|
||||
"name": "rampstack-skills",
|
||||
"source": "./",
|
||||
"description": "Full catalog of website-lifecycle skills: research, brand, build, and audit.",
|
||||
"category": "web-development",
|
||||
"keywords": ["agent-skills", "seo", "brand", "web-development"]
|
||||
},
|
||||
{
|
||||
"name": "rampstack-starter",
|
||||
"source": { "source": "github", "repo": "rampstackco/claude-skills-starter" },
|
||||
"description": "Curated starter subset of the RampStack catalog: a general-purpose skill set for the website lifecycle.",
|
||||
"category": "web-development",
|
||||
"keywords": ["agent-skills", "starter", "web-development"]
|
||||
},
|
||||
{
|
||||
"name": "rampstack-seo",
|
||||
"source": { "source": "github", "repo": "rampstackco/claude-skills-seo" },
|
||||
"description": "Focused SEO skills: keyword research, on-page and technical audits, AI-search optimization, traffic diagnosis, site-health triage, competitor and content audits, and programmatic SEO, with content companions.",
|
||||
"category": "web-development",
|
||||
"keywords": ["agent-skills", "seo", "aeo", "geo"]
|
||||
},
|
||||
{
|
||||
"name": "rampstack-pm",
|
||||
"source": { "source": "github", "repo": "rampstackco/claude-skills-pm" },
|
||||
"description": "Focused product management skills across the lifecycle: discovery, roadmaps and OKRs, PRDs, stakeholder communication, launch and beta programs, and measurement.",
|
||||
"category": "productivity",
|
||||
"keywords": ["agent-skills", "product-management", "roadmap", "okr"]
|
||||
}
|
||||
]
|
||||
}
|
||||
@@ -0,0 +1,10 @@
|
||||
{
|
||||
"name": "rampstack-skills",
|
||||
"description": "Full RampStack catalog of website-lifecycle skills across research, brand, build, and audit.",
|
||||
"version": "1.2.0",
|
||||
"author": { "name": "RampStack" },
|
||||
"homepage": "https://rampstack.co",
|
||||
"repository": "https://github.com/rampstackco/claude-skills",
|
||||
"license": "MIT",
|
||||
"keywords": ["agent-skills", "claude-skills", "seo", "brand", "web-development", "product-management"]
|
||||
}
|
||||
@@ -0,0 +1,95 @@
|
||||
name: Bug report
|
||||
description: Report a bug, broken link, broken trigger, or content error in a skill or reference file.
|
||||
title: "[Bug]: <short description>"
|
||||
labels: ["bug", "needs-triage"]
|
||||
body:
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
Thanks for reporting a bug. Please fill in as much detail as you can.
|
||||
|
||||
**Not a bug?** Use these instead:
|
||||
- General questions or proposals: [Discussions](https://github.com/rampstackco/claude-skills/discussions)
|
||||
- Security issues: see [SECURITY.md](../blob/main/SECURITY.md)
|
||||
- Improvement to a reference file: use the "Improve a reference file" template
|
||||
|
||||
- type: input
|
||||
id: skill
|
||||
attributes:
|
||||
label: Skill affected
|
||||
description: Which skill is the bug in? Use the skill folder name. If the bug is in the README, CONTRIBUTING.md, or another root doc, name that file instead.
|
||||
placeholder: seo-traffic-diagnosis
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: input
|
||||
id: file
|
||||
attributes:
|
||||
label: Specific file (if applicable)
|
||||
description: If the bug is in a specific reference file, name it.
|
||||
placeholder: references/diagnosis-checklist.md
|
||||
|
||||
- type: dropdown
|
||||
id: bug-type
|
||||
attributes:
|
||||
label: Type of bug
|
||||
options:
|
||||
- "Broken link (internal cross-reference or external URL)"
|
||||
- "Trigger doesn't fire when it should"
|
||||
- "Trigger fires when it shouldn't (false positive)"
|
||||
- "Factual error in content"
|
||||
- "Em dash or formatting violation"
|
||||
- "Em dash in catalog count or stats"
|
||||
- "Skill output doesn't match documented format"
|
||||
- "Cross-skill reference points to non-existent skill"
|
||||
- "YAML frontmatter parse error"
|
||||
- "Other"
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: description
|
||||
attributes:
|
||||
label: Description
|
||||
description: What is the bug? Be specific.
|
||||
placeholder: |
|
||||
The skill `seo-traffic-diagnosis` references `references/diagnoses-checklist.md` (typo) but the actual file is `references/diagnosis-checklist.md`.
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: expected
|
||||
attributes:
|
||||
label: Expected behavior
|
||||
description: What should happen instead?
|
||||
placeholder: |
|
||||
The Reference files section in SKILL.md should match the actual filename in the references/ folder.
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: reproduce
|
||||
attributes:
|
||||
label: Steps to reproduce
|
||||
description: How did you find this? If applicable, include the exact prompt that triggered the wrong behavior.
|
||||
placeholder: |
|
||||
1. Opened `skills/seo-traffic-diagnosis/SKILL.md`
|
||||
2. Searched for "diagnoses" (typo) and "diagnosis"
|
||||
3. Found mismatch between the SKILL.md text and the actual file in references/
|
||||
|
||||
- type: textarea
|
||||
id: context
|
||||
attributes:
|
||||
label: Additional context
|
||||
description: Anything else worth knowing? Screenshots welcome.
|
||||
|
||||
- type: dropdown
|
||||
id: willingness
|
||||
attributes:
|
||||
label: Are you willing to submit a fix?
|
||||
options:
|
||||
- "Yes, I will draft a PR"
|
||||
- "Maybe, depending on complexity"
|
||||
- "No, just reporting"
|
||||
validations:
|
||||
required: true
|
||||
@@ -0,0 +1,11 @@
|
||||
blank_issues_enabled: false
|
||||
contact_links:
|
||||
- name: Question or proposal
|
||||
url: https://github.com/rampstackco/claude-skills/discussions
|
||||
about: For general questions, design discussions, or proposals, please open a Discussion instead of an Issue.
|
||||
- name: Security issue
|
||||
url: https://github.com/rampstackco/claude-skills/security/advisories/new
|
||||
about: Report security vulnerabilities privately via GitHub Security Advisories. See SECURITY.md for the full policy.
|
||||
- name: Documentation
|
||||
url: https://github.com/rampstackco/claude-skills/blob/main/SKILL_AUTHORING.md
|
||||
about: Read SKILL_AUTHORING.md and CONTRIBUTING.md before opening a new-skill issue.
|
||||
@@ -0,0 +1,104 @@
|
||||
name: Improve a reference file
|
||||
description: Suggest an improvement to a reference file (template, checklist, decision matrix, worked example).
|
||||
title: "[Improve]: <skill-name> / <reference-file-name>"
|
||||
labels: ["improvement", "needs-triage"]
|
||||
body:
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
Thanks for suggesting an improvement. Reference files are the deep-dive material that go beyond what fits in a SKILL.md. They get better with every well-shaped contribution.
|
||||
|
||||
Before filling this out, please confirm:
|
||||
- You have read the existing reference file end to end
|
||||
- You have read [CONTRIBUTING.md](../blob/main/CONTRIBUTING.md)
|
||||
- The improvement does not belong in the SKILL.md instead
|
||||
|
||||
- type: input
|
||||
id: skill
|
||||
attributes:
|
||||
label: Skill
|
||||
description: Which skill folder does the reference file belong to?
|
||||
placeholder: seo-keyword-gap-audit
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: input
|
||||
id: reference-file
|
||||
attributes:
|
||||
label: Reference file
|
||||
description: Which file in the references/ folder are you improving?
|
||||
placeholder: references/opportunity-scoring-rubric.md
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: dropdown
|
||||
id: improvement-type
|
||||
attributes:
|
||||
label: Type of improvement
|
||||
options:
|
||||
- "Add a worked example"
|
||||
- "Add a missing edge case"
|
||||
- "Update outdated guidance"
|
||||
- "Improve a template or checklist"
|
||||
- "Add a missing reference (table, formula, decision tree)"
|
||||
- "Fix factual error"
|
||||
- "Improve clarity or structure"
|
||||
- "Other"
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: gap
|
||||
attributes:
|
||||
label: What is missing or wrong?
|
||||
description: Describe the gap specifically. Quote the existing text if you can.
|
||||
placeholder: |
|
||||
The opportunity-scoring-rubric.md does not cover [specific scenario]. The current scoring formula assumes [assumption], but this breaks down when [edge case].
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: proposal
|
||||
attributes:
|
||||
label: Proposed change
|
||||
description: |
|
||||
Sketch the addition or change. Doesn't have to be final wording, but should be specific enough to evaluate.
|
||||
placeholder: |
|
||||
Add a section "Adjusting weights for goal" with three preset weight configurations:
|
||||
- Quick wins focus
|
||||
- Strategic territory focus
|
||||
- Defensive (protect rankings)
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: justification
|
||||
attributes:
|
||||
label: Why does this earn its place?
|
||||
description: |
|
||||
Reference files should go deeper than the SKILL.md, not duplicate it, and should be useful in real work.
|
||||
placeholder: |
|
||||
Without this, users running an audit on a low-DR site cannot calibrate the rubric correctly and the priority list mis-ranks. I have hit this in two real audits.
|
||||
|
||||
- type: dropdown
|
||||
id: willingness
|
||||
attributes:
|
||||
label: Are you willing to draft the change?
|
||||
options:
|
||||
- "Yes, I will draft a PR"
|
||||
- "I can collaborate on a PR"
|
||||
- "I am only suggesting, not authoring"
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: checkboxes
|
||||
id: terms
|
||||
attributes:
|
||||
label: Confirmation
|
||||
options:
|
||||
- label: I have read the existing reference file end to end
|
||||
required: true
|
||||
- label: I confirmed this content does not belong in the SKILL.md instead
|
||||
required: true
|
||||
- label: I have read [CONTRIBUTING.md](../blob/main/CONTRIBUTING.md)
|
||||
required: true
|
||||
@@ -0,0 +1,113 @@
|
||||
name: Propose a new skill
|
||||
description: Suggest a new skill for the library. Read CONTRIBUTING.md first.
|
||||
title: "[New skill]: <proposed-skill-name>"
|
||||
labels: ["new-skill", "needs-triage"]
|
||||
body:
|
||||
- type: markdown
|
||||
attributes:
|
||||
value: |
|
||||
Thanks for proposing a new skill. Before filling this out, please confirm:
|
||||
- You have read [CONTRIBUTING.md](../blob/main/CONTRIBUTING.md) and [SKILL_AUTHORING.md](../blob/main/SKILL_AUTHORING.md)
|
||||
- You have searched the [existing skills](../tree/main/skills) and confirmed this gap is real
|
||||
- The proposed skill is stack-agnostic (or has a strong reason to be tool-bound)
|
||||
|
||||
- type: input
|
||||
id: proposed-name
|
||||
attributes:
|
||||
label: Proposed skill name
|
||||
description: Use lowercase-hyphenated format. Example: `seo-rank-tracking`
|
||||
placeholder: my-new-skill
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: description
|
||||
attributes:
|
||||
label: Draft description (frontmatter)
|
||||
description: |
|
||||
2-4 sentences. Should include:
|
||||
- One sentence: what the skill does
|
||||
- One sentence: situations where it should fire
|
||||
- Trigger words and phrases
|
||||
- An "Also triggers when..." edge case line
|
||||
placeholder: |
|
||||
Audits X for Y using Z. Use this skill when [specific situation], scoping a [related task], or [another situation]. Triggers on [phrase 1], [phrase 2], [phrase 3]. Also triggers when [edge case].
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: gap
|
||||
attributes:
|
||||
label: Why existing skills don't cover this
|
||||
description: Name the closest existing skills and explain why they fall short for this use case.
|
||||
placeholder: |
|
||||
- `existing-skill-a` covers part of this but stops at...
|
||||
- `existing-skill-b` is adjacent but focuses on...
|
||||
- There is no skill that handles [specific need].
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: triggers
|
||||
attributes:
|
||||
label: Example user prompts that should trigger this skill
|
||||
description: List 3-5 realistic prompts a user would type that should fire this skill.
|
||||
placeholder: |
|
||||
- "Help me audit X for Y"
|
||||
- "Why is Z happening to my A"
|
||||
- "Compare B options across C"
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: framework
|
||||
attributes:
|
||||
label: The framework
|
||||
description: |
|
||||
What is the durable insight the skill teaches? 1-3 sentences. If you cannot articulate this, the skill is not yet ready.
|
||||
placeholder: |
|
||||
There are N categories of X, and they each need different treatment. Phase 1 is..., phase 2 is..., phase 3 is...
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: textarea
|
||||
id: references
|
||||
attributes:
|
||||
label: Reference files
|
||||
description: What templates, checklists, or worked examples will live in `references/`?
|
||||
placeholder: |
|
||||
- `template.md` - Blank template for the deliverable
|
||||
- `checklist.md` - Pre-flight checklist
|
||||
- `example.md` - Worked example for [scenario]
|
||||
|
||||
- type: textarea
|
||||
id: pairs-with
|
||||
attributes:
|
||||
label: Pairs with which existing skills?
|
||||
description: Which sibling skills will this cross-reference in "When NOT to use" or workflow sections?
|
||||
placeholder: |
|
||||
- `skill-a` - for adjacent task X
|
||||
- `skill-b` - for downstream task Y
|
||||
|
||||
- type: dropdown
|
||||
id: willingness
|
||||
attributes:
|
||||
label: Are you willing to author the skill?
|
||||
options:
|
||||
- "Yes, I will draft a PR"
|
||||
- "I can collaborate on a PR"
|
||||
- "I am only proposing, not authoring"
|
||||
validations:
|
||||
required: true
|
||||
|
||||
- type: checkboxes
|
||||
id: terms
|
||||
attributes:
|
||||
label: Confirmation
|
||||
options:
|
||||
- label: I have read [CONTRIBUTING.md](../blob/main/CONTRIBUTING.md) and [SKILL_AUTHORING.md](../blob/main/SKILL_AUTHORING.md)
|
||||
required: true
|
||||
- label: I confirmed this skill is not duplicating an existing one
|
||||
required: true
|
||||
- label: I understand the proposal may be declined if the gap is not real or the framework is not durable
|
||||
required: true
|
||||
@@ -0,0 +1,73 @@
|
||||
<!-- Thanks for opening a PR. Please fill in the sections below. -->
|
||||
|
||||
## What this PR does
|
||||
|
||||
<!-- One paragraph. What is the change and why? -->
|
||||
|
||||
## Type of change
|
||||
|
||||
<!-- Check the one that applies. -->
|
||||
|
||||
- [ ] New skill (adds a folder under `skills/`)
|
||||
- [ ] Update to an existing skill (`SKILL.md` body or frontmatter)
|
||||
- [ ] Update to a reference file
|
||||
- [ ] Bug fix (broken link, typo, formatting violation, etc.)
|
||||
- [ ] Documentation (README, CONTRIBUTING, SKILL_AUTHORING, MAPPING, CHANGELOG)
|
||||
- [ ] Tooling or CI
|
||||
|
||||
## Linked issue
|
||||
|
||||
<!-- Link the issue this PR addresses. New skills should always have an issue first. -->
|
||||
|
||||
Closes #
|
||||
|
||||
---
|
||||
|
||||
## Contributor checklist
|
||||
|
||||
<!-- Confirm each item before requesting review. Some items only apply to certain change types. -->
|
||||
|
||||
### For all changes
|
||||
|
||||
- [ ] I have read [CONTRIBUTING.md](../blob/main/CONTRIBUTING.md)
|
||||
- [ ] No em dashes anywhere in the changed files (search for U+2014)
|
||||
- [ ] No private brand, personal handle, or proprietary domain references
|
||||
- [ ] Internal links resolve to real files
|
||||
- [ ] Cross-references to sibling skills name skills that actually exist
|
||||
- [ ] PR title follows the format: `Add: <name>` / `Fix: <description>` / `Improve: <skill> reference` / `Update: <doc>`
|
||||
|
||||
### If adding a new skill
|
||||
|
||||
- [ ] Skill folder name is `lowercase-hyphenated`
|
||||
- [ ] `SKILL.md` exists with valid YAML frontmatter
|
||||
- [ ] `name` in frontmatter matches the folder name exactly
|
||||
- [ ] `description` is 2-4 sentences with explicit triggers and an "Also triggers when..." line
|
||||
- [ ] All 10 sections are present in the documented order (When to use, When NOT to use, Required inputs, The framework, Workflow, Failure patterns, Output format, Reference files)
|
||||
- [ ] At least one reference file exists in `references/`
|
||||
- [ ] `Reference files` section in SKILL.md matches the actual files in `references/`
|
||||
- [ ] No vendor-specific framework references in the SKILL.md body
|
||||
- [ ] No version-specific references (e.g., "Tailwind 4", "Next.js 15") in the SKILL.md body
|
||||
- [ ] `SKILL.md` is under 250 lines (hard cap 500)
|
||||
- [ ] Each reference file is under 400 lines
|
||||
- [ ] I added the new skill to the catalog table in `README.md`
|
||||
- [ ] I added an entry to `CHANGELOG.md` under `[Unreleased]`
|
||||
- [ ] I ran a quick check for trigger collisions with existing skills
|
||||
|
||||
### If modifying an existing skill
|
||||
|
||||
- [ ] Changes preserve the uniform section order
|
||||
- [ ] If renaming files, all references in SKILL.md are updated
|
||||
- [ ] If renaming the skill, all cross-references in other SKILL.md files are updated
|
||||
- [ ] I added an entry to `CHANGELOG.md` under `[Unreleased]` if the change is user-visible
|
||||
|
||||
### If fixing a bug
|
||||
|
||||
- [ ] I described the bug in the linked issue or in this PR
|
||||
- [ ] I verified the fix actually resolves the problem
|
||||
- [ ] I checked for the same bug pattern elsewhere in the repo
|
||||
|
||||
---
|
||||
|
||||
## Notes for the reviewer
|
||||
|
||||
<!-- Anything that does not fit above. Trade-offs you considered. Things you are unsure about. -->
|
||||
@@ -0,0 +1,22 @@
|
||||
# Dependabot configuration
|
||||
# https://docs.github.com/en/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file
|
||||
|
||||
version: 2
|
||||
updates:
|
||||
# Keep GitHub Actions versions current. The repo's lint workflow uses
|
||||
# actions/checkout and actions/setup-python; when a new major version
|
||||
# ships, Dependabot opens a PR with release notes attached.
|
||||
- package-ecosystem: "github-actions"
|
||||
directory: "/"
|
||||
schedule:
|
||||
interval: "weekly"
|
||||
day: "monday"
|
||||
time: "09:00"
|
||||
timezone: "America/Denver"
|
||||
open-pull-requests-limit: 5
|
||||
commit-message:
|
||||
prefix: "ci"
|
||||
include: "scope"
|
||||
labels:
|
||||
- "dependencies"
|
||||
- "github-actions"
|
||||
@@ -0,0 +1,471 @@
|
||||
#!/usr/bin/env python3
|
||||
"""
|
||||
Lint script for the Brand Build Skills catalog.
|
||||
|
||||
Validates structural conventions documented in SKILL_AUTHORING.md and CONTRIBUTING.md.
|
||||
Run from the repo root via `python .github/scripts/lint_skills.py`.
|
||||
|
||||
Exit codes:
|
||||
0 All checks passed.
|
||||
1 One or more checks failed.
|
||||
|
||||
Designed to be:
|
||||
- Stdlib-only except for PyYAML (frontmatter parsing).
|
||||
- Loud about failures, quiet about passes.
|
||||
- Easy to extend: each check is a function appended to CHECKS.
|
||||
"""
|
||||
|
||||
from __future__ import annotations
|
||||
|
||||
import re
|
||||
import sys
|
||||
from dataclasses import dataclass, field
|
||||
from pathlib import Path
|
||||
from typing import Callable, Iterable
|
||||
|
||||
try:
|
||||
import yaml
|
||||
except ImportError:
|
||||
print("ERROR: PyYAML is required. Install with: pip install pyyaml", file=sys.stderr)
|
||||
sys.exit(1)
|
||||
|
||||
|
||||
REPO_ROOT = Path(__file__).resolve().parents[2]
|
||||
SKILLS_DIR = REPO_ROOT / "skills"
|
||||
README = REPO_ROOT / "README.md"
|
||||
|
||||
# Brand watchlist. Any case-insensitive hit fails the build, except for the
|
||||
# explicitly-allowed legitimate public references in ALLOWED_BRAND_CONTEXTS.
|
||||
BRAND_WATCHLIST = [
|
||||
"adunn08",
|
||||
"GameDesk",
|
||||
"ANDY.md",
|
||||
"bankranked",
|
||||
"wirly",
|
||||
"vehiclemd",
|
||||
"carcabin",
|
||||
"codeblu",
|
||||
"stayrentals",
|
||||
"insurrates",
|
||||
"mycarneedsthis",
|
||||
"tereks",
|
||||
"checkvin",
|
||||
"credit-factor",
|
||||
"straightstocks",
|
||||
"econgrader",
|
||||
"degreemath",
|
||||
"taxgrader",
|
||||
"retiregrader",
|
||||
"smallbizgrader",
|
||||
"bankscored",
|
||||
"401klens",
|
||||
"diplomavalue",
|
||||
"degreegrade",
|
||||
"studentdebtmath",
|
||||
"nesteggnerd",
|
||||
"bizmoneymath",
|
||||
"retireranked",
|
||||
"taxscoped",
|
||||
]
|
||||
|
||||
# `rampstack` requires special handling: legitimate as the public org name
|
||||
# `rampstackco` and the public domain `rampstack.co`, never as `rampstack`
|
||||
# in isolation. The check enforces this with a regex below.
|
||||
|
||||
SKILL_MD_LINE_LIMIT = 500 # Hard cap; warns above 400.
|
||||
SKILL_MD_LINE_TARGET = 400
|
||||
REFERENCE_LINE_LIMIT = 500
|
||||
|
||||
|
||||
@dataclass
|
||||
class LintResult:
|
||||
errors: list[str] = field(default_factory=list)
|
||||
warnings: list[str] = field(default_factory=list)
|
||||
|
||||
def fail(self, message: str) -> None:
|
||||
self.errors.append(message)
|
||||
|
||||
def warn(self, message: str) -> None:
|
||||
self.warnings.append(message)
|
||||
|
||||
def merge(self, other: "LintResult") -> None:
|
||||
self.errors.extend(other.errors)
|
||||
self.warnings.extend(other.warnings)
|
||||
|
||||
@property
|
||||
def ok(self) -> bool:
|
||||
return not self.errors
|
||||
|
||||
|
||||
def list_skill_dirs() -> list[Path]:
|
||||
return sorted(p for p in SKILLS_DIR.iterdir() if p.is_dir())
|
||||
|
||||
|
||||
def read_text(path: Path) -> str:
|
||||
return path.read_text(encoding="utf-8")
|
||||
|
||||
|
||||
def parse_frontmatter(skill_md: Path) -> tuple[dict, str]:
|
||||
"""Return (frontmatter_dict, body_text) or raise ValueError on malformed YAML."""
|
||||
text = read_text(skill_md)
|
||||
match = re.match(r"^---\s*\n(.*?)\n---\s*\n(.*)$", text, re.DOTALL)
|
||||
if not match:
|
||||
raise ValueError("No YAML frontmatter delimited by --- markers")
|
||||
frontmatter_text, body = match.group(1), match.group(2)
|
||||
try:
|
||||
data = yaml.safe_load(frontmatter_text)
|
||||
except yaml.YAMLError as exc:
|
||||
raise ValueError(f"YAML parse error: {exc}")
|
||||
if not isinstance(data, dict):
|
||||
raise ValueError("Frontmatter is not a dict")
|
||||
return data, body
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Checks
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
def check_em_dashes(result: LintResult) -> None:
|
||||
"""Em dashes are forbidden anywhere in tracked Markdown."""
|
||||
for md in REPO_ROOT.rglob("*.md"):
|
||||
# Skip git internal and node_modules if any.
|
||||
if any(part in (".git", "node_modules") for part in md.parts):
|
||||
continue
|
||||
text = read_text(md)
|
||||
if "\u2014" in text:
|
||||
for i, line in enumerate(text.splitlines(), start=1):
|
||||
if "\u2014" in line:
|
||||
result.fail(
|
||||
f"Em dash found in {md.relative_to(REPO_ROOT)}:{i}"
|
||||
)
|
||||
|
||||
|
||||
def check_brand_leaks(result: LintResult) -> None:
|
||||
"""Forbidden brand mentions from the watchlist."""
|
||||
for md in REPO_ROOT.rglob("*.md"):
|
||||
if any(part in (".git", "node_modules") for part in md.parts):
|
||||
continue
|
||||
text = read_text(md)
|
||||
|
||||
text_lower = text.lower()
|
||||
for needle in BRAND_WATCHLIST:
|
||||
if needle.lower() in text_lower:
|
||||
result.fail(
|
||||
f"Brand watchlist hit '{needle}' in {md.relative_to(REPO_ROOT)}"
|
||||
)
|
||||
|
||||
|
||||
def check_frontmatter_and_name_match(result: LintResult) -> None:
|
||||
"""Every SKILL.md must have valid frontmatter; name must match folder name."""
|
||||
for skill_dir in list_skill_dirs():
|
||||
skill_md = skill_dir / "SKILL.md"
|
||||
if not skill_md.exists():
|
||||
result.fail(f"Missing SKILL.md in {skill_dir.relative_to(REPO_ROOT)}")
|
||||
continue
|
||||
try:
|
||||
fm, _ = parse_frontmatter(skill_md)
|
||||
except ValueError as exc:
|
||||
result.fail(f"{skill_md.relative_to(REPO_ROOT)}: {exc}")
|
||||
continue
|
||||
name = fm.get("name")
|
||||
description = fm.get("description")
|
||||
if not name:
|
||||
result.fail(f"{skill_md.relative_to(REPO_ROOT)}: missing 'name' in frontmatter")
|
||||
elif name != skill_dir.name:
|
||||
result.fail(
|
||||
f"{skill_md.relative_to(REPO_ROOT)}: frontmatter name '{name}' "
|
||||
f"does not match folder name '{skill_dir.name}'"
|
||||
)
|
||||
if not description:
|
||||
result.fail(f"{skill_md.relative_to(REPO_ROOT)}: missing 'description' in frontmatter")
|
||||
elif len(description.strip()) < 80:
|
||||
result.warn(
|
||||
f"{skill_md.relative_to(REPO_ROOT)}: description is short "
|
||||
f"({len(description.strip())} chars); aim for 2-4 sentences"
|
||||
)
|
||||
|
||||
|
||||
def check_framework_section(result: LintResult) -> None:
|
||||
"""Every SKILL.md must contain a section starting with `## The framework`."""
|
||||
pattern = re.compile(r"^## The framework(:|\s|$)", re.MULTILINE)
|
||||
for skill_dir in list_skill_dirs():
|
||||
skill_md = skill_dir / "SKILL.md"
|
||||
if not skill_md.exists():
|
||||
continue
|
||||
text = read_text(skill_md)
|
||||
if not pattern.search(text):
|
||||
result.fail(
|
||||
f"{skill_md.relative_to(REPO_ROOT)}: missing '## The framework' "
|
||||
f"section (canonical text is required; descriptive colon-suffix is allowed)"
|
||||
)
|
||||
|
||||
|
||||
def extract_reference_section(text: str) -> str | None:
|
||||
"""Extract the body text under the actual `## Reference files` heading.
|
||||
|
||||
Skips matches inside fenced code blocks. Uses the last canonical occurrence
|
||||
in case the heading is also referenced inside a code-block template.
|
||||
Returns None if the section is not found.
|
||||
"""
|
||||
lines = text.splitlines()
|
||||
in_code_fence = False
|
||||
section_starts: list[int] = []
|
||||
|
||||
for i, line in enumerate(lines):
|
||||
stripped = line.strip()
|
||||
if stripped.startswith("```"):
|
||||
in_code_fence = not in_code_fence
|
||||
continue
|
||||
if not in_code_fence and stripped == "## Reference files":
|
||||
section_starts.append(i)
|
||||
|
||||
if not section_starts:
|
||||
return None
|
||||
|
||||
start = section_starts[-1]
|
||||
|
||||
in_code_fence = False
|
||||
section_lines: list[str] = []
|
||||
for i in range(start + 1, len(lines)):
|
||||
line = lines[i]
|
||||
stripped = line.strip()
|
||||
if stripped.startswith("```"):
|
||||
in_code_fence = not in_code_fence
|
||||
section_lines.append(line)
|
||||
continue
|
||||
if not in_code_fence and stripped.startswith("## "):
|
||||
break
|
||||
section_lines.append(line)
|
||||
|
||||
return "\n".join(section_lines)
|
||||
|
||||
|
||||
def check_reference_files_match(result: LintResult) -> None:
|
||||
"""SKILL.md 'Reference files' list must match actual files in references/.
|
||||
|
||||
Only the `## Reference files` section is parsed. References mentioned
|
||||
elsewhere (e.g., naming-convention examples in the body, or the canonical
|
||||
skill template inside a code block) are ignored.
|
||||
"""
|
||||
ref_pattern = re.compile(r"`references/([^`]+)`")
|
||||
|
||||
for skill_dir in list_skill_dirs():
|
||||
skill_md = skill_dir / "SKILL.md"
|
||||
ref_dir = skill_dir / "references"
|
||||
if not skill_md.exists():
|
||||
continue
|
||||
|
||||
text = read_text(skill_md)
|
||||
section_text = extract_reference_section(text)
|
||||
if section_text is None:
|
||||
result.fail(
|
||||
f"{skill_md.relative_to(REPO_ROOT)}: missing '## Reference files' section"
|
||||
)
|
||||
continue
|
||||
cited_refs = set(ref_pattern.findall(section_text))
|
||||
|
||||
actual_refs = set()
|
||||
if ref_dir.exists():
|
||||
actual_refs = {p.name for p in ref_dir.iterdir() if p.is_file()}
|
||||
|
||||
missing = cited_refs - actual_refs
|
||||
orphan = actual_refs - cited_refs
|
||||
|
||||
rel = skill_md.relative_to(REPO_ROOT)
|
||||
for name in sorted(missing):
|
||||
result.fail(f"{rel}: cites references/{name} but file does not exist")
|
||||
for name in sorted(orphan):
|
||||
result.fail(
|
||||
f"{skill_dir.relative_to(REPO_ROOT)}/references/{name}: "
|
||||
f"orphan file not cited from SKILL.md"
|
||||
)
|
||||
|
||||
|
||||
def check_cross_skill_references(result: LintResult) -> None:
|
||||
"""Cross-skill references like `skill-name` must name skills that exist."""
|
||||
skill_names = {p.name for p in list_skill_dirs()}
|
||||
# Catch backtick-quoted skill names that look like skill folder names
|
||||
# (lowercase-hyphenated, must contain at least one hyphen to avoid noise).
|
||||
pattern = re.compile(r"`([a-z][a-z0-9]*(?:-[a-z0-9]+)+)`")
|
||||
|
||||
for skill_dir in list_skill_dirs():
|
||||
skill_md = skill_dir / "SKILL.md"
|
||||
if not skill_md.exists():
|
||||
continue
|
||||
text = read_text(skill_md)
|
||||
for match in pattern.finditer(text):
|
||||
candidate = match.group(1)
|
||||
# Heuristic: only check tokens that look like full skill names
|
||||
# (start with one of our known prefixes or are exactly a skill name).
|
||||
if candidate in skill_names:
|
||||
continue
|
||||
# Looks-like-skill heuristic: has 2+ hyphens or starts with known prefix.
|
||||
known_prefixes = (
|
||||
"seo-", "brand-", "content-", "design-", "code-", "frontend-",
|
||||
"qa-", "ux-", "pm-", "cro-", "form-", "media-", "email-",
|
||||
"domain-", "monitoring-", "backup-", "security-", "launch-",
|
||||
"incident-", "after-", "analytics-", "journey-", "usability-",
|
||||
"performance-", "accessibility-", "art-", "creative-",
|
||||
"information-", "landing-", "skill-", "stakeholder-",
|
||||
"documentation-", "vendor-", "team-", "internationalization",
|
||||
"dependency-", "cost-", "roadmap-",
|
||||
)
|
||||
if any(candidate.startswith(p) for p in known_prefixes):
|
||||
result.fail(
|
||||
f"{skill_md.relative_to(REPO_ROOT)}: references unknown skill "
|
||||
f"`{candidate}` (not a valid skill folder name)"
|
||||
)
|
||||
|
||||
|
||||
def check_line_lengths(result: LintResult) -> None:
|
||||
"""SKILL.md soft cap 400, hard cap 500. Reference files cap 500.
|
||||
|
||||
Counts file line counts via len(splitlines()), not characters
|
||||
per line. The function name is misleading shorthand for file
|
||||
line counts. Consider renaming in a future cleanup.
|
||||
"""
|
||||
for skill_dir in list_skill_dirs():
|
||||
skill_md = skill_dir / "SKILL.md"
|
||||
if skill_md.exists():
|
||||
n = len(read_text(skill_md).splitlines())
|
||||
rel = skill_md.relative_to(REPO_ROOT)
|
||||
if n > SKILL_MD_LINE_LIMIT:
|
||||
result.fail(f"{rel}: {n} lines (hard cap is {SKILL_MD_LINE_LIMIT})")
|
||||
elif n > SKILL_MD_LINE_TARGET:
|
||||
result.warn(f"{rel}: {n} lines (target is under {SKILL_MD_LINE_TARGET})")
|
||||
ref_dir = skill_dir / "references"
|
||||
if ref_dir.exists():
|
||||
for ref in ref_dir.iterdir():
|
||||
if not ref.is_file() or ref.suffix != ".md":
|
||||
continue
|
||||
n = len(read_text(ref).splitlines())
|
||||
rel = ref.relative_to(REPO_ROOT)
|
||||
if n > REFERENCE_LINE_LIMIT:
|
||||
result.warn(f"{rel}: {n} lines (target is under {REFERENCE_LINE_LIMIT})")
|
||||
|
||||
|
||||
def check_readme_catalog_generated(result: LintResult) -> None:
|
||||
"""README catalog content must match the output of the generator script.
|
||||
|
||||
Runs `scripts/generate_readme_catalog.py --check` and surfaces its diff
|
||||
on failure. This is the strict version of `check_readme_catalog_count`,
|
||||
which is kept as a sanity check for badge and header counts.
|
||||
"""
|
||||
import subprocess
|
||||
|
||||
generator = REPO_ROOT / "scripts" / "generate_readme_catalog.py"
|
||||
if not generator.exists():
|
||||
result.fail(
|
||||
f"generator script not found at {generator.relative_to(REPO_ROOT)}"
|
||||
)
|
||||
return
|
||||
proc = subprocess.run(
|
||||
[sys.executable, str(generator), "--check"],
|
||||
cwd=str(REPO_ROOT),
|
||||
capture_output=True,
|
||||
text=True,
|
||||
)
|
||||
if proc.returncode == 0:
|
||||
return
|
||||
detail = (proc.stdout or proc.stderr or "").strip()
|
||||
result.fail(
|
||||
"README catalog out of sync with skill metadata. "
|
||||
"Run: python scripts/generate_readme_catalog.py --write"
|
||||
+ (f"\n{detail}" if detail else "")
|
||||
)
|
||||
|
||||
|
||||
def check_readme_catalog_count(result: LintResult) -> None:
|
||||
"""README badge and catalog claims must match the actual SKILL.md count."""
|
||||
if not README.exists():
|
||||
result.fail("README.md not found")
|
||||
return
|
||||
text = read_text(README)
|
||||
actual = len(list_skill_dirs())
|
||||
|
||||
# Badge: []
|
||||
badge_pattern = re.compile(r"badge/Skills-(\d+)-")
|
||||
for match in badge_pattern.finditer(text):
|
||||
claimed = int(match.group(1))
|
||||
if claimed != actual:
|
||||
result.fail(
|
||||
f"README.md skills badge claims {claimed} but actual count is {actual}"
|
||||
)
|
||||
|
||||
# Catalog header: e.g. "## The 59-skill catalog"
|
||||
catalog_pattern = re.compile(r"## The (\d+)-skill catalog")
|
||||
for match in catalog_pattern.finditer(text):
|
||||
claimed = int(match.group(1))
|
||||
if claimed != actual:
|
||||
result.fail(
|
||||
f"README.md catalog header claims {claimed} but actual count is {actual}"
|
||||
)
|
||||
|
||||
# Status line: "Status: N of N skills shipped" or similar
|
||||
status_pattern = re.compile(r"(\d+) of (\d+) skills shipped", re.IGNORECASE)
|
||||
for match in status_pattern.finditer(text):
|
||||
claimed_done, claimed_total = int(match.group(1)), int(match.group(2))
|
||||
if claimed_total != actual:
|
||||
result.fail(
|
||||
f"README.md status claims '{claimed_done} of {claimed_total} skills' "
|
||||
f"but actual count is {actual}"
|
||||
)
|
||||
|
||||
|
||||
# ---------------------------------------------------------------------------
|
||||
# Driver
|
||||
# ---------------------------------------------------------------------------
|
||||
|
||||
|
||||
CHECKS: list[Callable[[LintResult], None]] = [
|
||||
check_em_dashes,
|
||||
check_brand_leaks,
|
||||
check_frontmatter_and_name_match,
|
||||
check_framework_section,
|
||||
check_reference_files_match,
|
||||
check_cross_skill_references,
|
||||
check_line_lengths,
|
||||
check_readme_catalog_count,
|
||||
check_readme_catalog_generated,
|
||||
]
|
||||
|
||||
|
||||
def main() -> int:
|
||||
print(f"Linting catalog at {REPO_ROOT}")
|
||||
if not SKILLS_DIR.exists():
|
||||
print(f"ERROR: skills/ directory not found at {SKILLS_DIR}", file=sys.stderr)
|
||||
return 1
|
||||
|
||||
skill_count = len(list_skill_dirs())
|
||||
print(f"Found {skill_count} skill folders.\n")
|
||||
|
||||
result = LintResult()
|
||||
for check in CHECKS:
|
||||
sub = LintResult()
|
||||
try:
|
||||
check(sub)
|
||||
except Exception as exc:
|
||||
sub.fail(f"Internal error in {check.__name__}: {exc}")
|
||||
status = "OK" if sub.ok else "FAIL"
|
||||
warn_count = len(sub.warnings)
|
||||
warn_suffix = f" ({warn_count} warnings)" if warn_count else ""
|
||||
print(f" [{status}] {check.__name__}{warn_suffix}")
|
||||
for err in sub.errors:
|
||||
print(f" ERROR: {err}")
|
||||
for warn in sub.warnings:
|
||||
print(f" WARN: {warn}")
|
||||
result.merge(sub)
|
||||
|
||||
print()
|
||||
if result.ok:
|
||||
print(f"PASSED: {skill_count} skills validated, "
|
||||
f"{len(result.warnings)} warnings.")
|
||||
return 0
|
||||
print(f"FAILED: {len(result.errors)} errors, "
|
||||
f"{len(result.warnings)} warnings across {skill_count} skills.")
|
||||
return 1
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
sys.exit(main())
|
||||
@@ -0,0 +1,27 @@
|
||||
name: Lint skills
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
branches: [main]
|
||||
push:
|
||||
branches: [main]
|
||||
workflow_dispatch:
|
||||
|
||||
jobs:
|
||||
lint:
|
||||
name: Validate catalog structure
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Check out repo
|
||||
uses: actions/checkout@v7
|
||||
|
||||
- name: Set up Python
|
||||
uses: actions/setup-python@v6
|
||||
with:
|
||||
python-version: "3.12"
|
||||
|
||||
- name: Install dependencies
|
||||
run: pip install pyyaml
|
||||
|
||||
- name: Run skill linter
|
||||
run: python .github/scripts/lint_skills.py
|
||||
@@ -0,0 +1,18 @@
|
||||
name: Skills manifest
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
paths:
|
||||
- "skills/**"
|
||||
- "tools/gen_skills_lock.py"
|
||||
|
||||
jobs:
|
||||
verify-lock:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v7
|
||||
- uses: actions/setup-python@v6
|
||||
with:
|
||||
python-version: "3.12"
|
||||
- name: Verify SKILLS.lock is current
|
||||
run: python tools/gen_skills_lock.py --check
|
||||
@@ -0,0 +1,56 @@
|
||||
name: Workflows manifest
|
||||
|
||||
on:
|
||||
pull_request:
|
||||
paths:
|
||||
- "workflows/**"
|
||||
- "SKILLS.lock"
|
||||
- "tools/gen_workflows_lock.py"
|
||||
- "tools/check_workflow_drift.py"
|
||||
- ".github/workflows/workflows-manifest.yml"
|
||||
|
||||
jobs:
|
||||
verify-lock:
|
||||
name: WORKFLOWS.lock is current
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v7
|
||||
- uses: actions/setup-python@v6
|
||||
with:
|
||||
python-version: "3.12"
|
||||
- name: Verify WORKFLOWS.lock
|
||||
run: python tools/gen_workflows_lock.py --check
|
||||
|
||||
drift-check:
|
||||
name: Bound skills exist in SKILLS.lock
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v7
|
||||
- uses: actions/setup-python@v6
|
||||
with:
|
||||
python-version: "3.12"
|
||||
- name: Check workflow-to-catalog drift
|
||||
run: python tools/check_workflow_drift.py
|
||||
|
||||
fence-test:
|
||||
name: SKILLS.lock untouched by the workflows tier
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- uses: actions/checkout@v7
|
||||
with:
|
||||
fetch-depth: 0
|
||||
- name: Assert the fence
|
||||
env:
|
||||
BASE_SHA: ${{ github.event.pull_request.base.sha }}
|
||||
run: |
|
||||
touches_workflows=$(git diff --name-only "$BASE_SHA" HEAD -- \
|
||||
workflows/ tools/gen_workflows_lock.py tools/check_workflow_drift.py)
|
||||
skills_lock_changed=$(git diff --name-only "$BASE_SHA" HEAD -- SKILLS.lock)
|
||||
if [ -n "$touches_workflows" ] && [ -n "$skills_lock_changed" ]; then
|
||||
echo "FENCE BREACH: this PR changes both the workflows tier and SKILLS.lock."
|
||||
echo "The workflows tier lives outside the skills source tree and must not"
|
||||
echo "perturb the skills manifest. Split the skill change into its own PR."
|
||||
git diff --stat "$BASE_SHA" HEAD -- SKILLS.lock
|
||||
exit 1
|
||||
fi
|
||||
echo "Fence holds: SKILLS.lock is byte-identical to base for this workflows-tier PR."
|
||||
+25
@@ -0,0 +1,25 @@
|
||||
# OS files
|
||||
.DS_Store
|
||||
Thumbs.db
|
||||
desktop.ini
|
||||
|
||||
# Editor files
|
||||
.vscode/
|
||||
.idea/
|
||||
*.swp
|
||||
*.swo
|
||||
*~
|
||||
|
||||
# Logs
|
||||
*.log
|
||||
|
||||
# Local environment
|
||||
.env
|
||||
.env.local
|
||||
|
||||
# Temporary files
|
||||
*.tmp
|
||||
*.bak
|
||||
|
||||
# Internal audit documents
|
||||
docs/audits/
|
||||
+160
@@ -0,0 +1,160 @@
|
||||
# Changelog
|
||||
|
||||
All notable changes to this library are documented in this file.
|
||||
|
||||
The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
|
||||
|
||||
## [Unreleased]
|
||||
|
||||
### Added
|
||||
|
||||
**Distribution**
|
||||
|
||||
- Claude Code plugin marketplace. `.claude-plugin/marketplace.json` and `.claude-plugin/plugin.json` publish the full catalog as an installable plugin: `/plugin marketplace add rampstackco/claude-skills` then `/plugin install rampstack-skills@rampstack`.
|
||||
|
||||
**README sections**
|
||||
|
||||
- "Install in Claude Code" section documenting the one-command marketplace install path.
|
||||
|
||||
### Changed
|
||||
|
||||
- "The framework's range" cards now link to their live showcase demos (Pulse, Forge, Bloom, Observatory), and the section closes with a CTA to the full creative-direction showcase.
|
||||
- Hand-authored rampstack.co showcase demo links across the README now open in a new tab (`target="_blank" rel="noopener"`).
|
||||
|
||||
## [1.2.0] - 2026-05-07
|
||||
|
||||
### Added
|
||||
|
||||
**Skills (38 net additions, 60 → 98)**
|
||||
|
||||
- `logo-design` skill (Brand category). Logo variants across architectures (wordmark, lockup, monogram, letterform-as-symbol, abstract, pictorial, combination, emblem) with rationale and application specs.
|
||||
- Tier 2 PM experimentation track (6 skills): `experiment-design`, `feature-flagging`, `experimentation-platform-orchestrator`, `experimentation-analytics`, `product-analytics-setup`, `data-warehouse-experimentation`. Statistical discipline for shipping changes with confidence: hypothesis to decision, sample size, sequential testing, CUPED variance reduction, dashboard reconciliation, the failure modes that produce wrong shipping calls.
|
||||
- Tier 2 PM gap-closing track (4 new + 2 expanded): `feature-launch-playbook`, `jtbd-framing`, `okr-design`, `beta-program-management`, plus expanded coverage in `roadmap-planning` and `pm-spec-writing`. Operational discipline for shipping features that land: positioning, internal alignment, customer comms, sales enablement, support readiness, rollout strategy, monitoring, post-launch measurement.
|
||||
- Tier 2 content lifecycle (9 skills): `pillar-content-architecture`, `content-brief-authoring`, `programmatic-seo`, `editorial-qa`, `ai-content-collaboration`, `long-form-content-frameworks`, `content-refresh-system`, `content-repurposing`, `content-distribution`. Hub-and-cluster topical authority, per-piece editorial brief authoring, pSEO programs, pre-publish QA, AI-content workflows, long-form structural patterns, refresh cadence, cross-format adaptation, distribution discipline.
|
||||
- Growth tooling cluster (12 skills): `funnel-flow-architecture` (orchestrator), `lead-magnet-design`, `calculator-design`, `quiz-and-assessment-design`, `multi-step-form-design`, `chatbot-flow-design`, `onboarding-wizard-design`, `interactive-product-tour`, `upgrade-flow-design`, `scheduler-and-booking-design`, `comparison-tool-design`, `product-configurator-design`. Interactive web tools that turn visitors into leads, activate signups, and convert intent to action.
|
||||
- Marketing paid media (3 skills): `paid-media-strategy`, `ads-creative-development`, `ads-performance-analytics`. Channel selection, creative variations, performance analytics for budgets at scale.
|
||||
- Research expansion (2 skills): `discovery-research-synthesis`, `user-feedback-aggregation`. Synthesizing customer interviews and feedback into actionable PM decisions; weighted feedback triage across channels.
|
||||
- `integration-orchestrator` skill (Product category). Sequence creative-direction work across phases, gates, handoffs, and QA verification.
|
||||
|
||||
**Reference files**
|
||||
|
||||
- ~330 new reference files (95 → ~424), bringing every skill above the floor of one reference file each, with most skills carrying 4-6 references covering templates, checklists, decision matrices, and worked examples.
|
||||
- ARIA patterns reference for `accessibility-audit` skill ([PR #36](https://github.com/rampstackco/claude-skills/pull/36) community contribution).
|
||||
- "Methodology-level / Implementation choices" closing section added across reference files.
|
||||
|
||||
**Categories (14 → 16)**
|
||||
|
||||
- Growth tooling category (12 skills). Interactive web tools that turn visitors into leads.
|
||||
- Marketing category (3 skills). Paid media discipline.
|
||||
|
||||
**README sections**
|
||||
|
||||
- "Logo design in action" H2 section showcasing the logo-design skill rendered as two parallel surfaces on rampstack.co (per-brand variant explorer at /showcase/logo-design and architectural taxonomy gallery at /showcase/logos).
|
||||
- "Surfaces" section naming the rampstack.co commercial layer (skills directory, walkthroughs, integrations directory, showcase) that extends the open-source methodology.
|
||||
- "How the catalog connects" section with AI-generated hub-and-spoke architecture diagram (Gemini-generated JPG, responsive variants for desktop and mobile via `<picture>` element) showing 98 skills at the center and 35 integrations across 6 categories radiating out.
|
||||
- HTML `<picture>` element pattern for responsive image swaps on README and at rampstack.co/integrations.
|
||||
- Acknowledgments section crediting [@IgnacioChiaravalle](https://github.com/IgnacioChiaravalle) for the PR #36 community feedback (CONTRIBUTING typo fix, cross-linking pass, ARIA patterns reference).
|
||||
|
||||
**Generator scripts**
|
||||
|
||||
- `scripts/generate_readme_catalog.py`. Build-time README generator with `FEATURED_SKILLS`, `SURFACES`, and `COUNT_*` markers driven by skills/ folder contents. Eliminates drift between catalog state and README.
|
||||
- `scripts/generate_og_card.py`. Pillow-based reproducible OG social card.
|
||||
- `scripts/crosslink_pass.py`. Idempotent script from PR #36 that maintains cross-references between SKILL.md files and reference files.
|
||||
|
||||
### Changed
|
||||
|
||||
- Catalog renumbered to 98 entries across 16 categories. README catalog tables now drop the # column (was creating mobile readability issues).
|
||||
- Featured Skills section restructured to 2-column with audience track parenthetical (was 3-column without track).
|
||||
- Architecture image redesigned as AI-generated illustration (Gemini) matching the rampstack.co aesthetic, replacing the prior Pillow-rendered diagram. JPG variants for desktop and mobile.
|
||||
- README "Recommended MCPs" section restructured with explicit cost-model framing (free with rate limits, credits-per-call, etc.) per integration. SEO competitive intelligence section expanded to cover Ahrefs, Semrush, DataForSEO, Similarweb with explicit complementarity framing.
|
||||
- Cross-skill cross-references expanded across the catalog: every skill's "When NOT to use" section names sibling skills, and "Pairs with" references made bidirectional.
|
||||
- README archetype count updated from "Thirty fictional brands" to "Forty-two fictional brands" reflecting the actual count on rampstack.co/showcase/creative-direction (Wave 1 + Wave 2 expansions).
|
||||
|
||||
### Fixed
|
||||
|
||||
- Stale archetype count reference in README "See it in action" intro.
|
||||
- Mobile readability of catalog tables (# column was forcing horizontal scroll on narrow viewports).
|
||||
- Logo showcase mark clipping on /showcase/logos (Tarsus and Caval marks had viewBox declarations too tight for their rendered content; expanded viewBoxes preserve design intent while giving content room to render). Live at rampstack.co/showcase/logos.
|
||||
|
||||
## [1.1.0] - 2026-04-30
|
||||
|
||||
### Added
|
||||
|
||||
**Community standards**
|
||||
|
||||
- `CONTRIBUTING.md` with full contribution process and authoring discipline.
|
||||
- `CODE_OF_CONDUCT.md` (Contributor Covenant 2.1).
|
||||
- `SECURITY.md` with vulnerability reporting process.
|
||||
- `CHANGELOG.md` (this file).
|
||||
- Issue templates: new skill request, bug report, improve reference file.
|
||||
- Pull request template.
|
||||
- 100% Community Standards score on GitHub repo health check.
|
||||
|
||||
**Reference files**
|
||||
|
||||
- 20 new reference files (75 → 95).
|
||||
|
||||
**README**
|
||||
|
||||
- Recommended MCPs section listing categorical recommendations by skill area.
|
||||
- Banner image at `docs/banner.jpg`.
|
||||
- Social profile links (LinkedIn, X/Twitter, Facebook).
|
||||
- Expanded table of contents.
|
||||
|
||||
### Changed
|
||||
|
||||
- Audit reports moved from repo root to `docs/audits/`.
|
||||
|
||||
### Fixed
|
||||
|
||||
- 21 broken SKILL.md to reference file links.
|
||||
- 6 orphan reference files (referenced from no SKILL.md).
|
||||
- Cross-skill reference (`pm-framework` → `pm-spec-writing`).
|
||||
- 3 SKILL.md framework section headers normalized.
|
||||
- `SKILL_AUTHORING.md` updated with section-naming clarification.
|
||||
|
||||
## [1.0.0] - 2026-04-28
|
||||
|
||||
### Added
|
||||
|
||||
The initial public release. 59 stack-agnostic Claude Skills covering the full website lifecycle.
|
||||
|
||||
**Strategy and discovery (4):** `brand-discovery`, `creative-brief`, `information-architecture`, `content-strategy`
|
||||
|
||||
**Brand (4):** `brand-ideation`, `brand-identity`, `brand-style-guide`, `brand-voice`
|
||||
|
||||
**Design (3):** `design-system`, `design-standards`, `art-direction`
|
||||
|
||||
**Content (3):** `content-and-copy`, `landing-page-copy`, `email-sequences`
|
||||
|
||||
**SEO foundation (7):** `seo-onpage`, `seo-technical`, `seo-keyword`, `seo-competitor`, `seo-offpage`, `seo-content-audit`, `seo-aeo-geo`
|
||||
|
||||
**SEO audit suite (Ahrefs MCP-powered) (7):** `seo-audit-orchestration`, `seo-backlink-audit`, `seo-keyword-gap-audit`, `seo-content-gap-audit`, `seo-traffic-diagnosis`, `seo-site-health-audit`, `seo-rank-tracking`
|
||||
|
||||
**Product (2):** `pm-spec-writing`, `roadmap-planning`
|
||||
|
||||
**Development (4):** `code-review-web`, `frontend-component-build`, `accessibility-audit`, `performance-optimization`
|
||||
|
||||
**Quality assurance (1):** `qa-testing`
|
||||
|
||||
**Operations (9):** `launch-runbook`, `incident-response`, `after-action-report`, `domain-strategy`, `monitoring-and-alerting`, `backup-and-disaster-recovery`, `security-baseline`, `email-deliverability`, `media-asset-management`
|
||||
|
||||
**Growth (2):** `analytics-strategy`, `cro-optimization`
|
||||
|
||||
**Research (3):** `ux-research`, `usability-testing`, `journey-mapping`
|
||||
|
||||
**Cross-cutting workflows (5):** `form-strategy`, `content-migration`, `internationalization`, `dependency-management`, `cost-optimization`
|
||||
|
||||
**Process and team (5):** `stakeholder-communication`, `documentation-strategy`, `vendor-evaluation`, `team-onboarding-playbook`, `skill-creation-walkthrough`
|
||||
|
||||
### Repo metadata
|
||||
|
||||
- 59 `SKILL.md` files
|
||||
- 75 reference files
|
||||
- Companion docs: `README.md`, `SKILL_AUTHORING.md`, `MAPPING.md`, `CONTRIBUTING.md`, `CODE_OF_CONDUCT.md`, `SECURITY.md`, `CHANGELOG.md`
|
||||
- MIT License
|
||||
|
||||
[Unreleased]: https://github.com/rampstackco/claude-skills/compare/v1.2.0...HEAD
|
||||
[1.2.0]: https://github.com/rampstackco/claude-skills/releases/tag/v1.2.0
|
||||
[1.1.0]: https://github.com/rampstackco/claude-skills/releases/tag/v1.1.0
|
||||
[1.0.0]: https://github.com/rampstackco/claude-skills/releases/tag/v1.0.0
|
||||
@@ -0,0 +1,77 @@
|
||||
# Code of Conduct
|
||||
|
||||
## Our pledge
|
||||
|
||||
We as members, contributors, and leaders pledge to make participation in this project a respectful and welcoming experience for everyone, regardless of age, body size, visible or invisible disability, ethnicity, sex characteristics, gender identity and expression, level of experience, education, socio-economic status, nationality, personal appearance, race, religion, or sexual identity and orientation.
|
||||
|
||||
We pledge to act and interact in ways that contribute to an open, welcoming, diverse, inclusive, and healthy community.
|
||||
|
||||
## Our standards
|
||||
|
||||
Examples of behavior that contributes to a positive environment:
|
||||
|
||||
- Demonstrating empathy and kindness toward other people
|
||||
- Being respectful of differing opinions, viewpoints, and experiences
|
||||
- Giving and gracefully accepting constructive feedback
|
||||
- Accepting responsibility and apologizing to those affected by our mistakes, and learning from the experience
|
||||
- Focusing on what is best not just for us as individuals, but for the overall community
|
||||
|
||||
Examples of unacceptable behavior:
|
||||
|
||||
- The use of sexualized language or imagery, and sexual attention or advances of any kind
|
||||
- Trolling, insulting or derogatory comments, and personal or political attacks
|
||||
- Public or private harassment
|
||||
- Publishing others' private information, such as a physical or email address, without their explicit permission
|
||||
- Other conduct which could reasonably be considered inappropriate in a professional setting
|
||||
|
||||
## Enforcement responsibilities
|
||||
|
||||
Project maintainers are responsible for clarifying and enforcing standards of acceptable behavior. They will take appropriate and fair corrective action in response to any behavior they deem inappropriate, threatening, offensive, or harmful.
|
||||
|
||||
Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, wiki edits, issues, and other contributions that are not aligned with this Code of Conduct, and will communicate reasons for moderation decisions when appropriate.
|
||||
|
||||
## Scope
|
||||
|
||||
This Code of Conduct applies within all project spaces, and also applies when an individual is officially representing the project in public spaces. Examples include using an official email address, posting via an official social media account, or acting as an appointed representative at an online or offline event.
|
||||
|
||||
## Enforcement
|
||||
|
||||
Instances of abusive, harassing, or otherwise unacceptable behavior may be reported to the project maintainers at conduct@rampstack.co. All complaints will be reviewed and investigated promptly and fairly.
|
||||
|
||||
All project maintainers are obligated to respect the privacy and security of the reporter of any incident.
|
||||
|
||||
## Enforcement guidelines
|
||||
|
||||
Project maintainers will follow these guidelines in determining the consequences for any action they deem in violation of this Code of Conduct:
|
||||
|
||||
### 1. Correction
|
||||
|
||||
**Community impact:** Use of inappropriate language or other behavior deemed unprofessional or unwelcome.
|
||||
|
||||
**Consequence:** A private, written warning from project maintainers, providing clarity around the nature of the violation and an explanation of why the behavior was inappropriate. A public apology may be requested.
|
||||
|
||||
### 2. Warning
|
||||
|
||||
**Community impact:** A violation through a single incident or series of actions.
|
||||
|
||||
**Consequence:** A warning with consequences for continued behavior. No interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, for a specified period of time. This includes avoiding interactions in community spaces as well as external channels like social media. Violating these terms may lead to a temporary or permanent ban.
|
||||
|
||||
### 3. Temporary ban
|
||||
|
||||
**Community impact:** A serious violation of community standards, including sustained inappropriate behavior.
|
||||
|
||||
**Consequence:** A temporary ban from any sort of interaction or public communication with the community for a specified period of time. No public or private interaction with the people involved, including unsolicited interaction with those enforcing the Code of Conduct, is allowed during this period. Violating these terms may lead to a permanent ban.
|
||||
|
||||
### 4. Permanent ban
|
||||
|
||||
**Community impact:** Demonstrating a pattern of violation of community standards, including sustained inappropriate behavior, harassment of an individual, or aggression toward or disparagement of classes of individuals.
|
||||
|
||||
**Consequence:** A permanent ban from any sort of public interaction within the community.
|
||||
|
||||
## Attribution
|
||||
|
||||
This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1, available at [https://www.contributor-covenant.org/version/2/1/code_of_conduct.html](https://www.contributor-covenant.org/version/2/1/code_of_conduct.html).
|
||||
|
||||
Community Impact Guidelines were inspired by [Mozilla's code of conduct enforcement ladder](https://github.com/mozilla/diversity).
|
||||
|
||||
For answers to common questions about this code of conduct, see the FAQ at [https://www.contributor-covenant.org/faq](https://www.contributor-covenant.org/faq). Translations are available at [https://www.contributor-covenant.org/translations](https://www.contributor-covenant.org/translations).
|
||||
+215
@@ -0,0 +1,215 @@
|
||||
# Contributing to Brand Build Skills for Claude
|
||||
|
||||
Thank you for considering a contribution. This library is opinionated by design: every skill follows the same structure, the same voice, and the same authoring conventions. That uniformity is what makes the skills compose cleanly. Contributions that respect those conventions are welcome.
|
||||
|
||||
If you have not read [SKILL_AUTHORING.md](SKILL_AUTHORING.md), start there. It is the source of truth for the skill structure and the bar for shipping.
|
||||
|
||||
---
|
||||
|
||||
## What we accept
|
||||
|
||||
- **New skills** that fill a real gap in the lifecycle and follow the uniform structure
|
||||
- **Reference file improvements** to existing skills (better templates, deeper checklists, worked examples)
|
||||
- **Bug fixes** in cross-references, broken internal links, typos, or stale information
|
||||
- **Clarifications** to existing skills that improve trigger reliability or output quality
|
||||
|
||||
## What we will likely decline
|
||||
|
||||
- Stack-specific skills that hard-code one framework (Next.js-only, WordPress-only). The library is stack-agnostic by policy.
|
||||
- Skills that duplicate an existing skill in scope. Check the catalog first.
|
||||
- Skills that depend on a specific commercial tool, with the single exception of the SEO audit suite which depends on the Ahrefs MCP. New tool-bound skills need a strong justification.
|
||||
- Marketing or promotional content disguised as a skill.
|
||||
- Additions to the README MCP shortlist that a maintainer has not used and vouched for. See **Recommending an MCP server** below.
|
||||
|
||||
---
|
||||
|
||||
## Recommending an MCP server
|
||||
|
||||
The README keeps a short, curated list of MCP servers grouped by lifecycle phase. It points builders at tools the maintainers have used on real site work and will put the catalog's name behind. It is a recommendation, not a directory, and it stays short on purpose.
|
||||
|
||||
The bar reflects what this catalog is for. RampStack is a framework for original creation: building the brands, sites, and content that did not exist before you built them. The tools we recommend serve that work, and they have to be safe to hand to a real business, from a one-person shop to an enterprise team. Much of the AI tooling built around scraping, data copying, and platform automation attracts bad actors and carries legal and reputational risk, so we keep it out. That keeps the catalog something a serious business can adopt without a second thought.
|
||||
|
||||
What that means in practice:
|
||||
|
||||
- **It has to sit inside the website lifecycle this catalog covers** (research, brand, design, content, SEO, dev, ops, growth). Tools whose core job is scraping, bulk data extraction, or off-platform automation are out of scope, even the well engineered ones.
|
||||
- **A maintainer has to have used it** on a real build and be willing to vouch for it. We do not list tools we have only read about.
|
||||
- **Vendors do not add their own tools.** If you build or work on an MCP server, you are welcome to suggest it, but disclose the affiliation and expect it to clear the same bar as everything else. Self-submitted vendor PRs that add a product to the list will be closed with a link to this section.
|
||||
- **The list recommends capabilities, not links.** Anything that reads as placement for traffic, backlinks, or customer acquisition gets declined.
|
||||
|
||||
If you think a tool belongs on the list, open a thread in [Discussions](https://github.com/rampstackco/claude-skills/discussions) with the tool and a concrete use case you hit on a real project. Direct PRs that edit the MCP list will generally be closed in favor of that thread.
|
||||
|
||||
---
|
||||
|
||||
## Quick contribution steps
|
||||
|
||||
1. **Open an issue first** for any new skill or major change. This prevents wasted effort.
|
||||
2. **Fork the repo.**
|
||||
3. **Create a feature branch.** Name it descriptively: `add-skill-form-strategy`, `fix-broken-link-in-seo-keyword`, etc.
|
||||
4. **Follow the uniform structure** documented in [SKILL_AUTHORING.md](SKILL_AUTHORING.md).
|
||||
5. **Run the contributor checklist** below.
|
||||
6. **Submit a PR** with a clear title, description, and link to the originating issue.
|
||||
|
||||
---
|
||||
|
||||
## Adding a new skill
|
||||
|
||||
The README catalog section is generated from skill folder metadata. Do not hand-edit it.
|
||||
|
||||
1. Create the skill folder at `skills/your-skill-name/`.
|
||||
2. Author `SKILL.md` with these YAML frontmatter fields:
|
||||
- `name` (string, must match folder name)
|
||||
- `description` (string, 2 to 4 sentences with triggers)
|
||||
- `category` (one of: `strategy-and-discovery`, `brand`, `design`, `content`, `seo-foundation`, `seo-audit-suite`, `product`, `development`, `qa`, `operations`, `growth`, `research`, `cross-cutting`, `process-and-team`)
|
||||
- `catalog_summary` (string, one-line description for the catalog table)
|
||||
- `display_order` (integer, controls position within the category; omit for alphabetical-by-slug)
|
||||
3. Add at least one reference file under `skills/your-skill-name/references/`.
|
||||
4. Run `python scripts/generate_readme_catalog.py --write`. The generator updates the badge, subtitle, "What you get" counts, table-of-contents anchor, catalog header, and the catalog table.
|
||||
5. Verify with `python .github/scripts/lint_skills.py`.
|
||||
6. Open the PR.
|
||||
|
||||
The catalog content between `<!-- CATALOG:START -->` and `<!-- CATALOG:END -->` (and the six smaller marker pairs) is owned by the generator. Hand edits inside markers are overwritten on the next run. The generator is the source of truth.
|
||||
|
||||
---
|
||||
|
||||
## Skill structure (the short version)
|
||||
|
||||
```
|
||||
your-skill-name/
|
||||
SKILL.md
|
||||
references/
|
||||
template.md
|
||||
checklist.md
|
||||
example.md
|
||||
```
|
||||
|
||||
Your `SKILL.md` must include these sections, in this exact order:
|
||||
|
||||
1. YAML frontmatter (`name`, `description`)
|
||||
2. One-paragraph purpose statement
|
||||
3. `## When to use`
|
||||
4. `## When NOT to use`
|
||||
5. `## Required inputs`
|
||||
6. `## The framework`
|
||||
7. `## Workflow`
|
||||
8. `## Failure patterns`
|
||||
9. `## Output format`
|
||||
10. `## Reference files`
|
||||
|
||||
The full spec, with examples and rationale, lives in [SKILL_AUTHORING.md](SKILL_AUTHORING.md). The fastest path to writing a compliant skill is to use the [`skill-creation-walkthrough`](skills/skill-creation-walkthrough/SKILL.md) skill itself.
|
||||
|
||||
---
|
||||
|
||||
## Voice and style
|
||||
|
||||
The library has a specific voice. Match it.
|
||||
|
||||
- **Punchy short sentences.** Avoid run-ons.
|
||||
- **No em dashes.** Use periods, colons, parentheses, or commas.
|
||||
- **No first-person.** Neutral instructional voice.
|
||||
- **Concrete examples beat abstract advice.** Failure patterns should name the mistake specifically, not generically.
|
||||
- **Stack-agnostic.** Never hard-code framework versions in SKILL.md. Move stack-specific patterns to reference files if absolutely needed.
|
||||
- **No emojis** unless the skill is explicitly about content where they fit (and even then, sparingly).
|
||||
- **No private brand or company references.** Skills are public, so they should be generic.
|
||||
|
||||
---
|
||||
|
||||
## Contributor checklist
|
||||
|
||||
Before opening a PR, verify all of the following:
|
||||
|
||||
- [ ] Skill folder name is `lowercase-hyphenated`
|
||||
- [ ] `SKILL.md` exists with valid YAML frontmatter
|
||||
- [ ] `name` in frontmatter matches the folder name exactly
|
||||
- [ ] `description` is 2-4 sentences with explicit triggers and an "Also triggers when..." line
|
||||
- [ ] All 10 sections are present in the documented order
|
||||
- [ ] At least one reference file exists in `references/`
|
||||
- [ ] Reference files in the SKILL.md "Reference files" section match the actual files
|
||||
- [ ] No em dashes anywhere (search files for U+2014)
|
||||
- [ ] No vendor-specific framework references in the SKILL.md body
|
||||
- [ ] No version-specific references (e.g., "Tailwind 4", "Next.js 15") in the SKILL.md body
|
||||
- [ ] No private brand, personal handle, or proprietary domain references
|
||||
- [ ] Cross-references to sibling skills name skills that actually exist
|
||||
- [ ] `SKILL.md` is under 250 lines (hard cap 500)
|
||||
- [ ] Each reference file is under 400 lines
|
||||
- [ ] You have read at least one existing skill in a similar category and matched its style
|
||||
- [ ] If you added a new skill, the new SKILL.md frontmatter has `category`, `catalog_summary`, and `display_order` fields, and `python scripts/generate_readme_catalog.py --write` was run to update the README catalog
|
||||
- [ ] If you added a new skill, you ran a quick local search for trigger collisions with existing skills
|
||||
|
||||
---
|
||||
|
||||
## Pull request guidelines
|
||||
|
||||
- **One concept per PR.** Do not bundle a new skill, three bug fixes, and a refactor. Split them.
|
||||
- **Clear PR title.** Format: `Add: [skill-name]`, `Fix: [short description]`, `Improve: [skill-name] reference file`.
|
||||
- **Description includes:**
|
||||
- Link to the originating issue
|
||||
- What the contribution adds or changes
|
||||
- Why it earns its place (especially for new skills)
|
||||
- Any decisions you made that future maintainers should know about
|
||||
- **Be patient.** This is a maintained library. Reviews take time.
|
||||
- **Be open to feedback.** The reviewer's goal is uniformity and quality, not gatekeeping.
|
||||
|
||||
---
|
||||
|
||||
## Reviewing process
|
||||
|
||||
1. A maintainer reviews the PR for structural compliance, voice match, and substance.
|
||||
2. Comments may be left for clarification or required changes.
|
||||
3. Once approved, the PR is merged.
|
||||
4. CI runs the lint suite on every PR, including the generator-sync check. Stale README catalog blocks the merge.
|
||||
|
||||
---
|
||||
|
||||
## Security and review requirements
|
||||
|
||||
Every skill, whether authored in-house or contributed, is held to the same
|
||||
review standard before it merges.
|
||||
|
||||
### All contributions
|
||||
|
||||
- Follow [SKILL_AUTHORING.md](SKILL_AUTHORING.md) for SKILL.md structure and
|
||||
metadata.
|
||||
- Commits to `main` are signed and merged through a pull request with linear
|
||||
history.
|
||||
- Each skill and its bundled files must pass the safety checklist below.
|
||||
- PRs are squash-merged.
|
||||
|
||||
### Safety checklist
|
||||
|
||||
Unless the behavior is the skill's explicit, documented purpose, a skill must
|
||||
not:
|
||||
|
||||
- Make network calls or reference external domains from bundled scripts.
|
||||
- Read environment variables, credentials, or secret files.
|
||||
- Spawn shells or subprocesses.
|
||||
- Contain instructions that redirect Claude away from the user's task.
|
||||
- Use trigger conditions broader than the skill's actual scope.
|
||||
- Write to agent memory or persistence files.
|
||||
|
||||
Anything that legitimately needs one of these must declare it in the PR and
|
||||
gets extra review. An advisory scan (`tools/scan_skills.py`) flags these
|
||||
patterns to focus review; it is a guide, not a gate.
|
||||
|
||||
### When external contributions are open (curator mode)
|
||||
|
||||
These apply once the catalog accepts outside contributors:
|
||||
|
||||
- Sign off each commit under the Developer Certificate of Origin
|
||||
(`git commit -s`).
|
||||
- Complete the PR template, declaring what the skill does and what it accesses.
|
||||
- The scan is promoted to a required status check.
|
||||
- Skills carrying executable code get two-person review.
|
||||
|
||||
---
|
||||
|
||||
## Code of conduct
|
||||
|
||||
Be respectful. Be constructive. Disagree on substance, not personality. Bad-faith contributions, harassment, or self-promotional spam will be closed without comment.
|
||||
|
||||
---
|
||||
|
||||
## Questions
|
||||
|
||||
Open a [GitHub Discussion](https://github.com/rampstackco/claude-skills/discussions) for general questions or proposals. Use [Issues](https://github.com/rampstackco/claude-skills/issues) for bugs and concrete change requests.
|
||||
|
||||
Thank you for contributing. The library gets better with every well-shaped addition.
|
||||
@@ -0,0 +1,21 @@
|
||||
MIT License
|
||||
|
||||
Copyright (c) 2026 RampStack Co.
|
||||
|
||||
Permission is hereby granted, free of charge, to any person obtaining a copy
|
||||
of this software and associated documentation files (the "Software"), to deal
|
||||
in the Software without restriction, including without limitation the rights
|
||||
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
||||
copies of the Software, and to permit persons to whom the Software is
|
||||
furnished to do so, subject to the following conditions:
|
||||
|
||||
The above copyright notice and this permission notice shall be included in all
|
||||
copies or substantial portions of the Software.
|
||||
|
||||
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
||||
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
||||
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
||||
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
||||
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
||||
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
||||
SOFTWARE.
|
||||
+168
@@ -0,0 +1,168 @@
|
||||
# Mapping: Existing Skills → Public v1
|
||||
|
||||
This document records the historical porting decisions for the initial public skill set (v1). It exists so contributors can see why a skill looks the way it does.
|
||||
|
||||
> **Note**: This is a historical document covering the initial v1 port. The current catalog has expanded substantially (see `README.md` for the current count and full list). The mapping below covers only the original v1 ports and net-new writes.
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
The starting position: 5 user-scoped skills. The public v1: 11 skills. Five of the public skills are generic ports of existing ones. Six were net-new and written from scratch. Subsequent versions added many more skills covering the full lifecycle.
|
||||
|
||||
| Existing skill | Maps to | Action |
|
||||
|---|---|---|
|
||||
| `design-framework` | `design-standards` | Port + genericize |
|
||||
| `pm-framework` | `pm-spec-writing` | Port + genericize |
|
||||
| `seo-review` | `seo-foundations` | Port + lighten |
|
||||
| `dev-code-review` | `code-review-web` | Port + abstract |
|
||||
| `qa-testing` | `qa-testing` | Port + lighten |
|
||||
|
||||
| New skill | Source | Action |
|
||||
|---|---|---|
|
||||
| `brand-discovery` | New | Write from scratch |
|
||||
| `creative-brief` | New | Write from scratch (prototype done) |
|
||||
| `information-architecture` | New | Write from scratch |
|
||||
| `content-and-copy` | New | Write from scratch |
|
||||
| `launch-runbook` | New | Write from scratch |
|
||||
| `after-action-report` | New | Write from scratch |
|
||||
|
||||
---
|
||||
|
||||
## Port decisions, skill by skill
|
||||
|
||||
### `design-framework` → `design-standards`
|
||||
|
||||
**Keep:**
|
||||
- WCAG AA contrast ratios and the contrast checker JS
|
||||
- The pre-ship checklist (mostly)
|
||||
- Section pattern philosophy (hero, card grid, data row, CTA banner)
|
||||
|
||||
**Genericize or remove:**
|
||||
- Tailwind class libraries → reference patterns conceptually, give one Tailwind example as a reference file, give equivalent vanilla CSS
|
||||
- `#E47200 not #FF9900` Amazon orange rule → genericize as "verify brand color contrast against actual backgrounds"
|
||||
- The specific hex tokens (`#1A1D23`, etc.) → replace with role-based tokens that the user fills in
|
||||
- Affiliate-specific markup (`rel="nofollow sponsored"`) → keep but make optional
|
||||
|
||||
**Add:**
|
||||
- Stack-agnostic component patterns (React + vanilla HTML side by side in a reference file)
|
||||
- Type scale guidance independent of Tailwind classes
|
||||
- Spacing system explanation (8px grid as the default reference)
|
||||
|
||||
**Risk:** stripping the Tailwind classes makes it less immediately useful for your own projects. Mitigation: ship a `references/tailwind-patterns.md` reference file that contains the existing Tailwind library, so you don't lose anything.
|
||||
|
||||
---
|
||||
|
||||
### `pm-framework` → `pm-spec-writing`
|
||||
|
||||
**Keep:**
|
||||
- The IDEA → SPEC → BRIEF → SHIP loop
|
||||
- The dev brief structure (CONTEXT / TASK / CONSTRAINTS / VERIFY)
|
||||
- Impact vs effort quadrant
|
||||
- Feature planning templates (new page, content entry, bug report)
|
||||
- Decision log structure
|
||||
|
||||
**Genericize or remove:**
|
||||
- Multi-agent orchestration section → split out. This is a power-user pattern that doesn't belong in a generic public skill. Consider a separate `ai-agent-orchestration` skill later.
|
||||
- Sprint rhythm → keep but loosen the SEO-revenue-affiliate framing
|
||||
- Launch checklist → move to the new `launch-runbook` skill (this is its proper home)
|
||||
|
||||
**Add:**
|
||||
- User story format (As a / I want / So that) for teams that prefer it
|
||||
- Acceptance criteria patterns
|
||||
- A worked example from idea to ticket
|
||||
|
||||
**Risk:** removing the launch checklist creates churn. Mitigation: it lives in `launch-runbook` now, where it belongs, and `pm-spec-writing` references it.
|
||||
|
||||
---
|
||||
|
||||
### `seo-review` → `seo-foundations`
|
||||
|
||||
**Keep:**
|
||||
- Technical SEO checklist (canonical, sitemap, robots.txt, schema)
|
||||
- On-page patterns
|
||||
- E-E-A-T signals
|
||||
- AEO and GEO sections
|
||||
- Schema markup patterns
|
||||
|
||||
**Genericize or remove:**
|
||||
- Any references to specific affiliate networks
|
||||
- Project-specific examples from your own portfolio
|
||||
- Stack-specific implementation (Next.js metadata API, etc.) → move to a `references/stack-implementations.md` file
|
||||
|
||||
**Add:**
|
||||
- Pre-launch SEO checklist as a separate quick-reference file
|
||||
- llms.txt guidance (since this is becoming standard)
|
||||
|
||||
---
|
||||
|
||||
### `dev-code-review` → `code-review-web`
|
||||
|
||||
**Keep:**
|
||||
- Bug-finding mindset
|
||||
- Security review patterns
|
||||
- Performance review patterns
|
||||
|
||||
**Genericize or remove:**
|
||||
- Next.js/Supabase-specific failure modes → move to a `references/stack-quirks.md` file with Next.js, WordPress, and vanilla sections
|
||||
- TypeScript-specific patterns → keep but mark as optional
|
||||
- ISR-specific guidance → reference file
|
||||
|
||||
**Add:**
|
||||
- A general code review checklist that works for any web stack
|
||||
- Accessibility review section (was implicit, make explicit)
|
||||
|
||||
**Risk:** loses some of its punch when stripped of stack opinions. Mitigation: the reference files preserve the depth, and the trigger description still hooks the same review intent.
|
||||
|
||||
---
|
||||
|
||||
### `qa-testing` → `qa-testing` (same name)
|
||||
|
||||
**Keep:**
|
||||
- Functional QA flow
|
||||
- Accessibility checks
|
||||
- Performance checks
|
||||
- Cross-browser checks
|
||||
|
||||
**Genericize or remove:**
|
||||
- Any Vercel/Supabase-specific deploy verification → reference file
|
||||
- WordPress-specific patterns (you have a section on these) → reference file
|
||||
|
||||
**Add:**
|
||||
- A QA report template (markdown) so the output is consistent
|
||||
- Pre-launch vs post-deploy QA distinction (different scopes)
|
||||
|
||||
---
|
||||
|
||||
## What does NOT get ported
|
||||
|
||||
A few patterns from your existing skills are intentionally not in the public set:
|
||||
|
||||
- **Multi-agent orchestration** - too specific to your workflow. Could be a separate skill later.
|
||||
- **`/go/[slug]` affiliate redirects** - too specific to your monetization model. Mention briefly in `seo-foundations` as one valid pattern, not as the standard.
|
||||
- **`llms.txt` on all sites** - keep as a recommendation in `seo-foundations` but not a non-negotiable.
|
||||
- **Personal style preferences** (em dash prohibition, hashtag-in-comments, specific monetization patterns). These live in your private skills, not the public set.
|
||||
|
||||
---
|
||||
|
||||
## v1 ship plan
|
||||
|
||||
Suggested order to write the remaining skills:
|
||||
|
||||
1. **Done:** `creative-brief` (prototype, sets the pattern)
|
||||
2. **Port next** (lowest risk, you already have the content): `design-standards`, `pm-spec-writing`, `qa-testing`
|
||||
3. **Port after that:** `seo-foundations`, `code-review-web`
|
||||
4. **Write new:** `brand-discovery` (precedes `creative-brief`, so write next)
|
||||
5. **Write new:** `information-architecture`, `content-and-copy`
|
||||
6. **Write new last:** `launch-runbook`, `after-action-report`
|
||||
|
||||
This order means the most-used skills land first, so you can dogfood them on a real project before the rest are written.
|
||||
|
||||
---
|
||||
|
||||
## Open questions to revisit
|
||||
|
||||
- Do `brand-discovery` and `creative-brief` stay separate or merge? Default: separate. Different triggers, different outputs.
|
||||
- Should `code-review-web` split into `code-review-frontend` and `code-review-backend`? Default: no for v1. Revisit if the skill gets too long.
|
||||
- Should there be a `accessibility` skill, or does it stay distributed across `design-standards`, `qa-testing`, and `code-review-web`? Default: distributed. Accessibility is a quality dimension, not a phase.
|
||||
- License: MIT. Confirm this is what you want before publishing.
|
||||
@@ -0,0 +1,881 @@
|
||||
<div align="center">
|
||||
|
||||
<img src="docs/rampstack-complete-banner.jpg" alt="Complete Claude Skills for the full web lifecycle. Build, ship, audit, optimize." />
|
||||
|
||||
# Brand Build Skills for Claude
|
||||
|
||||
**A complete, opinionated library of [Claude Skills](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview) covering the full lifecycle of building, launching, running, and growing a brand and a website.**
|
||||
|
||||
[](LICENSE)
|
||||
[](CONTRIBUTING.md)
|
||||
[](#the-103-skill-catalog)
|
||||
[](https://claude.ai)
|
||||
|
||||
[](https://rampstack.co)
|
||||
[](https://linkedin.com/company/rampstack/)
|
||||
[](https://x.com/RampStackco)
|
||||
[](https://facebook.com/rampstack)
|
||||
|
||||
</div>
|
||||
|
||||
<!-- COUNT_INTRO:START -->
|
||||
> 103 stack-agnostic skills covering brand, design, content, SEO, dev, ops, growth, and research. Includes an Ahrefs MCP-powered SEO audit suite. Use them on Next.js, WordPress, Shopify, Webflow, plain HTML, or anything else.
|
||||
<!-- COUNT_INTRO:END -->
|
||||
|
||||
*Featured in [awesome-claude-skills](https://github.com/ComposioHQ/awesome-claude-skills) under Business & Marketing.*
|
||||
|
||||
---
|
||||
|
||||
## Install in Claude Code
|
||||
|
||||
Add the marketplace, then install the plugin you want:
|
||||
|
||||
```
|
||||
/plugin marketplace add rampstackco/claude-skills
|
||||
|
||||
# full catalog (103 skills)
|
||||
/plugin install rampstack-skills@rampstack
|
||||
|
||||
# focused subsets
|
||||
/plugin install rampstack-starter@rampstack
|
||||
/plugin install rampstack-seo@rampstack
|
||||
/plugin install rampstack-pm@rampstack
|
||||
```
|
||||
|
||||
Prefer a lighter marketplace that lists only the curated subsets (no full catalog)? Add `rampstackco/plugins` instead and install the same three plugins from there:
|
||||
|
||||
```
|
||||
/plugin marketplace add rampstackco/plugins
|
||||
/plugin install rampstack-starter@rampstack
|
||||
```
|
||||
|
||||
Skills load on demand: each contributes roughly its name and description until Claude needs it.
|
||||
|
||||
---
|
||||
|
||||
## Table of contents
|
||||
|
||||
- [What are Claude Skills?](#what-are-claude-skills)
|
||||
- [What is in this library](#what-is-in-this-library)
|
||||
- [Featured skills](#featured-skills)
|
||||
- [See it in action](#see-it-in-action)
|
||||
- [Logo design in action](#logo-design-in-action)
|
||||
- [Reference build in action](#reference-build-in-action)
|
||||
- [Getting started](#getting-started)
|
||||
- [Quick example](#quick-example)
|
||||
- [How they compose](#how-they-compose)
|
||||
- [How the catalog connects](#how-the-catalog-connects)
|
||||
- [Surfaces](#surfaces)
|
||||
<!-- COUNT_TOC:START -->
|
||||
- [The 103-skill catalog](#the-103-skill-catalog)
|
||||
<!-- COUNT_TOC:END -->
|
||||
- [Recommended MCPs](#recommended-mcps)
|
||||
- [Authoring conventions](#authoring-conventions)
|
||||
- [Repository structure](#repository-structure)
|
||||
- [Trust and security](#trust-and-security)
|
||||
- [Contributing](#contributing)
|
||||
- [Acknowledgments](#acknowledgments)
|
||||
- [Resources](#resources)
|
||||
- [License](#license)
|
||||
|
||||
---
|
||||
|
||||
## What are Claude Skills?
|
||||
|
||||
Claude Skills are reusable capability packages that teach Claude how to handle a specific kind of task with a consistent framework, vocabulary, and output format. Each skill is a folder containing a `SKILL.md` (instructions plus YAML metadata) and optional reference files (templates, checklists, worked examples). Claude loads a skill automatically when a user request matches the skill's description.
|
||||
|
||||
Skills work across [Claude.ai](https://claude.ai), [Claude Code](https://docs.claude.com/en/docs/claude-code/overview), and the [Anthropic API](https://docs.claude.com/en/api/agent-skills). Once you write a skill, it is portable across all three.
|
||||
|
||||
For the official deep dive, see [Anthropic's Agent Skills documentation](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview).
|
||||
|
||||
---
|
||||
|
||||
## What is in this library
|
||||
|
||||
This is not a curated list of other people's skills. It is a single, opinionated library where every skill follows the same structure and conventions, so the skills compose cleanly across a real project lifecycle.
|
||||
|
||||
What you get:
|
||||
|
||||
<!-- COUNT_WHATYOUGET:START -->
|
||||
- **103 skills** across 16 categories, every one with a complete `SKILL.md` and at least one reference file
|
||||
- **490 reference files** (templates, checklists, decision matrices, worked examples)
|
||||
<!-- COUNT_WHATYOUGET:END -->
|
||||
- **Stack-agnostic.** Works on any web stack. The only named-tool exception is the SEO audit suite, which assumes the Ahrefs MCP.
|
||||
- **Future-proof.** Principles over tools. Stable concepts over trending techniques. References to durable specs (W3C, WHATWG, Schema.org, MDN, NN/g, WCAG) over content that ages with each algorithm update.
|
||||
- **Uniform structure.** Every skill uses the same section order, the same tone, and the same authoring conventions. Predictable in, predictable out.
|
||||
- **Composable.** Skills reference each other. `creative-brief` points to `brand-voice`. `incident-response` points to `monitoring-and-alerting`. Each skill's "When NOT to use" tells you which sibling fits your adjacent work.
|
||||
|
||||
Highlight categories: brand strategy and identity, design systems, content production with full Tier 1 and Tier 2 coverage, full SEO suite (foundation plus Ahrefs MCP-powered audit suite), product management with experimentation and gap-closing tracks, growth tooling for interactive web tools, paid media discipline, frontend dev and accessibility, performance and QA, launch and incident ops, UX research, plus a meta-skill that teaches you to write your own.
|
||||
|
||||
---
|
||||
|
||||
## Featured skills
|
||||
|
||||
<!-- FEATURED_SKILLS:START -->
|
||||
Six entry-point skills, one per audience track. Run any of these standalone, or compose them with the rest of the catalog.
|
||||
|
||||
| Skill | What it does |
|
||||
|---|---|
|
||||
| [`creative-direction`](skills/creative-direction/SKILL.md) (Brand and creative) | Four-axis brief (tone, aesthetic, audience, sensory ambition) that gives every downstream skill a coherent direction |
|
||||
| [`experiment-design`](skills/experiment-design/SKILL.md) (PM, experimentation) | From hypothesis to decision: sample size, duration, segment analysis, and the failure modes that produce wrong shipping calls |
|
||||
| [`feature-launch-playbook`](skills/feature-launch-playbook/SKILL.md) (PM, gap-closing) | The discipline of launching a feature well: positioning, internal alignment, customer comms, enablement, rollout, monitoring |
|
||||
| [`pillar-content-architecture`](skills/pillar-content-architecture/SKILL.md) (Content) | Hub-and-cluster topical authority: pillar selection, cluster planning, internal linking, refresh discipline |
|
||||
| [`landing-page-copy`](skills/landing-page-copy/SKILL.md) (Marketing) | Landing pages, sales pages, hero-to-CTA flow with copy that converts |
|
||||
| [`funnel-flow-architecture`](skills/funnel-flow-architecture/SKILL.md) (Growth tooling) | Cross-tool conversion flows architected to match the audience and the funnel stage |
|
||||
<!-- FEATURED_SKILLS:END -->
|
||||
|
||||
---
|
||||
|
||||
## See it in action
|
||||
|
||||
<strong><a href="https://rampstack.co/showcase/creative-direction" target="_blank" rel="noopener">The creative-direction skill rendered as a live showcase →</a></strong>
|
||||
|
||||
Forty-two fictional brands generated from briefs that all use the same skill. Each is a fully styled brand site, not a mockup. The showcase demonstrates what the four-axis framework produces in practice and lets you filter by axis position to see how each combination renders.
|
||||
|
||||
<p align="center">
|
||||
<picture>
|
||||
<source media="(max-width: 640px)" srcset="assets/showcase/creative-direction-highlight-mobile.jpg">
|
||||
<img src="assets/showcase/creative-direction-highlight-desktop.jpg" alt="Creative Direction skill highlight diagram. Navy header card reads 'Impactful Creative Direction' with the subtitle 'Direction for art, taste, and style'. Four quadrants below show: Framework Axes 4 (Tone, Aesthetic, Relationship, Sensory), Framework Positions 16 (each axis combines into 16 distinct positions), Example Treatments 42 (Pulse, Bloom, Forge, Observatory, and 38 others), and Possible Compositions infinity (Motion: Static, Light, Medium, High). Caption reads 'No templates, only guided outputs.'">
|
||||
</picture>
|
||||
</p>
|
||||
|
||||
<p align="center">
|
||||
<img src="assets/showcase/showcase-grid-hero.png" alt="Showcase grid of brand archetypes including Pulse, Volt, Anode, Drift, and others, with type and motion intensity filter pills above the cards." />
|
||||
</p>
|
||||
|
||||
### Filter by any axis position
|
||||
|
||||
The skill defines four axes: tone, aesthetic, relationship, sensory. The showcase lets you filter by any combination and see which examples match. Pre-filtered URLs deep-link from the [SKILL.md](skills/creative-direction/SKILL.md) and [axes-explained reference](skills/creative-direction/references/axes-explained.md), so you can read about a position and click straight through to the rendered examples.
|
||||
|
||||
<p align="center">
|
||||
<img src="assets/showcase/showcase-filter-active.png" alt="Showcase grid filtered by Tone equals Provocative and Sensory equals Resonant, showing eight matching brand cards with the axis disclosure auto-expanded." />
|
||||
</p>
|
||||
|
||||
### The empty state is the lesson
|
||||
|
||||
The framework is generative. The showcase is illustrative. Most rare-but-powerful combinations are valid creative choices that simply have not been built yet. Set Provocative + Editorial Restrained + Coach + Resonant and the grid is empty.
|
||||
|
||||
<p align="center">
|
||||
<img src="assets/showcase/showcase-empty-state.png" alt="Showcase grid with all four axis filters set to Provocative, Editorial Restrained, Coach, and Resonant, showing zero matching examples and the empty state copy: No example yet. The framework allows this combination, it just hasn't been built as one of the thirty worked examples." />
|
||||
</p>
|
||||
|
||||
### The framework's range
|
||||
|
||||
Same skill, same brief format. Four completely different visual systems. Notice that Pulse and Bloom share identical axis positions yet read as opposite visual languages. The reference brands and aesthetic interpretation do the rest.
|
||||
|
||||
<table>
|
||||
<tr>
|
||||
<td width="50%"><img src="assets/showcase/archetype-pulse.png" alt="Pulse music streaming brand. Saturated gradient hero with the headline 'Sound that moves with you' and pink-to-cyan equalizer bars below." /></td>
|
||||
<td width="50%"><img src="assets/showcase/archetype-forge-fitness.png" alt="Forge boutique fitness studio. Dark industrial hero with intense typography and motivational copy." /></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>Pulse</strong> · music streaming<br/><em>Sound that moves with you.</em><br/>Playful / Expressive Maximalist / Companion / Resonant<br/><a href="https://rampstack.co/showcase/creative-direction/pulse-music" target="_blank" rel="noopener">See Pulse demo example →</a></td>
|
||||
<td><strong>Forge</strong> · boutique fitness<br/><em>Show up. Get hammered.</em><br/>Provocative / Expressive Maximalist / Coach / Resonant<br/><a href="https://rampstack.co/showcase/creative-direction/forge-fitness" target="_blank" rel="noopener">See Forge demo example →</a></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><img src="assets/showcase/archetype-bloom-soda.png" alt="Bloom adaptogenic soda brand. Peachy gradient hero with tri-color headline 'Soda that loves you back' and a strawberries-around-soda-can product photo." /></td>
|
||||
<td><img src="assets/showcase/archetype-observatory-editorial.png" alt="Observatory Editorial. Cream paper hero with restrained serif headline 'An observability tool for the engineers who already know what they are doing'." /></td>
|
||||
</tr>
|
||||
<tr>
|
||||
<td><strong>Bloom</strong> · adaptogenic soda<br/><em>Soda that loves you back.</em><br/>Playful / Expressive Maximalist / Companion / Resonant<br/><a href="https://rampstack.co/showcase/creative-direction/bloom-soda" target="_blank" rel="noopener">See Bloom demo example →</a></td>
|
||||
<td><strong>Observatory Editorial</strong> · observability tool<br/><em>An open-source tool that respects engineer time.</em><br/>Conversational / Editorial Restrained / Peer / Considered<br/><a href="https://rampstack.co/showcase/creative-direction/observatory-editorial" target="_blank" rel="noopener">See Observatory demo example →</a></td>
|
||||
</tr>
|
||||
</table>
|
||||
|
||||
<p align="center">
|
||||
<strong><a href="https://rampstack.co/showcase/creative-direction" target="_blank" rel="noopener">See all the brands in the showcase →</a></strong>
|
||||
</p>
|
||||
|
||||
### Run this on your own brand
|
||||
|
||||
The creative-direction skill lives at [`skills/creative-direction/`](skills/creative-direction/). Install it (see below), give Claude a project name and a few inspiration references, and the skill walks you through producing a brief that downstream skills can consume. The brand sites in the showcase were built from briefs of exactly that shape.
|
||||
|
||||
---
|
||||
|
||||
## Logo design in action
|
||||
|
||||
The logo-design skill is rendered on rampstack.co as two parallel surfaces. The variant explorer goes deep on one brand at a time: a primary mark, variants across architectures, applied contexts. The taxonomy gallery goes wide across the architecture space: ten fictional marks demonstrating eight mark architectures (wordmark, lockup, monogram, letterform-as-symbol, abstract, pictorial, combination, emblem). Same skill, two different lenses.
|
||||
|
||||
<p align="center">
|
||||
<picture>
|
||||
<source media="(max-width: 640px)" srcset="assets/showcase/logo-design-highlight-mobile.jpg">
|
||||
<img src="assets/showcase/logo-design-highlight-desktop.jpg" alt="Logo Design skill highlight diagram. Navy header card reads 'Bespoke Logo Design' with the subtitle 'Bringing brands to life.' Below the header, a simulated construction guide shows a stylised letterform B rendered against gridlines, with a Golden Ratio overlay, Primary Curve and Secondary Shape callouts, a Kerning marker, and a six-swatch color palette. Three columns at the bottom show: Verticals (Tech, Finance, Healthcare, Retail), Brand Voice (Trustworthy, Innovative, Premium, Approachable), and Architectures (Monogram, Wordmark, Emblem, Abstract).">
|
||||
</picture>
|
||||
</p>
|
||||
|
||||
### Per-brand depth
|
||||
|
||||
<strong><a href="https://rampstack.co/showcase/logo-design" target="_blank" rel="noopener">The variant explorer →</a></strong>
|
||||
|
||||
Each brand has a primary mark plus variants across architectures and applied contexts. The logo-design skill walks through the discipline of choosing one architecture and rendering it consistently across the system the brand will actually use.
|
||||
|
||||
<p align="center">
|
||||
<picture>
|
||||
<source media="(max-width: 640px)" srcset="assets/showcase/logo-design-showcase-mobile.png">
|
||||
<img src="assets/showcase/logo-design-showcase-desktop.png" alt="Logo design variant explorer showing six fictional brand cards in a three-by-two grid: Whitfield Carter (legal counsel lockup), Wren and Bough (consumer goods lockup), Highline (hospitality wordmark), Sentinel (tech and AI symbol-only), Lacuna (fashion wordmark), and Roost (restaurant lockup). Each card pairs a primary mark with three classification chips for architecture, typographic register, and category, plus a four-variants and five-application-contexts subtext.">
|
||||
</picture>
|
||||
</p>
|
||||
|
||||
The brands are filterable by architecture, typographic register, and category. The intent is reference work, not consumable templates.
|
||||
|
||||
### Architectural taxonomy
|
||||
|
||||
<strong><a href="https://rampstack.co/showcase/logos" target="_blank" rel="noopener">The marks gallery →</a></strong>
|
||||
|
||||
Ten fictional marks across eight mark architectures: wordmark, lockup, monogram, letterform-as-symbol, abstract, pictorial, combination, emblem. The taxonomy makes the architectural distinctions concrete by showing all eight side-by-side, with three wordmarks at three typographic registers so the architectural label does less work than the execution.
|
||||
|
||||
<p align="center">
|
||||
<picture>
|
||||
<source media="(max-width: 640px)" srcset="assets/showcase/marks-showcase-mobile.png">
|
||||
<img src="assets/showcase/marks-showcase-desktop.png" alt="Marks gallery showing six fictional brand cards in a three-by-two grid: knurl (lowercase serif wordmark with knurled texture), TARSUS (uppercase sans lockup with stacked-bar mark), PLINTH (classical serif inside a double-lined emblem frame), Caval (italic horse silhouette plus italic wordmark combination), Ostend (flowing OS monogram resolving to a single connected glyph), and GLINT (high-contrast Didone wordmark with hairline I crossbar). Each card carries the brand name, descriptor, and three classification chips for mark architecture, vertical, and brand voice.">
|
||||
</picture>
|
||||
</p>
|
||||
|
||||
Filter by architecture, vertical, or brand voice; click any mark card to read its design rationale.
|
||||
|
||||
---
|
||||
|
||||
## Reference build in action
|
||||
|
||||
The full catalog rendered as a 4-phase reference build: blank brief through deployed audited launch site. Threshold is a fictional PLG onboarding analytics product, but the research, brand foundations, build, and audit findings are all real. The reference build is the catalog's single strongest demonstration of how the skills compose end-to-end.
|
||||
|
||||
<p align="center">
|
||||
<picture>
|
||||
<source media="(max-width: 640px)" srcset="assets/showcase/reference-build-highlight-mobile.png">
|
||||
<img src="assets/showcase/reference-build-highlight-desktop.png" alt="Reference build hero card. Navy header card reads 'Reference Build' with subtitle 'A fictional B2B SaaS launch, end-to-end.' Below, four white phase cards arranged in a 2x2 grid: Phase 01 Strategy and Research with caption 'Real Ahrefs research applied to a fictional brief'; Phase 02 Brand and Design with caption 'Working brand system with live tokens and components'; Phase 03 Build and Ship with caption 'Deployed launch microsite at /demo/threshold'; Phase 04 Audit and Optimize with caption 'Real audit findings with applied fixes.' Footer caption reads 'Threshold is fictional. The methodology is not.'">
|
||||
</picture>
|
||||
</p>
|
||||
|
||||
### The four phases
|
||||
|
||||
**[Phase 1: Strategy and research →](https://rampstack.co/walkthroughs/saas-launch-research-and-strategy)**
|
||||
Real Ahrefs keyword research, competitor analysis, content gap audit, and backlink opportunity mapping applied to a fictional B2B SaaS brief. Live data tables sourced from the Ahrefs API.
|
||||
|
||||
**[Phase 2: Brand and design →](https://rampstack.co/walkthroughs/saas-launch-brand-and-design)**
|
||||
Logo system, color and typography tokens, working brand component primitives. The brand system renders live on the walkthrough page in real fonts and tokens, not just described.
|
||||
|
||||
**[Phase 3: Build and ship →](https://rampstack.co/walkthroughs/saas-launch-build-and-ship)**
|
||||
The actual launch microsite built with Next.js using Phase 2's brand foundations. Live at [rampstack.co/demo/threshold](https://rampstack.co/demo/threshold). Persistent demonstration banner; noindex; local-only waitlist form.
|
||||
|
||||
**[Phase 4: Audit and optimize →](https://rampstack.co/walkthroughs/saas-launch-audit-and-optimize)**
|
||||
Real audit on the deployed site using the catalog's audit suite (axe-core, Lighthouse, manual checks). Real findings with severity, real fixes applied, real before/after metrics. The closing chapter where the catalog audits its own output.
|
||||
|
||||
### The deployed result
|
||||
|
||||
The four phases compose into a working microsite at [rampstack.co/demo/threshold](https://rampstack.co/demo/threshold). Real Next.js code, real brand foundations from Phase 2 referenced via cross-route imports, real working multi-step waitlist form (no data stored), persistent demonstration banner, and the inline data visualizations that came out of the post-audit polish pass.
|
||||
|
||||
<p align="center">
|
||||
<picture>
|
||||
<source media="(max-width: 640px)" srcset="assets/showcase/threshold-demo-screenshot-mobile.png">
|
||||
<img src="assets/showcase/threshold-demo-screenshot-desktop.png" alt="Full-page screenshot of the deployed Threshold demo at rampstack.co/demo/threshold. Persistent navy demonstration banner at top reads 'Demonstration · Threshold is a fictional product built to illustrate how the catalog composes from blank brief to deployed launch microsite.' Below, the hero section shows a serif headline 'Know how new users actually get to value' next to a stylized product dashboard mockup with KPI tiles, an activation funnel chart, and recent cohorts comparison. Further down the page: a fictional cohort trust strip, a 'The gap' problem section, a wedge section with inline funnel and time-to-first-value charts, a comparison table against Mixpanel/Amplitude/Heap and Pendo/Userpilot, a 'How it works' section with three connected cards, a multi-step waitlist form, and a FAQ section.">
|
||||
</picture>
|
||||
</p>
|
||||
|
||||
### Why a fictional product
|
||||
|
||||
Real client work cannot be open-sourced; portfolio claims trigger conflict-of-interest concerns in interviews and consulting conversations. A fictional product with a documented brief plus real research, real brand foundations, real working code, and real audit findings produces a teaching artifact that demonstrates methodology without claiming relationships. Threshold is a measurement tool that does not exist; the methodology that built it is the catalog working end-to-end.
|
||||
|
||||
---
|
||||
|
||||
## Getting started
|
||||
|
||||
Skills install in three different places depending on where you use Claude. Pick the platform that matches your workflow.
|
||||
|
||||
### Option 1: Claude.ai (web and desktop)
|
||||
|
||||
If your Claude.ai plan supports custom Skills:
|
||||
|
||||
1. Go to **Settings → Capabilities → Skills**.
|
||||
2. Upload the skill folder you want as a `.zip` (one zip per skill folder containing `SKILL.md` and the `references/` subfolder).
|
||||
3. Enable the skill in the chat interface.
|
||||
|
||||
Claude will load the skill automatically when your request matches its description.
|
||||
|
||||
For current plan availability and the exact upload UI, see [Anthropic's Skills user guide](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview).
|
||||
|
||||
### Option 2: Claude Code (recommended)
|
||||
|
||||
Skills are first-class citizens in Claude Code. Drop them into your skills directory and Claude Code picks them up automatically.
|
||||
|
||||
**User-level skills** (available in every project):
|
||||
|
||||
```bash
|
||||
# macOS / Linux
|
||||
mkdir -p ~/.claude/skills
|
||||
cp -r skills/* ~/.claude/skills/
|
||||
|
||||
# Windows (PowerShell)
|
||||
New-Item -ItemType Directory -Force -Path "$HOME\.claude\skills"
|
||||
Copy-Item -Recurse skills\* "$HOME\.claude\skills\"
|
||||
```
|
||||
|
||||
**Project-level skills** (available only in a specific project):
|
||||
|
||||
```bash
|
||||
mkdir -p .claude/skills
|
||||
cp -r path/to/this-repo/skills/* .claude/skills/
|
||||
```
|
||||
|
||||
Start (or restart) Claude Code. Skills load automatically.
|
||||
|
||||
For exact current paths and config flags, see the [Claude Code documentation](https://docs.claude.com/en/docs/claude-code/overview).
|
||||
|
||||
### Option 3: Anthropic API
|
||||
|
||||
Use Skills programmatically by referencing them in your API calls. Skills must first be uploaded to your workspace (via the Console or API), then referenced by ID when creating messages.
|
||||
|
||||
For the current API surface, request format, and limits, see the [Agent Skills API documentation](https://docs.claude.com/en/api/agent-skills).
|
||||
|
||||
### Want only a few skills?
|
||||
|
||||
You do not have to install all 103. Pick the categories that match your work. The library is modular: each skill stands on its own.
|
||||
|
||||
---
|
||||
|
||||
## Quick example
|
||||
|
||||
Once installed, skills trigger automatically based on your request. You do not have to name the skill or change how you talk to Claude.
|
||||
|
||||
**You ask:**
|
||||
|
||||
> "Our organic traffic dropped 30% last week. Help me figure out why."
|
||||
|
||||
**What happens:**
|
||||
|
||||
Claude recognizes the request matches `seo-traffic-diagnosis`, loads the skill, and walks through its 5-layer root cause framework: confirm the change is real → localize the change → page-level analysis → technical analysis → external analysis. By the end, you have a hypothesis statement, evidence, and an action plan, structured the same way every time.
|
||||
|
||||
**Other natural triggers:**
|
||||
|
||||
- "Help me write a creative brief" → `creative-brief`
|
||||
- "Audit my homepage for SEO" → `seo-onpage`
|
||||
- "We need a backlink audit" → `seo-backlink-audit`
|
||||
- "Plan our content roadmap for Q3" → `seo-content-gap-audit` plus `content-strategy`
|
||||
- "Postmortem template for last night's incident" → `after-action-report`
|
||||
- "How do I write my own skill?" → `skill-creation-walkthrough`
|
||||
|
||||
You can also call a skill explicitly: "Use the `seo-audit-orchestration` skill to run a full audit on example.com."
|
||||
|
||||
---
|
||||
|
||||
## How they compose
|
||||
|
||||
The skills compose into a full project flow:
|
||||
|
||||
```
|
||||
brand-discovery → brand-ideation → brand-identity → brand-style-guide → brand-voice
|
||||
↓
|
||||
creative-brief → information-architecture → content-strategy → design-system
|
||||
↓
|
||||
seo-keyword → seo-content-audit → content-and-copy → landing-page-copy
|
||||
↓
|
||||
seo-onpage → seo-technical → seo-aeo-geo → seo-offpage → seo-competitor
|
||||
↓
|
||||
frontend-component-build → accessibility-audit → performance-optimization
|
||||
↓
|
||||
code-review-web → qa-testing → security-baseline → launch-runbook
|
||||
↓
|
||||
domain-strategy → monitoring-and-alerting → backup-and-disaster-recovery
|
||||
↓
|
||||
incident-response → after-action-report
|
||||
↓
|
||||
analytics-strategy → cro-optimization → ux-research → usability-testing → journey-mapping
|
||||
```
|
||||
|
||||
The SEO audit suite (Ahrefs MCP-powered) wraps around the SEO foundation skills:
|
||||
|
||||
```
|
||||
seo-audit-orchestration
|
||||
├── seo-site-health-audit
|
||||
├── seo-backlink-audit
|
||||
├── seo-keyword-gap-audit
|
||||
├── seo-content-gap-audit
|
||||
├── seo-traffic-diagnosis (also runs standalone for incident-style work)
|
||||
└── seo-rank-tracking (ongoing, feeds the others)
|
||||
```
|
||||
|
||||
The catalog also includes four audience tracks that compose alongside the foundational lifecycle. Each track has its own internal flow:
|
||||
|
||||
**Paid media (Marketing track):**
|
||||
|
||||
```
|
||||
paid-media-strategy → ads-creative-development → ads-performance-analytics
|
||||
```
|
||||
|
||||
Pairs with the paid media platforms in the integrations catalog at rampstack.co (Google Ads, Meta, LinkedIn, TikTok, plus Synter as the multi-platform aggregator).
|
||||
|
||||
**Growth tooling (interactive web tools):**
|
||||
|
||||
```
|
||||
funnel-flow-architecture (orchestrator)
|
||||
├── lead-magnet-design (capture)
|
||||
├── calculator-design (capture / activate)
|
||||
├── quiz-and-assessment-design (capture / activate)
|
||||
├── multi-step-form-design (activate)
|
||||
├── chatbot-flow-design (activate)
|
||||
├── onboarding-wizard-design (activate)
|
||||
├── interactive-product-tour (activate / convert)
|
||||
├── upgrade-flow-design (convert)
|
||||
├── scheduler-and-booking-design (convert)
|
||||
├── comparison-tool-design (convert)
|
||||
└── product-configurator-design (convert)
|
||||
```
|
||||
|
||||
`funnel-flow-architecture` is the orchestrator: it sequences which interactive tool fits each audience and funnel stage, distinguishing matched-funnels from kitchen-sink-funnels.
|
||||
|
||||
**Tier 2 content lifecycle:**
|
||||
|
||||
```
|
||||
content-strategy → pillar-content-architecture → content-brief-authoring
|
||||
↓
|
||||
content-and-copy / long-form-content-frameworks / email-sequences
|
||||
↓
|
||||
editorial-qa → content-distribution → programmatic-seo
|
||||
↓
|
||||
content-refresh-system → content-repurposing → content-migration
|
||||
```
|
||||
|
||||
`ai-content-collaboration` is a workflow layer that runs across every phase rather than a single step. `documentation-strategy` operates continuously alongside the rest.
|
||||
|
||||
**Tier 2 product management (two parallel tracks):**
|
||||
|
||||
```
|
||||
Experimentation track:
|
||||
experiment-design → feature-flagging → experimentation-platform-orchestrator
|
||||
↓
|
||||
experimentation-analytics → data-warehouse-experimentation
|
||||
|
||||
Gap-closing track:
|
||||
pm-spec-writing → roadmap-planning → feature-launch-playbook
|
||||
↓
|
||||
beta-program-management → product-analytics-setup → integration-orchestrator
|
||||
```
|
||||
|
||||
The experimentation track ships changes with statistical discipline; the gap-closing track ships features with operational discipline. Both compose with the foundational lifecycle above.
|
||||
|
||||
Operations, cross-cutting, and team skills (`stakeholder-communication`, `documentation-strategy`, `vendor-evaluation`, `team-onboarding-playbook`, `dependency-management`, `cost-optimization`, etc.) cut across every track.
|
||||
|
||||
You can also pull individual skills for one-off work. Need just a backlink audit? Use `seo-backlink-audit`. Need to write a creative brief? Use `creative-brief`. Each skill stands on its own.
|
||||
|
||||
---
|
||||
|
||||
## How the catalog connects
|
||||
|
||||
The skills compose with the tools your team already uses. 103 skills at the center; 35 integrations across 6 integration categories radiating out via MCPs.
|
||||
|
||||
<p align="center">
|
||||
<picture>
|
||||
<source media="(max-width: 640px)" srcset="docs/architecture-mobile.jpg">
|
||||
<img src="docs/architecture-wide.jpg" alt="RampStack architecture diagram. A central navy hub card shows the RampStack mark with the subtitle 'Stack-agnostic methodology'. Six category cards radiate out: Workflow with 6 integrations (Jira, Linear, Notion, Figma, GitHub), Experimentation with 11 integrations (Statsig, PostHog, Optimizely, Amplitude), SEO Intelligence with 3 integrations (Ahrefs, Semrush, Similarweb), Paid Media with 5 integrations (Google Ads, Meta Ads, LinkedIn, TikTok, Synter), Content and SEO with 5 integrations (Webflow, Contentful, Frase, Profound, AirOps), and Data and Analytics with 5 integrations (BigQuery, Snowflake, Mixpanel, dbt, Hex).">
|
||||
</picture>
|
||||
</p>
|
||||
|
||||
---
|
||||
|
||||
## Surfaces
|
||||
|
||||
<!-- SURFACES:START -->
|
||||
This catalog is the open-source methodology layer. Commercial surfaces at [rampstack.co](https://rampstack.co) extend it:
|
||||
|
||||
- **[Skills directory](https://rampstack.co/skills)**. Every skill on a curated landing surface with audience tracks, search, and category navigation.
|
||||
- **[Walkthroughs](https://rampstack.co/walkthroughs)**. Multi-skill recipes that orchestrate skill clusters end-to-end. Use these when one skill is not enough and a packaged sequence is.
|
||||
- **[Integrations directory](https://rampstack.co/integrations)**. Curated MCPs, APIs, and tooling that the skills hook into.
|
||||
- **[Showcase](https://rampstack.co/showcase)**. Real brand sites built from these skills, with the brief that produced each one.
|
||||
|
||||
The skills in this repository remain free, open-source, and stack-agnostic. The surfaces above are how the same methodology is delivered as a product.
|
||||
<!-- SURFACES:END -->
|
||||
|
||||
---
|
||||
|
||||
## Design principles
|
||||
|
||||
claude-skills follows the [Agent Skills Specification](https://agentskills.io), the open standard for portable AI agent skills originally developed by Anthropic and adopted across the AI tooling ecosystem (Claude Code, OpenAI Codex, Gemini CLI, GitHub Copilot, Cursor, VS Code, Goose, Spring AI, and 30+ other platforms as of early 2026).
|
||||
|
||||
Beyond the format itself, the catalog is designed around three principles aligned with the guidance Anthropic publishes in [Building effective agents](https://www.anthropic.com/engineering/building-effective-agents):
|
||||
|
||||
**Simplicity.** Each skill covers one focused capability rather than trying to be a multi-purpose document. A roadmap-planning skill plans roadmaps. A keyword-research skill researches keywords. Composing them together produces complex workflows; mixing them inside one skill produces unreliable ones.
|
||||
|
||||
**Transparency.** Every skill declares its scope, dependencies, and expected behavior in machine-readable YAML frontmatter. The catalog is inspectable by tooling, not just by humans reading prose.
|
||||
|
||||
**Quality contracts via tooling.** Structural and content quality is enforced through automated checks (run `python .github/scripts/lint_skills.py`) rather than convention alone. Every skill is validated against a schema. Every catalog change is validated in CI.
|
||||
|
||||
Skills in this catalog are designed to compose into the common agentic workflow patterns Anthropic documents: prompt chaining (sequential steps), routing (classify and direct), parallelization (sectioning or voting), orchestrator-workers (dynamic delegation), and evaluator-optimizer (iterative refinement).
|
||||
|
||||
Because the catalog conforms to the open Agent Skills standard, skills work across any platform supporting the specification without modification.
|
||||
|
||||
## Family repos
|
||||
|
||||
claude-skills is the parent catalog. Curated subsets and companion repos focus on specific specialties:
|
||||
|
||||
| Repo | Focus | Skills |
|
||||
|---|---|---|
|
||||
| [claude-skills](https://github.com/rampstackco/claude-skills) | Full catalog (you are here) | 103 |
|
||||
| [claude-skills-starter](https://github.com/rampstackco/claude-skills-starter) | General-purpose lite | 14 |
|
||||
| [claude-skills-seo](https://github.com/rampstackco/claude-skills-seo) | SEO consulting | 12 |
|
||||
| [claude-skills-pm](https://github.com/rampstackco/claude-skills-pm) | Product management | 12 |
|
||||
| [claude-skills-widgets](https://github.com/rampstackco/claude-skills-widgets) | UI patterns + components | 65 + 32 |
|
||||
| [awesome-claude-skills](https://github.com/rampstackco/awesome-claude-skills) | Curated discovery list | n/a |
|
||||
|
||||
Each family repo is MIT-licensed, conforms to the Agent Skills Specification, and is stack-agnostic. Use the full catalog for breadth; use a specialty subset when working in one domain.
|
||||
|
||||
---
|
||||
|
||||
<!-- COUNT_CATALOG_HEADER:START -->
|
||||
## The 103-skill catalog
|
||||
<!-- COUNT_CATALOG_HEADER:END -->
|
||||
|
||||
<!-- COUNT_CATALOG_INTRO:START -->
|
||||
All 103 skills are shipped. Each has a complete SKILL.md plus at least one reference file (template, checklist, or playbook).
|
||||
<!-- COUNT_CATALOG_INTRO:END -->
|
||||
|
||||
<!-- AUTO-GENERATED CATALOG: do not edit by hand. Run scripts/generate_readme_catalog.py --write -->
|
||||
<!-- CATALOG:START -->
|
||||
### Strategy and discovery (5)
|
||||
|
||||
| Skill | What it does |
|
||||
|---|---|
|
||||
| [`brand-discovery`](skills/brand-discovery/SKILL.md) | Audience research, competitive scan, positioning territory exploration |
|
||||
| [`creative-brief`](skills/creative-brief/SKILL.md) | Project briefs that align stakeholders before work starts |
|
||||
| [`creative-direction`](skills/creative-direction/SKILL.md) | Four-axis aesthetic brief (tone, aesthetic, audience, sensory ambition) for cross-skill coherence |
|
||||
| [`information-architecture`](skills/information-architecture/SKILL.md) | Sitemap, navigation, URL structure, content types, taxonomy |
|
||||
| [`content-strategy`](skills/content-strategy/SKILL.md) | Editorial strategy, content calendar, topical authority planning |
|
||||
|
||||
### Brand (7)
|
||||
|
||||
| Skill | What it does |
|
||||
|---|---|
|
||||
| [`brand-ideation`](skills/brand-ideation/SKILL.md) | Naming, positioning territories, mood directions, narrative angles |
|
||||
| [`brand-identity`](skills/brand-identity/SKILL.md) | Logo system, color, typography, imagery, iconography, motion |
|
||||
| [`brand-style-guide`](skills/brand-style-guide/SKILL.md) | The canonical reference document for the full brand system |
|
||||
| [`brand-voice`](skills/brand-voice/SKILL.md) | Voice attributes, tone shifts, vocabulary, paired-example library |
|
||||
| [`brand-archetype-system`](skills/brand-archetype-system/SKILL.md) | 12 archetype defaults across 18 verticals: color, type, voice, imagery starters |
|
||||
| [`logo-design`](skills/logo-design/SKILL.md) | Logo variants across architectures (wordmark, lockup, monogram, letterform-as-symbol), with rationale and application specs |
|
||||
| [`creative-brief-selector`](skills/creative-brief-selector/SKILL.md) | Live-reference-grounded creative briefs with divergence check against prior builds |
|
||||
|
||||
### Design (4)
|
||||
|
||||
| Skill | What it does |
|
||||
|---|---|
|
||||
| [`design-system`](skills/design-system/SKILL.md) | Component library, design tokens, design system documentation |
|
||||
| [`design-standards`](skills/design-standards/SKILL.md) | Production-grade page and component design standards |
|
||||
| [`art-direction`](skills/art-direction/SKILL.md) | Photography, illustration, and visual direction for campaigns |
|
||||
| [`vertical-site-conventions`](skills/vertical-site-conventions/SKILL.md) | Vertical page and site composition built to the experience bar |
|
||||
|
||||
### Content (13)
|
||||
|
||||
| Skill | What it does |
|
||||
|---|---|
|
||||
| [`pillar-content-architecture`](skills/pillar-content-architecture/SKILL.md) | Hub-level content architecture: pillar topic selection, cluster planning, internal linking, URL structure, pillar and cluster page anatomy, topical authority signals, refresh discipline |
|
||||
| [`content-brief-authoring`](skills/content-brief-authoring/SKILL.md) | Per-piece editorial brief: target keyword, intent, audience, outline, entity coverage, internal linking, success criteria, and the discipline that distinguishes useful briefs from bloat |
|
||||
| [`content-and-copy`](skills/content-and-copy/SKILL.md) | Website copy, blog content, content production frameworks |
|
||||
| [`landing-page-copy`](skills/landing-page-copy/SKILL.md) | Landing pages, sales pages, hero-to-CTA flow |
|
||||
| [`email-sequences`](skills/email-sequences/SKILL.md) | Onboarding flows, lifecycle campaigns, transactional copy |
|
||||
| [`programmatic-seo`](skills/programmatic-seo/SKILL.md) | Designing pSEO programs that work: data sources, template design, quality control at scale, internal linking, crawl budget, AEO/GEO patterns, refresh discipline, and when pSEO is and is not the right answer |
|
||||
| [`editorial-qa`](skills/editorial-qa/SKILL.md) | Pre-publish QA framework: brief adherence, voice consistency, fact accuracy, AI-content audit, AEO/SEO compliance, sampling at scale, and the workflow that distinguishes catch-problems QA from process theater |
|
||||
| [`ai-content-collaboration`](skills/ai-content-collaboration/SKILL.md) | How humans and AI compose in content workflows: participation boundaries, hybrid patterns, voice ownership, the AI slop problem, disclosure and transparency, team calibration, and the ethics of honest AI-assisted production |
|
||||
| [`long-form-content-frameworks`](skills/long-form-content-frameworks/SKILL.md) | Structural patterns for individual long-form pieces (case studies, whitepapers, research reports, definitive guides, manifestos, ebooks, long-form tutorials) that distinguish publication-quality work from bloggy-long padding or academic bloat |
|
||||
| [`content-refresh-system`](skills/content-refresh-system/SKILL.md) | Systematic content refresh: quarterly audits, refresh prioritization, refresh-vs-merge-vs-delete decisions, the lifecycle discipline that distinguishes intentional programs from set-and-forget decay |
|
||||
| [`content-repurposing`](skills/content-repurposing/SKILL.md) | Cross-format content adaptation: one piece becomes many (blog series, email, social, webinar, podcast, video) with per-format adaptation rather than mass-blast that ignores medium constraints |
|
||||
| [`content-distribution`](skills/content-distribution/SKILL.md) | Content distribution discipline: owned, earned, and paid channels matched to audience and content type. Channel-fit decisions, distribution cadence, the strategic alternative to spam-everywhere or hope-and-pray |
|
||||
| [`evidence-based-reviews`](skills/evidence-based-reviews/SKILL.md) | Evidence tiers, methodology disclosure, honest review claims |
|
||||
|
||||
### SEO foundation (7)
|
||||
|
||||
Tool-agnostic SEO skills. These define the conceptual frameworks. The SEO audit suite below adds the Ahrefs MCP-powered execution layer.
|
||||
|
||||
| Skill | What it does |
|
||||
|---|---|
|
||||
| [`seo-onpage`](skills/seo-onpage/SKILL.md) | Single-page audits and optimization across 8 dimensions |
|
||||
| [`seo-technical`](skills/seo-technical/SKILL.md) | Crawlability, indexability, rendering, schema, page experience |
|
||||
| [`seo-keyword`](skills/seo-keyword/SKILL.md) | Discovery, intent classification, clustering, prioritization |
|
||||
| [`seo-competitor`](skills/seo-competitor/SKILL.md) | SERP overlap, content gaps, backlink gaps, technical comparison |
|
||||
| [`seo-offpage`](skills/seo-offpage/SKILL.md) | Link building, digital PR, citations, linkable assets |
|
||||
| [`seo-content-audit`](skills/seo-content-audit/SKILL.md) | Keep/update/merge/redirect/delete decisions across a site |
|
||||
| [`seo-aeo-geo`](skills/seo-aeo-geo/SKILL.md) | AI search optimization, llms.txt, extraction-friendly content |
|
||||
|
||||
### SEO audit suite (Ahrefs MCP-powered) (7)
|
||||
|
||||
End-to-end SEO audit workflows that pull data from the Ahrefs MCP and produce concrete deliverables. These skills assume the Ahrefs MCP is connected.
|
||||
|
||||
| Skill | What it does |
|
||||
|---|---|
|
||||
| [`seo-audit-orchestration`](skills/seo-audit-orchestration/SKILL.md) | Master orchestrator: sequences the suite, produces a rollup report |
|
||||
| [`seo-backlink-audit`](skills/seo-backlink-audit/SKILL.md) | Profile health, anchor mix, toxic links, reclamation, gap analysis |
|
||||
| [`seo-keyword-gap-audit`](skills/seo-keyword-gap-audit/SKILL.md) | Competitor keyword gaps with opportunity scoring and clustering |
|
||||
| [`seo-content-gap-audit`](skills/seo-content-gap-audit/SKILL.md) | Missing topics, thin coverage, outdated content, decay diagnosis |
|
||||
| [`seo-traffic-diagnosis`](skills/seo-traffic-diagnosis/SKILL.md) | Diagnose drops, stalls, or wins via 5-layer root cause analysis |
|
||||
| [`seo-site-health-audit`](skills/seo-site-health-audit/SKILL.md) | Triage Ahrefs Site Audit findings by SEO impact, not severity |
|
||||
| [`seo-rank-tracking`](skills/seo-rank-tracking/SKILL.md) | Setup, baseline, segmentation, alerting, dashboarding |
|
||||
|
||||
### Product (13)
|
||||
|
||||
| Skill | What it does |
|
||||
|---|---|
|
||||
| [`pm-spec-writing`](skills/pm-spec-writing/SKILL.md) | PRDs, user stories, acceptance criteria, dev briefs |
|
||||
| [`roadmap-planning`](skills/roadmap-planning/SKILL.md) | Quarterly planning, prioritization, dependency mapping |
|
||||
| [`integration-orchestrator`](skills/integration-orchestrator/SKILL.md) | Sequence creative-direction work across phases, gates, handoffs, and QA verification |
|
||||
| [`experiment-design`](skills/experiment-design/SKILL.md) | Hypothesis to decision: sample size, duration, segment analysis, interpretation, and the failure modes that produce wrong shipping calls |
|
||||
| [`feature-flagging`](skills/feature-flagging/SKILL.md) | Flags as production infrastructure: types, naming, lifecycle, targeting, rollout, stale flag cleanup, governance |
|
||||
| [`experimentation-analytics`](skills/experimentation-analytics/SKILL.md) | Read result panels without fooling yourself: confidence intervals, p-values, multiple testing, sequential testing, CUPED, ratio metrics, network effects, dashboard reconciliation |
|
||||
| [`experimentation-platform-orchestrator`](skills/experimentation-platform-orchestrator/SKILL.md) | Pick the right experimentation platform, migrate when wrong, coordinate when multi-platform: a decision framework for Statsig, PostHog, GrowthBook, Optimizely, Amplitude, Eppo, Kameleoon |
|
||||
| [`product-analytics-setup`](skills/product-analytics-setup/SKILL.md) | Instrument product analytics correctly: event taxonomy, properties, naming conventions, schema versioning, funnels, retention cohorts, North Star selection, and the instrumentation debt that compounds without discipline |
|
||||
| [`data-warehouse-experimentation`](skills/data-warehouse-experimentation/SKILL.md) | Run experiments out of the warehouse: SQL assignment, exposure logs, dbt metric definitions, statistical analysis, variance reduction with CUPED, sequential testing, and the operational tradeoffs vs platforms |
|
||||
| [`feature-launch-playbook`](skills/feature-launch-playbook/SKILL.md) | The operational discipline of launching a feature well: positioning, internal alignment, customer comms, sales enablement, support readiness, rollout strategy, monitoring, and post-launch measurement |
|
||||
| [`jtbd-framing`](skills/jtbd-framing/SKILL.md) | Jobs-to-be-Done framework. Job statements, struggling moments, hire/fire criteria, the difference between feature-thinking and job-thinking. Honest about where JTBD earns its keep and where it becomes performative |
|
||||
| [`okr-design`](skills/okr-design/SKILL.md) | OKR design discipline. Outcome statements, key results, scoring, mid-quarter recalibration. Distinguishes sandbagged OKRs (always hit, useless) from aspirational fantasy (impossible, demoralizing) from stretch OKRs (genuine ambition with quarterly accountability) |
|
||||
| [`beta-program-management`](skills/beta-program-management/SKILL.md) | Running betas that produce real signal. Participant selection, structured feedback, beta-to-GA decisions. Distinguishes soft-launch (no structure) from kitchen-sink (everyone in) from structured-beta (calibrated cohort with intentional feedback loops) |
|
||||
|
||||
### Development (4)
|
||||
|
||||
| Skill | What it does |
|
||||
|---|---|
|
||||
| [`code-review-web`](skills/code-review-web/SKILL.md) | PR review, build error diagnosis, security and quality checks |
|
||||
| [`frontend-component-build`](skills/frontend-component-build/SKILL.md) | Component architecture, props design, accessibility from the start |
|
||||
| [`accessibility-audit`](skills/accessibility-audit/SKILL.md) | WCAG compliance audit with remediation plan |
|
||||
| [`performance-optimization`](skills/performance-optimization/SKILL.md) | Core Web Vitals, asset optimization, render performance |
|
||||
|
||||
### Quality assurance (1)
|
||||
|
||||
| Skill | What it does |
|
||||
|---|---|
|
||||
| [`qa-testing`](skills/qa-testing/SKILL.md) | Pre-launch QA, regression testing, cross-browser checks |
|
||||
|
||||
### Operations (9)
|
||||
|
||||
| Skill | What it does |
|
||||
|---|---|
|
||||
| [`launch-runbook`](skills/launch-runbook/SKILL.md) | Go-live runbook, DNS cutover, deploy day procedures |
|
||||
| [`incident-response`](skills/incident-response/SKILL.md) | Incident triage, comms, mitigation, escalation |
|
||||
| [`after-action-report`](skills/after-action-report/SKILL.md) | Post-mortems, retros, learnings documentation |
|
||||
| [`domain-strategy`](skills/domain-strategy/SKILL.md) | DNS architecture, redirects, registrars, multi-domain portfolios |
|
||||
| [`monitoring-and-alerting`](skills/monitoring-and-alerting/SKILL.md) | SLO design, uptime checks, alert routing, on-call rotations |
|
||||
| [`backup-and-disaster-recovery`](skills/backup-and-disaster-recovery/SKILL.md) | RPO/RTO targets, backup strategy, restoration drills |
|
||||
| [`security-baseline`](skills/security-baseline/SKILL.md) | HTTPS, security headers, CSP, secrets management, vulnerability scans |
|
||||
| [`email-deliverability`](skills/email-deliverability/SKILL.md) | DMARC, SPF, DKIM, sender reputation, deliverability monitoring |
|
||||
| [`media-asset-management`](skills/media-asset-management/SKILL.md) | Image pipelines, video hosting, asset libraries, format selection |
|
||||
|
||||
### Growth (2)
|
||||
|
||||
| Skill | What it does |
|
||||
|---|---|
|
||||
| [`analytics-strategy`](skills/analytics-strategy/SKILL.md) | Measurement frameworks, dashboard design, event taxonomy |
|
||||
| [`cro-optimization`](skills/cro-optimization/SKILL.md) | Hypothesis-driven testing, conversion optimization |
|
||||
|
||||
### Growth tooling (12)
|
||||
|
||||
Interactive web tools that turn visitors into leads. Lead magnets, calculators, quizzes, multi-step forms, chatbots, and the cross-tool funnel architecture that orchestrates them.
|
||||
|
||||
| Skill | What it does |
|
||||
|---|---|
|
||||
| [`lead-magnet-design`](skills/lead-magnet-design/SKILL.md) | Designing gated content that earns the email. Distinguishes thin-bait (overpromises, underdelivers) from kitchen-sink-resource (everything, helps with nothing) from earned-value-magnet (delivers standalone value while qualifying the lead) |
|
||||
| [`calculator-design`](skills/calculator-design/SKILL.md) | Designing interactive calculators that deliver decision-support value while qualifying leads. Distinguishes vanity-calculator (no real value) from lead-trap (hides answer behind email) from transparent-decision-tool (gives genuine value, captures leads honestly) |
|
||||
| [`quiz-and-assessment-design`](skills/quiz-and-assessment-design/SKILL.md) | Designing quizzes and assessments that produce actionable segmentation. Distinguishes clickbait-quiz (engagement only) from vanity-result (entertaining, not useful) from actionable-segmentation (genuine categorization that drives next-step recommendations) |
|
||||
| [`multi-step-form-design`](skills/multi-step-form-design/SKILL.md) | Designing multi-step forms that respect cognitive load while maintaining completion intent. Distinguishes kitchen-sink-single-page (overwhelms) from progress-theater (steps without genuine staging) from genuinely-staged (each step earns its own page) |
|
||||
| [`chatbot-flow-design`](skills/chatbot-flow-design/SKILL.md) | Designing conversational flows for chatbots and AI agents on websites. Distinguishes scripted-bot (rigid trees, fail edge cases) from hallucinating-bot (LLM without structure, makes things up) from structured-guided-conversation (LLM-powered with intent architecture and fallback discipline) |
|
||||
| [`funnel-flow-architecture`](skills/funnel-flow-architecture/SKILL.md) | Architecting cross-tool conversion flows that match audience and stage. Distinguishes silo-funnels (every tool standalone) from kitchen-sink-funnels (every audience squeezed through one path) from matched-funnels (architecture matched to audience-and-stage) |
|
||||
| [`onboarding-wizard-design`](skills/onboarding-wizard-design/SKILL.md) | Designing first-run product onboarding wizards. Distinguishes tutorial-overload (dump everything upfront) from skip-friendly-empty (skipped onboarding leads to abandoned product) from earned-progressive-disclosure (right things at the right moments) |
|
||||
| [`interactive-product-tour`](skills/interactive-product-tour/SKILL.md) | Designing in-product tours and contextual help. Distinguishes tooltip-spam (every button has a tour stop) from one-and-done (tour shows once, never seen again) from contextual-when-needed (surfaces help at the moment friction occurs) |
|
||||
| [`upgrade-flow-design`](skills/upgrade-flow-design/SKILL.md) | Designing free-to-paid conversion flows. Distinguishes paywall-everywhere (gates everything aggressively) from free-forever-trap (no upgrade path surfaces) from value-triggered-upgrade (paywall surfaces at moments of demonstrated value) |
|
||||
| [`scheduler-and-booking-design`](skills/scheduler-and-booking-design/SKILL.md) | Designing schedulers and booking flows. Distinguishes any-time-friction (no qualification, just a booking link) from interrogation-gate (so much qualification it scares users off) from qualified-fast-path (just enough qualification to set up the call well) |
|
||||
| [`comparison-tool-design`](skills/comparison-tool-design/SKILL.md) | Designing comparison tools that help users decide. Distinguishes feature-list-dump (every feature in a row, no decision support) from hidden-recommendation (biased comparison pretending to be neutral) from honest-comparison-with-guidance (genuine comparison plus opinionated recommendation) |
|
||||
| [`product-configurator-design`](skills/product-configurator-design/SKILL.md) | Designing interactive product configurators. Distinguishes infinite-options (decision paralysis from too many options) from canned-bundles-only (no real customization) from guided-configuration (smart defaults plus meaningful constraints plus escape hatches) |
|
||||
|
||||
### Marketing (3)
|
||||
|
||||
Paid media discipline: strategy, creative, and performance analytics. Pairs with the paid media platforms in the /integrations catalog at rampstack.co.
|
||||
|
||||
| Skill | What it does |
|
||||
|---|---|
|
||||
| [`paid-media-strategy`](skills/paid-media-strategy/SKILL.md) | Hypothesis to spend: channel selection, budget allocation, audience targeting, bid strategy, attribution reality, and the failure modes that burn agency-scale budgets |
|
||||
| [`ads-creative-development`](skills/ads-creative-development/SKILL.md) | Hook patterns, format selection, video pacing, variation systems, testing methodology, fatigue detection, and the platform-specific creative norms that separate ads from clutter |
|
||||
| [`ads-performance-analytics`](skills/ads-performance-analytics/SKILL.md) | Read paid media dashboards without fooling yourself: attribution models, platform reporting quirks, ROAS vs LTV, multi-platform reconciliation, incrementality testing, and the interpretation failures that compound into wasted budget |
|
||||
|
||||
### Research (6)
|
||||
|
||||
| Skill | What it does |
|
||||
|---|---|
|
||||
| [`ux-research`](skills/ux-research/SKILL.md) | Research planning, user interviews, qualitative synthesis |
|
||||
| [`usability-testing`](skills/usability-testing/SKILL.md) | Test design, moderation, findings reports |
|
||||
| [`journey-mapping`](skills/journey-mapping/SKILL.md) | Customer journey maps, service blueprints, friction analysis |
|
||||
| [`discovery-research-synthesis`](skills/discovery-research-synthesis/SKILL.md) | Synthesizing customer interviews, research notes, and support tickets into actionable PM decisions. Distinguishes data-dump (no synthesis) from insight-theater (overpolished narrative) from actionable synthesis (decision-grade clarity) |
|
||||
| [`user-feedback-aggregation`](skills/user-feedback-aggregation/SKILL.md) | Collecting and synthesizing user feedback across channels into continuous decision signal. Triage discipline that distinguishes loudest-voice (whoever complains most) from averaged-noise (every signal weighted equally) from triaged-synthesis (weighted by source quality and decision relevance) |
|
||||
| [`competitor-experience-audit`](skills/competitor-experience-audit/SKILL.md) | Cross-site experience patterns and gaps across a vertical |
|
||||
|
||||
### Cross-cutting workflows (5)
|
||||
|
||||
| Skill | What it does |
|
||||
|---|---|
|
||||
| [`form-strategy`](skills/form-strategy/SKILL.md) | Form design, validation patterns, spam prevention, conversion tuning |
|
||||
| [`content-migration`](skills/content-migration/SKILL.md) | Platform migrations with SEO equity preservation |
|
||||
| [`internationalization`](skills/internationalization/SKILL.md) | Locale strategy, hreflang, translation workflow, RTL design |
|
||||
| [`dependency-management`](skills/dependency-management/SKILL.md) | Package updates, security patches, lockfile hygiene |
|
||||
| [`cost-optimization`](skills/cost-optimization/SKILL.md) | Infrastructure spend audits, rightsizing, contract negotiation |
|
||||
|
||||
### Process and team (5)
|
||||
|
||||
| Skill | What it does |
|
||||
|---|---|
|
||||
| [`stakeholder-communication`](skills/stakeholder-communication/SKILL.md) | Status updates, exec readouts, project communications |
|
||||
| [`documentation-strategy`](skills/documentation-strategy/SKILL.md) | Documentation systems, what to document, maintenance cadence |
|
||||
| [`vendor-evaluation`](skills/vendor-evaluation/SKILL.md) | Tool and vendor selection using a structured rubric |
|
||||
| [`team-onboarding-playbook`](skills/team-onboarding-playbook/SKILL.md) | 30-60-90 onboarding plans for new hires and contractors |
|
||||
| [`skill-creation-walkthrough`](skills/skill-creation-walkthrough/SKILL.md) | The meta-skill: how to write your own custom skills |
|
||||
<!-- CATALOG:END -->
|
||||
|
||||
---
|
||||
|
||||
## Recommended MCPs
|
||||
|
||||
Skills compose best when Claude has live access to your data and tools. [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) servers provide that bridge. The skills in this library work without any MCPs, but pair them with the right ones and they go from "frameworks Claude follows" to "workflows Claude executes against your real systems."
|
||||
|
||||
Below is the MCP shortlist by skill area. None of these are required (except the Ahrefs MCP for the SEO audit suite). All are categorical recommendations: where multiple options exist for the same job, pick the one that fits your stack.
|
||||
|
||||
### SEO, competitive intelligence, and search data
|
||||
|
||||
The SEO audit suite (skills 23-29) is built around Ahrefs as its primary backend; foundation SEO skills (16-22) work with any equivalent. Competitive intelligence MCPs (Ahrefs, Semrush, Similarweb) cover overlapping but distinct data shapes: backlinks and keywords, traffic estimation, audience behavior. Use them in combination for the strongest signal.
|
||||
|
||||
**A note on MCP costs**: many of these MCPs are wrappers around APIs you are already paying for through a subscription, where MCP calls do not add marginal cost. Others (Ahrefs, Semrush, Similarweb, DataForSEO) use paid API credits per call, and long agentic sessions against these platforms can burn meaningful credit volume quickly. The cost model is documented on each integration's landing page at rampstack.co/integrations. Free with rate limits is called out where it applies (Google Search Console, PageSpeed Insights). When in doubt, check the platform's API pricing before running multi-hour agent workflows.
|
||||
|
||||
**Backlink and keyword data**
|
||||
|
||||
- **Ahrefs MCP** - primary backend for the audit suite; backlink profiles, keyword data, content explorer, site audit. Referenced explicitly by `seo-audit-orchestration` and the 6 audit suite skills (backlink, keyword gap, content gap, traffic, site health, rank tracking). Credits-per-call.
|
||||
- **Semrush MCP** - alternative or complement to Ahrefs with stronger US keyword data and SEO-PR features (Topic Research, brand monitoring) Ahrefs does not cover. Pairs with `seo-keyword`, `seo-competitor`, `seo-content-gap-audit`. Verify the official MCP endpoint at authoring time; Semrush has shipped first-party MCP tooling. Credits-per-call.
|
||||
- **DataForSEO MCP** - programmatic SEO data (SERP, keywords, backlinks) at developer-friendly pricing; useful as a third source for cross-validation when methodology decisions hinge on data agreement. Credits-per-call (free tier available).
|
||||
|
||||
**Traffic estimation and competitive intelligence**
|
||||
|
||||
- **Similarweb MCP** - competitive traffic estimation, audience demographics, channel mix (organic, paid, direct, referral, social, email), industry benchmarks, audience overlap analysis. Pairs with `seo-competitor`, `seo-traffic-diagnosis` (external-factor layer), `brand-discovery` (competitive scan), `analytics-strategy` (industry benchmarks). Where Ahrefs answers "how do they rank" and Semrush answers "what keywords drive what," Similarweb answers "how much traffic, from where, from whom." Credits-per-call.
|
||||
|
||||
**Search Console and Core Web Vitals**
|
||||
|
||||
- **Google Search Console MCP** - free, official Google data; essential for `seo-traffic-diagnosis` and any audit that needs ground-truth click and impression data. Free with rate limits.
|
||||
- **PageSpeed Insights MCP** - free, paired with `performance-optimization` and `seo-site-health-audit` for Core Web Vitals field data. Free with rate limits.
|
||||
|
||||
### Development and code
|
||||
|
||||
- **GitHub MCP** - paired with `code-review-web`, `pm-spec-writing`, `roadmap-planning`, `incident-response`. Lets Claude read PRs, file issues, search code, and reference real commits.
|
||||
- **Filesystem MCP** - local file and code operations; pairs with most dev and content skills
|
||||
- **Sentry MCP** - paired with `monitoring-and-alerting` and `incident-response`. Real error data turns generic incident frameworks into specific diagnoses.
|
||||
|
||||
### Hosting and infrastructure
|
||||
|
||||
- **Cloudflare MCP** - paired with `domain-strategy`, `security-baseline`, `performance-optimization`. DNS records, redirects, page rules, security headers.
|
||||
- **Vercel MCP** - paired with `launch-runbook` and `incident-response`. Deployments, env vars, build logs.
|
||||
- **Supabase MCP** - paired with `code-review-web`, `pm-spec-writing`, `backup-and-disaster-recovery`. Schema, queries, edge functions.
|
||||
|
||||
### Analytics and monitoring
|
||||
|
||||
- **PostHog MCP** - paired with `analytics-strategy`, `cro-optimization`, `journey-mapping`. Event taxonomy review and funnel analysis grounded in real data.
|
||||
- **Datadog MCP** - paired with `monitoring-and-alerting`, `incident-response`. SLO design and alert routing against actual metrics.
|
||||
|
||||
### Communication and project management
|
||||
|
||||
- **Slack MCP** - paired with `incident-response`, `stakeholder-communication`, `after-action-report`. Read channel context, draft updates, post incident comms.
|
||||
- **Linear MCP** (or Jira MCP) - paired with `pm-spec-writing`, `roadmap-planning`. Spec writing against the actual issue tracker, not a generic template.
|
||||
|
||||
### Research and search
|
||||
|
||||
- **Web search** (built into Claude in most environments) - paired with `brand-discovery`, `seo-keyword`, `seo-competitor`, `ux-research`
|
||||
- **Tavily MCP** or **Brave Search MCP** - alternatives for deeper research workflows
|
||||
|
||||
### Where to find them
|
||||
|
||||
- [modelcontextprotocol.io/servers](https://modelcontextprotocol.io/servers) - the canonical directory of MCP servers
|
||||
- The Connectors directory inside Claude.ai (Settings → Connectors)
|
||||
- `claude mcp add` in Claude Code for direct installation
|
||||
- Vendor websites for first-party servers (most major SaaS tools now ship official MCPs)
|
||||
|
||||
### Building your own MCP
|
||||
|
||||
If a skill in this library would benefit from a tool integration that does not yet exist, the [MCP documentation](https://modelcontextprotocol.io/) walks through building one. The `seo-audit-orchestration` skill is a worked example of how to design a skill suite around a specific MCP's capabilities.
|
||||
|
||||
---
|
||||
|
||||
## Authoring conventions
|
||||
|
||||
Every skill follows the same structure. See [SKILL_AUTHORING.md](SKILL_AUTHORING.md) for the full spec.
|
||||
|
||||
Highlights:
|
||||
|
||||
- **Stack-agnostic.** No specific framework versions in SKILL.md. Stack-specific patterns go in reference files. The Ahrefs-powered audit suite is the single named-tool exception.
|
||||
- **Future-proof.** Reference durable specs (W3C, WHATWG, Schema.org, MDN, NN/g, WCAG). Avoid trend pieces.
|
||||
- **Uniform structure.** Every SKILL.md has the same section order: When to use, When NOT to use, Required inputs, The framework, Workflow, Failure patterns, Output format, Reference files.
|
||||
- **Tight length.** SKILL.md under 250 lines. References under 400.
|
||||
- **Punchy voice.** Short sentences. Concrete examples beat abstract advice.
|
||||
|
||||
---
|
||||
|
||||
## Repository structure
|
||||
|
||||
```
|
||||
skills/
|
||||
skill-name/
|
||||
SKILL.md
|
||||
references/
|
||||
template.md
|
||||
checklist.md
|
||||
example.md
|
||||
SKILL_AUTHORING.md (the authoring guide)
|
||||
CONTRIBUTING.md (how to contribute)
|
||||
MAPPING.md (origin notes for skills ported from existing work)
|
||||
README.md (this file)
|
||||
LICENSE (MIT)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Trust and security
|
||||
|
||||
Skills are instructions and code that run with your agent's permissions, so how
|
||||
a catalog is maintained matters. Changes reach `main` only through pull requests
|
||||
with signed commits and linear history. Each skill is hashed into a checksum
|
||||
manifest (`SKILLS.lock`) you can verify against, and reviewed against a
|
||||
documented safety checklist before it merges.
|
||||
|
||||
This process catches known classes of unsafe content and lets you confirm a
|
||||
skill matches the reviewed version. It is not a promise that any skill is
|
||||
risk-free. See [SECURITY.md](SECURITY.md) for the full process and how to report
|
||||
an issue.
|
||||
|
||||
---
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are welcome. Whether you want to fix a typo, add a reference file, or propose an entirely new skill, the bar is the same: follow the uniform structure, keep the voice consistent, and prove the skill earns its place.
|
||||
|
||||
See [CONTRIBUTING.md](CONTRIBUTING.md) for the full process.
|
||||
|
||||
The fastest path: use the [`skill-creation-walkthrough`](skills/skill-creation-walkthrough/SKILL.md) skill itself. It teaches the same authoring discipline used across all 103 skills, with worked examples and a blank template.
|
||||
|
||||
---
|
||||
|
||||
## Acknowledgments
|
||||
|
||||
Thanks to [@IgnacioChiaravalle](https://github.com/IgnacioChiaravalle) for the community feedback that shaped [PR #36](https://github.com/rampstackco/claude-skills/pull/36): a CONTRIBUTING.md typo fix, a cross-linking pass between SKILL.md files and their reference files, and the new [ARIA patterns reference](skills/accessibility-audit/references/aria-patterns.md) for the accessibility-audit skill.
|
||||
|
||||
---
|
||||
|
||||
## Resources
|
||||
|
||||
### Official Anthropic documentation
|
||||
|
||||
- [Agent Skills overview](https://docs.claude.com/en/docs/agents-and-tools/agent-skills/overview) - The canonical reference
|
||||
- [Anthropic engineering blog on Skills](https://www.anthropic.com/engineering) - Background on the design
|
||||
- [Claude Code documentation](https://docs.claude.com/en/docs/claude-code/overview) - Where most of these skills will run
|
||||
- [Anthropic API reference](https://docs.claude.com/en/api/getting-started) - For programmatic use
|
||||
|
||||
### Other skill libraries worth knowing
|
||||
|
||||
- [Anthropic's official skills repository](https://github.com/anthropics/skills) - Examples and primitives published by Anthropic
|
||||
- [Awesome Claude Skills (Composio)](https://github.com/ComposioHQ/awesome-claude-skills) - A curated index of community skills, where this library is featured under Business & Marketing
|
||||
|
||||
### Companion concepts
|
||||
|
||||
- [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) - The protocol behind the Ahrefs MCP and other tool integrations referenced in this library
|
||||
- [WCAG quick reference](https://www.w3.org/WAI/WCAG22/quickref/) - Accessibility standard cited by the accessibility audit and design skills
|
||||
- [Schema.org](https://schema.org/) - Structured data vocabulary cited across the SEO suite
|
||||
|
||||
---
|
||||
|
||||
## License
|
||||
|
||||
[MIT](LICENSE). Use it. Fork it. Ship things with it.
|
||||
@@ -0,0 +1,7 @@
|
||||
# WeHub 来源说明
|
||||
|
||||
- 原始项目：`rampstackco/claude-skills`
|
||||
- 原始仓库：https://github.com/rampstackco/claude-skills
|
||||
- 导入方式：上游默认分支的最新快照
|
||||
- 原作者、版权和许可证信息以原始仓库及本仓库 LICENSE 为准
|
||||
- 本文件仅用于记录来源，不代表 WeHub 是原项目作者
|
||||
+42
@@ -0,0 +1,42 @@
|
||||
# Security Policy
|
||||
|
||||
This describes how skills in this catalog are reviewed, signed, and verified,
|
||||
and how to report a security issue.
|
||||
|
||||
## How skills are protected
|
||||
|
||||
Every skill goes through the same process before it lands on `main`:
|
||||
|
||||
- Provenance. Changes merge through required pull requests with signed commits
|
||||
and linear history enforced on `main`, so every skill traces back to a
|
||||
verified identity.
|
||||
- Integrity. Each skill and its bundled files are hashed, and the checksums are
|
||||
committed to `SKILLS.lock`. Verify a skill matches the reviewed version by
|
||||
regenerating the manifest with `python tools/gen_skills_lock.py --check`.
|
||||
- Review. Before merge, each skill is checked against a documented safety
|
||||
checklist covering bundled script behavior, network calls, environment and
|
||||
secret access, instruction content, trigger scope, and writes to agent memory
|
||||
files. See CONTRIBUTING.md for the checklist.
|
||||
|
||||
## What this does and does not cover
|
||||
|
||||
This process is designed to catch known classes of unsafe skill content and to
|
||||
give you a way to verify what you installed. It is not a guarantee that a skill
|
||||
is free of all risk. Skills are instructions and code that run with the
|
||||
permissions of your agent, so review any skill against your own environment
|
||||
before use, as you would any third-party code.
|
||||
|
||||
## Reporting a vulnerability
|
||||
|
||||
Report security issues privately through GitHub's private vulnerability
|
||||
reporting on this repository (Security tab, then Report a vulnerability). If you
|
||||
cannot use that, email security@rampstack.co.
|
||||
|
||||
Include the affected skill, a description of the issue, and reproduction steps
|
||||
if you have them. Do not open a public issue or PR for a security report.
|
||||
|
||||
## Disclosure
|
||||
|
||||
We aim to acknowledge a report within 3 business days and to agree a disclosure
|
||||
timeline with the reporter. Security discussion stays in the private advisory
|
||||
until a fix ships.
|
||||
+801
@@ -0,0 +1,801 @@
|
||||
{
|
||||
"accessibility-audit": {
|
||||
"SKILL.md": "4261e12c948d0832ac8c14431df3b40d2feb4b126356e4215be223ef64688503",
|
||||
"references/aria-patterns.md": "de9cb4934e62903d7d1676b4d4166a43f47e742bdcfd247ca8364c697b779b63",
|
||||
"references/audit-report-template.md": "0ed3d29c53a7f25ad2a72f5918181fd7f7e871d3253e3c66816baac425e09b87",
|
||||
"references/wcag-quick-reference.md": "4d70c669894200c64c9940dbec2ddf959173d7ad8d9dcb594206ea0c18d3cd8e"
|
||||
},
|
||||
"ads-creative-development": {
|
||||
"SKILL.md": "2663c08171e2abe3abc758947afe679eee7c2a5b8f8095fc5ce0dee1a153543b",
|
||||
"references/brand-voice-performance-balance.md": "1bbfe4c196fd80ebc4635ccf7a79e3a901eee0ea6648ab4825fc00e34e9ca7eb",
|
||||
"references/creative-variation-templates.md": "6639d23b01a813d84656ec2f163fad8ce38ed6b68e3be91375c17674234212a7",
|
||||
"references/fatigue-detection-checklist.md": "8cc07d83c0245c0380cadb08fca5ff59799de43cd23c45552e0d6e1ae2c1aeab",
|
||||
"references/format-decision-matrix.md": "6a323059143aba50c1561bde659547a31c81a3a7b11a93b44c437dcc891af37a",
|
||||
"references/hook-pattern-library.md": "900cd2a43ab2440f434bf039886f8fbd0ec1801f18d14a268ff7fb71c3874e3d",
|
||||
"references/platform-creative-norms.md": "7fa8579b1ac1f029ae124c0204acfe143213c29b9dd4386962bf98fcd7bf3562",
|
||||
"references/testing-cadence-playbook.md": "7266af1fe12d7f0b374589cb93682c83458634fc0229809c64873b46896a9bb5"
|
||||
},
|
||||
"ads-performance-analytics": {
|
||||
"SKILL.md": "9f45008134458f37e12812c42ad4bf863a5595e65db5c8cfa771aab8d9db58e7",
|
||||
"references/attribution-model-comparison.md": "fff3d7c5afc4c55ca9c75888a949b827de0338b2de9bb646a7733570cee96a63",
|
||||
"references/cohort-analysis-templates.md": "c15602571f8ce6d28b92d6c50918b2c6c07314b16f83c0d910e694fa332d460f",
|
||||
"references/common-interpretation-failures.md": "754a4c0ed869899d876fca5d38c5b6e0d2563f43fff4675dd567fcc38dbe2149",
|
||||
"references/dashboard-reconciliation-patterns.md": "8d9acce69c46b159866d823a2b38841eebc538bbadf4fdc4263b3afdbf011e80",
|
||||
"references/incrementality-testing-playbook.md": "5bc88f03f7173636edcf249f67efd660466de4439961a340485ec7498a92e010",
|
||||
"references/metric-definitions-glossary.md": "33baa687b9af6fbcf3edcacc411d714e7869df6bf7bb0ae03719c89895fbbdd2",
|
||||
"references/platform-reporting-quirks.md": "5df612e2f8a93adda50ed7830e5becee254e5f9ec7e87154e179b3d949c9a9e9"
|
||||
},
|
||||
"after-action-report": {
|
||||
"SKILL.md": "89bcf92ced995da4701b560163775bae0168a6b55e49937c224b223edf09ba6e",
|
||||
"references/aar-template.md": "b44409782f5a5cd8840b174b69a1a09ae0bb6b183cea9fab0f35fc2075a3495d"
|
||||
},
|
||||
"ai-content-collaboration": {
|
||||
"SKILL.md": "8c31ddb0f21751a412c2836f66e70a9b9a2093b436ac8184baa802808a52f0bf",
|
||||
"references/ai-participation-boundaries.md": "c5af7df14589717a8724f60426b993eceb3167b9baa385fee79e5c9149006de0",
|
||||
"references/ai-slop-detection-and-avoidance.md": "61239daf4cf9e319b31ffba1250daff591f21cd2224a33bb9cbcf3ef4f006395",
|
||||
"references/common-collaboration-failures.md": "2f94e41c0e8eab7c7c708601bef3a53293cd9b9cfebac704c52bdfa897d1f0fb",
|
||||
"references/disclosure-and-transparency-patterns.md": "5a1c02e114c5e1a20e18ccf19c78082fc20387d53108f3200bba5b8ce6a7b948",
|
||||
"references/ethics-and-intellectual-honesty.md": "ebc9864cdd3cef048fe5e72362f47f0d45b4cdab371581c91b320a568ecd9446",
|
||||
"references/hybrid-workflow-patterns.md": "38c43768caa17c5de10145fcc0723515e45a997545a5b9ee1c854e6c5ae87b9b",
|
||||
"references/quality-calibration-with-ai-in-loop.md": "6954375301ca09f7865fd0dfcb277ddea6e6bd1e8f5e1b795864f37dff55f0df",
|
||||
"references/team-training-and-calibration.md": "691e4cec4fb5977f0862bd01a77d1fa5c936051d06d8cf266fb635b050ae8bf1",
|
||||
"references/voice-ownership-preservation.md": "0cd7699f30bcc0384d26f42dee423d8d0952b1ced2847ff92e463164f24e56f7"
|
||||
},
|
||||
"analytics-strategy": {
|
||||
"SKILL.md": "111bcd57af348b778dfc2e8801b79f79c83a5bfdea28da670113a3c9437e6cb4",
|
||||
"references/event-taxonomy-template.md": "74bea752cf246b3c5c73a9597554c9786ae8836b627541708ca2f0d676adb8e4"
|
||||
},
|
||||
"art-direction": {
|
||||
"SKILL.md": "51b14631eae09deaf93bc3a9caefa93adb9a6f378163b4cc62b4129dfa74d346",
|
||||
"references/creative-brief-template.md": "dead6a017ca53c2109f324481e9481a785a86670f07922c92144efb7134593a2",
|
||||
"references/illustration-brief.md": "5f5d4be6388c11bcdcd1aeda2e8c6a13709f25d778be7c2fc3fc32b245687c00",
|
||||
"references/photo-shoot-brief.md": "531a005e77f7d10d71d9b4320fd4f13a2f6734516b92422c36a7aefe34d28e83"
|
||||
},
|
||||
"backup-and-disaster-recovery": {
|
||||
"SKILL.md": "ac0e58600d3332a87b64d06f91f13385eb74a599242a2c3634517479dff5dbd9",
|
||||
"references/restore-runbook-template.md": "96c6cb2b6921ade948d7a0667828148ba36e4845c30e8d7c9feed6f2a7f7c056"
|
||||
},
|
||||
"beta-program-management": {
|
||||
"SKILL.md": "5142f007fa6d68c3f4cba3d689bae8748834634687b161ba5ba795b0fc3d321d",
|
||||
"references/beta-onboarding-templates.md": "20a4d965287f9def6536853e00ae6310b18cc19ccfc84bf13592c46ca8bbf92e",
|
||||
"references/beta-to-ga-graduation-criteria.md": "e687ef9ed64b4e84c5f1caa339cb92088d9907ef80290e994999752a89d29a25",
|
||||
"references/beta-type-decisions.md": "2bca68ad9bde5a0977abe563111286b3d6852cd6e88b1ff6e47ef9e296860058",
|
||||
"references/beta-wind-down-communication.md": "0a71f64073aa7bdd3dfe29ac8235df05a3ce9f086ac53749515b8ee1f83e1116",
|
||||
"references/cohort-sizing-patterns.md": "aa733dd8ba320312d72716fc724ec9e5a174186b376dd3d2e2e5b0d60db42b32",
|
||||
"references/common-beta-failures.md": "d2edb34aa0ccc85d47e659b1c993d73fb31d736c1931b2955e3053460fe8d1da",
|
||||
"references/feedback-collection-patterns.md": "45db8bae42f42093c18a0bd38062e759e04672ad8dbbf973a4205a4c5ff68c2d",
|
||||
"references/mid-beta-triage-and-iteration.md": "b39c0445716ec16a89c7d55c120edad36f671de61eaf8416a6ea7a60e0284078",
|
||||
"references/participant-selection-criteria.md": "70ebffba5fbeb412c749198de249b35d8549189a684a9769602257feef15c478"
|
||||
},
|
||||
"brand-archetype-system": {
|
||||
"SKILL.md": "639b0266c564547bf0d6c616fee6951e024a6f174e883cbb31c38810e83cfea0",
|
||||
"references/00-archetype-system-overview.md": "4b9d470007b2b0a7a4e6b0cb49ced91f46ce4ae0521733a0ceb66f123307a119",
|
||||
"references/01-how-to-apply-an-archetype.md": "df22f17123818fccd7f249d6aa28087866963cd35daa1536356a54fa625bd8b1",
|
||||
"references/by-vertical/01-b2b-saas-developer-tools.md": "f617311a386ecd333f9b9f057e623a50cd67ac7ef11f2d1e97f340f4f2df162e",
|
||||
"references/by-vertical/02-b2b-saas-business-productivity.md": "d40d5aab365f3dc5f0f68436259e79653ca92273ddf193e3190099ce1d4624cd",
|
||||
"references/by-vertical/03-b2b-saas-marketing-sales.md": "b9662134c889e02c0136b1d8b24f93440859d65d0b12ef5624ee3d599dbd0a85",
|
||||
"references/by-vertical/04-b2b-saas-data-analytics.md": "3501620c1817e97ee15ec3cc35f77fc440621be27d5c227c459f15417afe5a1a",
|
||||
"references/by-vertical/05-fintech-consumer.md": "851bee3ce84af8c6c85f45ee4d043e7bff0bab5370ebf0ce54aedc3793b6e4a5",
|
||||
"references/by-vertical/06-fintech-enterprise.md": "87e525819af123b3d173eaabe4005eb495e1f0ccd79b08a2a14a77b65a3bf4ae",
|
||||
"references/by-vertical/07-dtc-fashion.md": "6efd298dab611e4269f8462e0d1febd753b0ce70dc3d6be09f9fec7f46d7f3ba",
|
||||
"references/by-vertical/08-dtc-beauty.md": "18b46980f4a2fba4f95747825806b76f596a22af76b8f0d64d7cc04bf53478f2",
|
||||
"references/by-vertical/09-dtc-home-lifestyle.md": "d55116081a8531747ba8f76b748e3a5acc825f653024f3e383426380d15719b7",
|
||||
"references/by-vertical/10-dtc-food-beverage.md": "d30df48afdbe57da926ca0f4ffd76001eb8ab25d9f6db46d18a66594df3c9251",
|
||||
"references/by-vertical/11-consumer-health-wellness.md": "be53d490f627d85b538e82d8712ca2e2a1e678b5873a76491def4b5f0729448b",
|
||||
"references/by-vertical/12-hospitality-travel.md": "a336fbc969e1c25b52059e6e0150af167eb31dcf4e3dce14a27657ea7a857ce0",
|
||||
"references/by-vertical/13-media-publishing.md": "b77ddc25aea3cd1e03e8313886369c5f44947f11b67926bde1b6a5805afeb345",
|
||||
"references/by-vertical/14-edtech.md": "0ea7800014ebb21f7d54750eb9ce7674ee2115b7f7fbfd4496806b75d0d88170",
|
||||
"references/by-vertical/15-gaming-entertainment.md": "02a41387caa0d88d12e1aa5c9ea6d7249d6fd20c0cd91834282c98798ea0c423",
|
||||
"references/by-vertical/16-marketplace.md": "9e04a05cbd002b311badde6db75fbaf971352cb709ab8c1a76536d9b69db9900",
|
||||
"references/by-vertical/17-crypto-web3.md": "14b87a942df5a92960c65227b570a0702125325a084b74f150c03957b9cbdbf3",
|
||||
"references/by-vertical/18-real-estate-proptech.md": "6693693d018c9341cb7d746980cd9317762706ea3075262cb232fa01f9379f39",
|
||||
"references/core-archetypes/01-editorial-restrained.md": "218bd73686228013751da565650bd9c153c3619b4755d38e04fe69113b64ff4a",
|
||||
"references/core-archetypes/02-technical-precise.md": "0e98fc931d9862bbba8c2bce438cc0d0816105798fb0075e2ace87dc04adc45f",
|
||||
"references/core-archetypes/03-warm-conversational.md": "b7a9fd6dca13df0345b4312696fd599d6bb420a8f60e62e200fb9b3d1f454f44",
|
||||
"references/core-archetypes/04-bold-confident.md": "c0f73226687ecd90e1469cbbcb1dabe1cb770ca24ea43fddb358e0fe2c65409c",
|
||||
"references/core-archetypes/05-playful-energetic.md": "f01cae4d9cac0e1af5e79484a7d1e4f0cd24f9393a6150ce3e1b472a7c58a216",
|
||||
"references/core-archetypes/06-luxe-considered.md": "77bbefa139cf6decbf7b1bfa5ced755c1a96e1dd717ea4c1aeae7f4c60cd11a0",
|
||||
"references/core-archetypes/07-clinical-trustworthy.md": "da38b9e3e28b2510cf68fef8c0170b53c7f0c3c686260186b2d482b71918aff2",
|
||||
"references/core-archetypes/08-rugged-utilitarian.md": "2512aa063ba2d87cbc1655a2fe1dbea546d029cf354f2ceb6ec24712b3e6c0f9",
|
||||
"references/core-archetypes/09-retro-nostalgic.md": "1c7bb79ded48f5be4c0f17d080c461affb730335490e0dd313f5b9f172e9119c",
|
||||
"references/core-archetypes/10-minimal-essentialist.md": "b04d099f90be855edb36a274d8368661e37cd867bb4bc96001861d6f364266b3",
|
||||
"references/core-archetypes/11-vibrant-saturated.md": "af335912eda0e0426b365177be9996ed078fbd9fc7d627113d64a7685b8b0124",
|
||||
"references/core-archetypes/12-documentary-honest.md": "08812b3563f6bcaac6326f1875589dc37da3cc1d14a21fe402c889d6dd6dcc84"
|
||||
},
|
||||
"brand-discovery": {
|
||||
"SKILL.md": "9a7a3a2fe3565401ed54921d13d2c2b0865dbe5753231cd121276953cef89bfd",
|
||||
"references/discovery-report-template.md": "bd86756ba7e05d2a14017447976e699ec7943cc49f9162574617ade7aa65c19c",
|
||||
"references/interview-guide.md": "284421b5bd389ebcd0f0eac36beff90eb5661f691a12f8e62b04652d29b83c46"
|
||||
},
|
||||
"brand-ideation": {
|
||||
"SKILL.md": "cbfa399301eed7dea1559f0c431ee9deab22ce54393c75353e19c241b5e8c746",
|
||||
"references/ideation-output-template.md": "57e4312d98f9db6f527bd2913480a6b6b6febc9a5756305db9c5db6eb771252e",
|
||||
"references/naming-evaluation-rubric.md": "b7f5c2b68229a4e992385519be8499a41f89744930372aee182a5f77ad4b9c57"
|
||||
},
|
||||
"brand-identity": {
|
||||
"SKILL.md": "91dc7f2acc3a0ad57867329adc327c0d531e1df3881c83f4115409079a67b63b",
|
||||
"references/contrast-and-accessibility.md": "180f2472fca45b4ac0cf17dd8c23dc2b1dcc2ee408cf908387e44b863b0b494c",
|
||||
"references/identity-system-spec.md": "57c239004570288f85abf57b6ff14b621b6f2b26da339187479e420891abf168"
|
||||
},
|
||||
"brand-style-guide": {
|
||||
"SKILL.md": "e5de2c8ff359f2c6204b3efbceb52e06d980545f50a915af38216e27de5845ff",
|
||||
"references/maintenance-playbook.md": "03911db7a3b797ef69c160a72ec99c84cab866cf19cd87f2dd46e0dab5eba2d3",
|
||||
"references/style-guide-template.md": "e7e67c874d4495f6a558437cc06a05ac6f5e060ebf5c089e5f718fc498a10006"
|
||||
},
|
||||
"brand-voice": {
|
||||
"SKILL.md": "b9fdadbcbe9b68200edf095c74c8abb7ca6ffa13a1c49fc3b98859ac301f1bc0",
|
||||
"references/voice-document-template.md": "3ecb680f2fab6ac6c056078eec6af588594b3f4947f56f6fa6342750c435d747",
|
||||
"references/voice-frameworks.md": "ddf10b3826f5d16806aad27a34d865ec990b0c910102ae7f289bb6ae19173153"
|
||||
},
|
||||
"calculator-design": {
|
||||
"SKILL.md": "12a86b7868c48e39ef957958a1a7160f9b754ff6d048ffa6f151c3ff0772e035",
|
||||
"references/calculation-logic-transparency.md": "1e35217d11420184083b2733201483a69ed0e08321390a469683a55336e9b36d",
|
||||
"references/calculator-anti-patterns.md": "c7889dddefe8cdf6d8ef6635113c14eb5731f71005a84d10c700380de0a1a256",
|
||||
"references/calculator-investment-criteria.md": "b9475cb4b8f14044dc4881e51d9f03a1d6fa541a2b7ee907c044d8c20bc9e83c",
|
||||
"references/common-calculator-failures.md": "8349575a83d99ad03ff9d515df0707cd3db7add2b8f0396585c5cc702ff83739",
|
||||
"references/email-capture-decision-tree.md": "44d21eef67c8d7e481aecfb0f9ffe489091cee7622e2b74f8331acd8144068ab",
|
||||
"references/input-design-patterns.md": "d2336ae07d4cfd56f16035a5c871a027dcdcf0fc0f175d140c3c9c9692f445ba",
|
||||
"references/methodology-disclosure-templates.md": "e558bd800287e5fd0768803ee45a50f359e41031cb202c36670650c4147b1cf8",
|
||||
"references/result-presentation-patterns.md": "5700738f9b85ffa26dd854506da598b9659f857834076d7d0417f44860ffb08a",
|
||||
"references/tiered-value-structures.md": "d30879cf8be0d490c4833116adad8dcc245a1af63c79b7deceff5d902129cf3f"
|
||||
},
|
||||
"chatbot-flow-design": {
|
||||
"SKILL.md": "57a6f2a29ba1c37db853e190faab629c0fe5c4b7cfe6a5d0698fd3aaa71e999d",
|
||||
"references/branching-and-conditional-logic.md": "c203d1d35c516b8a16d58d3dc65280feb43c4c21ba619d81a4ef3d2108db6fe4",
|
||||
"references/chatbot-anti-patterns.md": "0fb5f3aadb8a5bafdf807ea89cb34cddb1c7aabf8a3ffa81041027e034bfef7a",
|
||||
"references/chatbot-decision-criteria.md": "b590a527c109b4ce8e1be91fecc25159956da82ddc3752040c184a8909093295",
|
||||
"references/common-chatbot-failures.md": "ba271152ab0b616017390ba28ebebeaef39b11cbdb19e8b351ea8e7eb132ed5f",
|
||||
"references/conversation-analytics-patterns.md": "58c66b616cd4c8c42914fc8257eb7017e8318068f386b4977044210507d333bd",
|
||||
"references/escalation-to-human-patterns.md": "bd1e5e69f8dc0d2f3c3dccc4aa0cc1325715b94f1802210b47ebe8bcd891ed29",
|
||||
"references/fallback-pattern-design.md": "bb9a5aef2a2b7412f12158e1cd3784307ae969c21fbdcf98a1b61c1bd18534e8",
|
||||
"references/intent-architecture-patterns.md": "823b5c87d1739ce8d7151e01b629d58870da9cd51ba80fbd88c0404cc646142f",
|
||||
"references/knowledge-base-grounding-patterns.md": "599e49bb2a6bd5cbd20f5c514659ba2dcde27637ba1f4ac41a755356c3b5cfdc"
|
||||
},
|
||||
"code-review-web": {
|
||||
"SKILL.md": "1833c32ede91b3cc8fbda7ddc69de495c8f4bf4a6af3044d0b94c4249472efbd",
|
||||
"references/nextjs-patterns.md": "afdaa25a148693f8209a36c7e5690a7389d0e5490f61781092b9eba6d322836f",
|
||||
"references/review-template.md": "0ca48f838085ee176dc8098618aa1f8681bbc7f1c5d787464cf087f8282c2f8e",
|
||||
"references/wordpress-headless-patterns.md": "28ebedafeccf5b3b672d23b9e0551d9ac6a61780bc709f12963cd08b3fc54b8c"
|
||||
},
|
||||
"comparison-tool-design": {
|
||||
"SKILL.md": "24ce1daec98fc356616d00cf1799f2eca7b80248e980da0ad5e7a863b50b7d0e",
|
||||
"references/axis-selection-patterns.md": "ee3ebf49e43c1fbf51282eb8d18046d1ac5089ad7623e963693c61f82cd29efc",
|
||||
"references/common-comparison-failures.md": "cdd74332f89f9fd03299870de8564a5ef671ef69aa75d85c4b13f7474985d9fa",
|
||||
"references/comparison-anti-patterns.md": "6029133c1a4a7797868ba38194c55be3dc8c1aba77566cc8c1db50b858627379",
|
||||
"references/comparison-fatigue-patterns.md": "c6973c33e2579e8cfd25ff1de0e04644d43600ac24cdaa74e4afb79fee2b1cb9",
|
||||
"references/comparison-tool-decision-criteria.md": "6eba4047feaa696b12d236fd4c73d4f8b96abd49230da5dca0d92a0cf8a8ad41",
|
||||
"references/default-comparison-logic.md": "eecd2eb41e5a544ba280081d287566a1628ea7e367f3d5b6014b58004543859f",
|
||||
"references/filter-and-toggle-patterns.md": "eb9a4a1d65d1d098d4469174917688afc7104c8fac330012e0977d5a8ef65168",
|
||||
"references/honest-recommendation-discipline.md": "5aa51c8588736fb2cb2bdc3b30be55fedb9b8439c42468ed50dbfb473c5aa1bb",
|
||||
"references/recommendation-engine-design.md": "09f150fe3873ff961b44487d51f19a9be9adf6895709b5890dbf53a6333c05f7"
|
||||
},
|
||||
"competitor-experience-audit": {
|
||||
"SKILL.md": "ec49c12fd5729cc2840dbcbbe44a5369eced85ac2e547e94fdfd8d910d78e011",
|
||||
"references/audit-template.md": "d35eac714fafe0c24399de42f594e4ddc9655c046a45bf769afc428db293a336",
|
||||
"references/experience-dimensions-checklist.md": "725882e96410e18d1ed57ea036f4294976d5ee9c97d345d01e85185cdaa60569"
|
||||
},
|
||||
"content-and-copy": {
|
||||
"SKILL.md": "81daa6c8e6c4ec9470aecfde499c2105bf199f7989ba732f317b7e0002198614",
|
||||
"references/content-brief-template.md": "a487a56e9d243bf47f4871fad371779a92416507157d1b2c6138bc8d0382c7a0",
|
||||
"references/content-edit-checklist.md": "050aef4e1a1476bc36f9f368d147810ad54d7ed22bca6ca0ecb281f77840f2f9"
|
||||
},
|
||||
"content-brief-authoring": {
|
||||
"SKILL.md": "c2230a2512dfb785308532328548913baa0ec4ed7a95c2a7d380747fbd663b21",
|
||||
"references/brief-governance-patterns.md": "382342645f219bd2b7c563180cb1762fd02af75167618413ed8fb54e68c39bbd",
|
||||
"references/brief-templates.md": "b7a79d140611d98bf97ac0012b42af95b603dc62b14d19fe569362d664cce0e3",
|
||||
"references/common-brief-failures.md": "4ffac06f788da3b8c5a9455876d10fc4889d4299e5b8a72d30d36eb57c7e2116",
|
||||
"references/entity-coverage-checklist.md": "6ff4220eda35ce703fc692a4412244c9cec54448032b0dff6237fe05aca64ad4",
|
||||
"references/heading-structure-patterns.md": "f6de5d055ad9da0db009c2ef2d8d0a05ceb81b77c5f9e25580348cff7f723ac4",
|
||||
"references/internal-linking-strategy.md": "583fc4c14248b6cfca9a36fb538307419406aa3b6ee114f9fe4c427417f67ceb",
|
||||
"references/search-intent-classification.md": "1abb35b731098eab72480adb933ec623525a0e6dc97c56e15d860b3fe44aea0b",
|
||||
"references/writer-handoff-protocols.md": "8cf53b9a3f5c026bc20b2a861d40f83ce9088e43255f469fdb8e60ade1a0563a"
|
||||
},
|
||||
"content-distribution": {
|
||||
"SKILL.md": "c64b8f6a494351cd4fb7758a1a916381bce2a3b635a44bf23f96e76c9b1d283c",
|
||||
"references/audience-channel-matching.md": "5428654883780c23dfe6e757abf44c547a7f80ccf9fb41da9e3b49c311c21bbb",
|
||||
"references/channel-taxonomy.md": "53756c7e7e6697d87610a46f01f12bf7b2f2435b10747242eab24311b34b2cc7",
|
||||
"references/common-distribution-failures.md": "73f46f456d0876ee70ec222c2271d4b22242151e91c9392d6a4edad889d187d6",
|
||||
"references/content-channel-matching.md": "06f73d90652989d55d2c3a8cd0318fd9e11d43931fd001e6bf3130cfd953d1af",
|
||||
"references/distribution-cadence-patterns.md": "7bab05c454e42ae51b0e6d32b4a362f84b7de39cd93c742988abe1800d456b9f",
|
||||
"references/distribution-measurement.md": "b45c31337a64b3693b2816116206119325f439185d0ccd11b839a94fa9b47e07",
|
||||
"references/earned-channel-work.md": "d757f139c9332c094f1c95a4104542951d7abf1e5fc1c87154961bf0136f7815",
|
||||
"references/owned-channel-discipline.md": "d9dd2c4200ffc3c33481eeef0f94275c1a687ecaea1d9b653651915e7e219565",
|
||||
"references/paid-promotion-patterns.md": "421229698784ea9de8606340bd0eddb68d68714bef49cc0143738e285d678819"
|
||||
},
|
||||
"content-migration": {
|
||||
"SKILL.md": "943dabf12d00fe46909ea4df0913eb0c2816dc40e98d5233b58db463b3a19510",
|
||||
"references/migration-runbook.md": "12432adbabff9b516191922a2cf728d45dc44208f1164370d14970a72b1abaa9"
|
||||
},
|
||||
"content-refresh-system": {
|
||||
"SKILL.md": "e663127d720b3658a611591277e4b86359b34ccdc4d8c2123fb25b3427c3a48f",
|
||||
"references/audit-cadence-patterns.md": "01d640512a0975fc8a8a90adbc69c47e38614a3c0a2bb9b6560f0c42803f601e",
|
||||
"references/common-refresh-failures.md": "3e6b5004fa3256e5944ec71e652816b9c0673662a859cab5ab9aa3fba26c0e5d",
|
||||
"references/effectiveness-measurement.md": "0ce1c0e2554c273e55556a4d2c5f96132b11a5f101da9892ffb40a12ce45e05d",
|
||||
"references/re-promotion-after-refresh.md": "9f06b9e79cc8ba12d2dbcb3c9f07ba87591e6a1a10b42a2a2c79541142c7fd41",
|
||||
"references/refresh-depth-decision.md": "66444168df8b30226672741b02b83a896a6aa2b3fb23b2669b11f1a03cc6056e",
|
||||
"references/refresh-execution-patterns.md": "c4dd65f01b9d2128708b9ee6af37810fdb3069964dfd391245954bc668db2d1c",
|
||||
"references/refresh-prioritization-matrix.md": "8e5ffe36ee3c26c7e0a99eef80ae4b2efdcc3b20aeb4f890e39a19ea3de21900",
|
||||
"references/refresh-signals-checklist.md": "13e55bf62d98b8eefec3605a1aca28428a6db67c56f6e1e35497c27a8e685e23",
|
||||
"references/refresh-vs-merge-vs-delete.md": "20da2a78819e33b202bb5d969e57f850330c9064f2b8093da7d7b8526241e28c"
|
||||
},
|
||||
"content-repurposing": {
|
||||
"SKILL.md": "e3845e95d8beda2d5592a6e1ed6cc4a51242e80fd275875f47b6c41e87f96ad1",
|
||||
"references/aeo-extraction-patterns.md": "43d369809a612ddff65a0612ea077d9add7cba28964b5d11d35ac517cc70c197",
|
||||
"references/common-repurposing-failures.md": "865db4e58177ebd390d4501004836f102e484152486c4e2510a2cb549abe8291",
|
||||
"references/cross-promotion-patterns.md": "29c7c8eceeb3217069c6ba60d6a11503260e296bb3781eeaf8653a861d819c40",
|
||||
"references/format-adaptation-patterns.md": "8652b63ef34e5b2994774ef7829bbc65bb29b62940d935a3c7149b6f3f1ccd2e",
|
||||
"references/per-format-constraints.md": "08ddd2d86d1614215a10438181a1bcea3868c29d0ecedf22608038db323613f9",
|
||||
"references/repurposing-pipeline-templates.md": "6ad5112321327b81a588d41d387d9a3211b504011615a411ecff9c2af70d5783",
|
||||
"references/sequencing-and-cadence-patterns.md": "a88b40085203372c4c8dedde765529ab93815fb216adce3c1000c82a09dd1f23",
|
||||
"references/source-piece-selection-criteria.md": "38e988bcceefb541d53265b39a310f9670f116c0534b0cc3662d8032507e28db",
|
||||
"references/voice-consistency-across-formats.md": "18868f761b20ceefbbbc019c7adc1886d1dc1dae783d036b4af1a4c4a1ec0317"
|
||||
},
|
||||
"content-strategy": {
|
||||
"SKILL.md": "ec5d8e51677956fb73ab58a8bf7c0279c1ddbcef70bedae70c4b75527bcdc3ad",
|
||||
"references/content-strategy-template.md": "6707df3af82ddf656f3aeb945359ec9df0852e63c49590516d569581fe5a946a",
|
||||
"references/editorial-calendar-template.md": "feb36bd8373c725f6a13418457e872cca7f63fe7256189233644338453d3130e"
|
||||
},
|
||||
"cost-optimization": {
|
||||
"SKILL.md": "cf3c13cfc8f896e8941caa5a45d70091937d51882ef2ec66875a7aef9c043ebf",
|
||||
"references/cloud-audit-checklist.md": "88e90cd841d9e14b9c8d04c2e4f4bcf6d7248b319ed5856873f2a45b8a2fd1ed"
|
||||
},
|
||||
"creative-brief": {
|
||||
"SKILL.md": "6391b3f973ed4b0b38e2fa6d16fcf96b86fd0ee7c032101c01877a0abcded198",
|
||||
"references/creative-brief-template.md": "be62abe14c8bcad2776c72aeb4019150e06ab9209bcd9dd7e4a16a896face62d",
|
||||
"references/example-brief.md": "ada71946c214db87e898d504b9f2992976a77a3d313eb7f05dc7c04a4a968960",
|
||||
"references/voice-and-tone-guide.md": "0070a3c693d0c955938e1b804a8fba11fcb26602b103f653cc422fa4d1adef8e"
|
||||
},
|
||||
"creative-brief-selector": {
|
||||
"SKILL.md": "a450d913ee5da71061119f487b69021cfe90cb1274a648f246f0e846feb965ad",
|
||||
"references/00-overview.md": "7e88dc86fa3ef9a32ec80df6655ad87b00cc821ff39dc9f4d11486463e457eab",
|
||||
"references/01-process.md": "d1b2156b567c09f7a0a75b4f1dc2ffe0a6191c1c1f94ac6fbacdd37aad8469f6",
|
||||
"references/02-brief-template.md": "4fcff3d36094fc94dda6b6ccf2af31533d26fef9bc008a6ffc9f0f5d02739c51",
|
||||
"references/03-divergence-check.md": "7624e929d0889201378eba0d44de2ea90378202cb6bcd52adf9cd84b25924dab",
|
||||
"references/04-shipped-demos-signatures-example.md": "fc246a3d695d722b86cbc39650a9e675bc8fc47be74e339f31d358ee97a99087",
|
||||
"references/05-section-shapes-vocabulary.md": "c93deaa40b9fc54791fad7e92c1d40613783ee06502d873a6e1cdf74782417fd",
|
||||
"references/reference-bank/README.md": "3cba4191eab66335ad03f15f4606769f79c5ca57126c0f1e720939281e9cb226",
|
||||
"references/reference-bank/bold-confident-editorial-restrained-aaa-game-studio.md": "c3fd4b9aa05977ca787c7526caa08a3e9f4d21be9c1f22e66563c4388c780fcd",
|
||||
"references/reference-bank/bold-confident-vibrant-saturated-single-ip-game-title.md": "c088c9bb56dfd2bb48eb6ea64ffa98a58ceb8d928300cbdcc4ea3a9bdc331267",
|
||||
"references/reference-bank/editorial-restrained-documentary-honest-specialty-coffee-subscription.md": "fce75ea111fab93db34d5b94ca5ec929bf8467bac1497dd06023a940badbdde0",
|
||||
"references/reference-bank/editorial-restrained-literary-quarterly.md": "e18308c05371a4d28f1fbac1919f8968eb8b48cc178eab8dcc97455aa58fbec7",
|
||||
"references/reference-bank/heritage-local-service-barbershop.md": "ea5759017c562ce5ea307242c1ba416be2a56c393e55c385ce3e48927795a9f3",
|
||||
"references/reference-bank/hospitality-experience-balloon-ride.md": "281b9b75d4412738aed015987e9cb30ae9494e06b8f13f12278eb59b645d9ac7",
|
||||
"references/reference-bank/luxe-considered-curated-stays-directory.md": "4e1864874db794d111903cfd0456103233ec4a8adfeada5be14653a03c6b2a9d",
|
||||
"references/reference-bank/luxe-considered-editorial-restrained-residential-architectural-brokerage.md": "fd879703fdb1fbd13c71284adf04a88e12e5a72a60495f46f21fd142cb59fa55",
|
||||
"references/reference-bank/minimal-essentialist-documentary-honest-trades-directory.md": "15281a0104033f8e24f23e5869a85134986ccb56bb1e28cd98d03cd4aba4a641",
|
||||
"references/reference-bank/premium-dtc-maker-western-boots.md": "96fa2f957f14fe6e373732ad58bcb3adae673db3ace7f440a111293af3305252",
|
||||
"references/reference-bank/rugged-utilitarian-documentary-honest-regional-used-vehicle-marketplace.md": "3e54545c7bb9fa5f0aec2a0689098b9a08a78cdd5dfa87c93cc8c600e5ca2f27"
|
||||
},
|
||||
"creative-direction": {
|
||||
"SKILL.md": "fc11c13225666233b3e544854a7a46a19d3a04ced7faefaa0fc1cfd892fd0eb4",
|
||||
"references/axes-explained.md": "26cf20c0146660f1c675fbcabba2f3742f69ebb1543e31c0840deeaff0d77567",
|
||||
"references/brief-template.md": "bbcf997ba2049d58858758018bb81412c783f1d9a7d1e07ae0dc2615de9f8ddc",
|
||||
"references/example-aesthetic-brief.md": "9b99900f15182d05c705808691a2941aeb3ad48ab18b533fa28e0d3481282f91"
|
||||
},
|
||||
"cro-optimization": {
|
||||
"SKILL.md": "01c7b12c4627a5f4898c4cb0dda7cbd94c5b7c32f8771478eb87cf3d9f0980c1",
|
||||
"references/hypothesis-library.md": "a3a83b4596344c15eaf3f05b0ef165dd023c8e85f15e01cbb0abb60e64a68c98"
|
||||
},
|
||||
"data-warehouse-experimentation": {
|
||||
"SKILL.md": "42bfce53001c854601cca9b72bab4dffe5b0486d886dfb0f21aa8679b63fd6b0",
|
||||
"references/assignment-and-exposure-patterns.md": "23295809ed9f51480511647a9294ccf82e47da70f62ada5f1466b1e6080a75c2",
|
||||
"references/common-pitfalls.md": "3bd66b6477c1340b085f68fb42d550809fd931d0af2efc1cb10d686ea0cfc0b4",
|
||||
"references/metric-definitions-in-dbt.md": "68d9143d0eccbde123d06517c1b2b8b62304657c1999f7c08c9b7d4bf05c3272",
|
||||
"references/power-analysis-calculations.md": "f53c0eab73db7786826c590f108e17e21feef00cd40436337a8cb35723bdb78a",
|
||||
"references/sequential-testing-patterns.md": "e876bab3f9a795cc9c872d46ec128c18116b3ea2439b85fe27ce61953b5a74ae",
|
||||
"references/statistical-analysis-templates.md": "3a20a29d06a96b79c2e0df7452af0eef40237dc9b874a90587883eaac0abe7a1",
|
||||
"references/variance-reduction-techniques.md": "726539000ebc237f813a763e1655389784c1f32519c9420a1d6bca049c7efe81",
|
||||
"references/warehouse-vs-platform-decision.md": "6586a38fb0ca88501f5e5ba912d0effcea381f85159dd86f7c8cc8aa8ffca06a"
|
||||
},
|
||||
"dependency-management": {
|
||||
"SKILL.md": "ae2f2aad82407f0296e53eae858598d9695fd4fa92f72729fbbc9d63591eff6b",
|
||||
"references/upgrade-checklist.md": "5f109279239766ecea3303f7e3fd8c423788ec45bd197500d35a39e926f28bcb"
|
||||
},
|
||||
"design-standards": {
|
||||
"SKILL.md": "39d0e08ebf96c75330accefc409000df9155c7d8ae094a3121ae1c6083e764ff",
|
||||
"references/design-tokens-template.md": "c685d2f7f977f1e87293dfe796965bd1af73e240e9d69fefeff8276f2e3ccaf0",
|
||||
"references/preship-checklist.md": "1309a7808768d6628453b2e5b5d88a4728ded7491472c9b4af2d167f0dd0e6f6",
|
||||
"references/tailwind-patterns.md": "bb402ade1ebef7cea5a703d84bafa331a88ea2ff64f0cf8079639689522213c0"
|
||||
},
|
||||
"design-system": {
|
||||
"SKILL.md": "048170f41fdf1491b5dbdeaead1927b01622ef4a90cf8c273acdfa6a5fe944ea",
|
||||
"references/governance-playbook.md": "c9a4d533566bd6c1712884f240acf473a501dca4e7fcd35a29cd4578f93188b5",
|
||||
"references/system-architecture.md": "5fd27fd24b1794f5536b049fa0e1617b34cb49217ef1006b7f114788c3c26ac7",
|
||||
"references/system-audit-template.md": "6f55e20262360e19a2b7519d342fde4ba278877b9231f64748465d336591b6e5"
|
||||
},
|
||||
"discovery-research-synthesis": {
|
||||
"SKILL.md": "9b8117216f510e167d3183860f2c3b8ef0d023c0819164e8e66def9dde150c2b",
|
||||
"references/common-discovery-synthesis-failures.md": "443841c8b757f103e49f0887d95bcef7b1bee464378597bdab093d2f2a1204ee",
|
||||
"references/from-pattern-to-product-implication.md": "8e05d4063b81e291eaab9ce3cba0a6c74a359077d9c93850566fe1e5725ffc33",
|
||||
"references/pattern-naming-patterns.md": "ab31eef4afba854689fbb008f143c344361ffd2dd9e6967ce40dcf85936603a4",
|
||||
"references/research-types-and-when-each-fits.md": "0b3e9604fb84564be464329e1bc285b43d00af126809930aed30f8bf851b5afe",
|
||||
"references/synthesis-review-and-validation.md": "f894a570aacf1bc7c6ff1a45e68d7336cfd73cbc1a5b7278fb8d916ab1c5522c",
|
||||
"references/synthesis-sequence-walkthrough.md": "c53392053544ccc01c0a155f3df4721cba522a0f680a657315d4822f66b68979",
|
||||
"references/tagging-and-clustering-discipline.md": "9fdab28572262cb0fbcb05d1a88da6e7e7c05465a1907caaa540577346019f8b",
|
||||
"references/when-to-gather-more-data.md": "927f38ef709106541394198cbb32f0f081737b292a80ad34be12d3d4b7e3f0be",
|
||||
"references/writing-for-decisions-not-decks.md": "66512c8e9d7ca6cc8ed55f24754afd462a798a6fe28509138a494a88a80f1ecc"
|
||||
},
|
||||
"documentation-strategy": {
|
||||
"SKILL.md": "c9313863695c971cb8d5dd179d9dd91610a01806fc4a8e3cde3fa44a6b426d52",
|
||||
"references/doc-types-guide.md": "19f98b891fab1fb2918b7faf47517d839b3cb82b1c0198a976b9d17ed8c95b2d"
|
||||
},
|
||||
"domain-strategy": {
|
||||
"SKILL.md": "3c793b8980492e65a4006e09f0643112c51b3509b74939d9a80774c7dd07e6d6",
|
||||
"references/dns-record-reference.md": "bf7f15dcd0e7e3f6e54d789319593c6b94c20415bf81c5b20f604d8c3499127a"
|
||||
},
|
||||
"editorial-qa": {
|
||||
"SKILL.md": "a1f408fa2445e4576988c42ad05b01ed012e02a0aff47a3d7606e0bb3e54f195",
|
||||
"references/ai-content-audit-patterns.md": "5af73d5b614ab2456b9b4a6927f8228d9d5a399cb093282ca6d02a8623fcb5ff",
|
||||
"references/brief-adherence-checklist.md": "75ce474f7fd6ad22b240fe4441e60a47395922fb6b97833e083e261019bda10d",
|
||||
"references/common-qa-failures.md": "5023275955bd31c8f1934a1bab73bd5e07a33649dce45ba59ab31824f508b35b",
|
||||
"references/fact-accuracy-and-citation-discipline.md": "2a9bcf77720b5136c9d8d941bff1326a19086387ef8f1e120201c2e8e88132e5",
|
||||
"references/internal-linking-and-schema-validation.md": "06d81225921d5c59c01906d639a46e9bc5a089ce89496539f09ef370625860c5",
|
||||
"references/qa-at-scale-patterns.md": "670c89a5ee37207c86df70f0528b61150c6b94cfdf2b2d197694c5e9e618edfd",
|
||||
"references/qa-workflow-templates.md": "6182aa3efc8c1f7a53cbe4ba827fd3fb8e8aa12f26b5c4fc5de20ef862df7ec7",
|
||||
"references/seo-aeo-compliance-checklist.md": "9f51c6706673e2df8e1ef8b3b86c5fae74290ce422f165980718261fb54cab6a",
|
||||
"references/structure-and-clarity-review.md": "002258d5b0d87ed35e42799cc4c28a1da02553bdc707a24900586972dcdf2a6c",
|
||||
"references/voice-consistency-patterns.md": "65752a7c97f84aad0832ddcd492496e0df0011b02cd0c4c375e000a5d4942377"
|
||||
},
|
||||
"email-deliverability": {
|
||||
"SKILL.md": "d321d0661dbb471567570631f1b7ee031a7d96e1696206770af362eb2f1119e3",
|
||||
"references/dmarc-rollout-playbook.md": "da50d90b6fbc7be52f046e077d6be659b36fcbacf7e9c56484c8df8a9e0ed7f5"
|
||||
},
|
||||
"email-sequences": {
|
||||
"SKILL.md": "1fae7c044e018b024fbf4795bf83ccb7e411bcff17f7c0e9694a3febffe6428a",
|
||||
"references/sequence-templates.md": "01278eb7b4a30fe73bd609d3f11f641860b45b243520efc7da4393cd08a9f002",
|
||||
"references/subject-line-patterns.md": "ccb7daafdea47a5dfc632cab458b319a5ded21fc499a74da2aa305ed1a7c01d5"
|
||||
},
|
||||
"evidence-based-reviews": {
|
||||
"SKILL.md": "44bd22df772d09e8f8fc98cbb3355ff398c5d38c1cb066b709f67391211857ae",
|
||||
"references/evidence-tiers.md": "fee3b0f7ec78ad8cf9f0f15325679972db4180eafdd3419b257e92b98bfe4fda",
|
||||
"references/methodology-block-template.md": "74ec061cf5befb94a4db24479df918f1ed8c1dfa35721daaf3476a64e4082ef4"
|
||||
},
|
||||
"experiment-design": {
|
||||
"SKILL.md": "10e8c08d666170badc5eecc7880be137263a9533620f83ffa6f6f4d430c4ba15",
|
||||
"references/common-failures.md": "0c059512ada9af9831dbd6351c752fd77aa91e5e86b814268aa3a18d3d954a5c",
|
||||
"references/hypothesis-templates.md": "e34cf0e22eb6b5ef7cf1b6237d128bb4008a8f6dc29c4fbc408bfe9d555cc6b4",
|
||||
"references/platform-comparison.md": "0c287a49e0ed260fb98dee0d50f6bd77c59db5582c2cadd8da56292f64381e45",
|
||||
"references/post-experiment-decision-framework.md": "e6ae462e0500d8cb7bda483e18c6fc39f8929c00e1175a34169cb4bd41dbd872",
|
||||
"references/pre-experiment-readiness-checklist.md": "4c642e86c8c2c8748fde2a484cc63d74eedc61ec5611a21bf820ab50a26eec6b",
|
||||
"references/results-interpretation-checklist.md": "150d49b5c07bcbbaf4baf6e1c5122a1484a934ba91419d74a80a198cf92861af",
|
||||
"references/sample-size-tables.md": "2997f71cc07ddde0619f49b483b8499c4b92a4c4ca62d9c3a68d405e1c8e6319"
|
||||
},
|
||||
"experimentation-analytics": {
|
||||
"SKILL.md": "95c10f71f94e4d716f7521d6922ec42487361472a01fa67ab45170fdb6c055af",
|
||||
"references/analytics-platform-comparison.md": "37add0e40f70202abd4ce411cb06f5002027649e706bc379c4637e249fe69992",
|
||||
"references/common-interpretation-failures.md": "6fdbbda10777f3e88d47c7ac48a6f252f761e2519e08b3bbd0874a67013a9ef4",
|
||||
"references/confidence-interval-cheatsheet.md": "1230881d5b5a2058197974af63f55dbaf319e012cfbfafc815cc76cf16901351",
|
||||
"references/dashboard-vs-experiment-reconciliation.md": "05ce85c5d7cba5887facca4f2ddc3cf546bd3cf57d30a19707c6265a2038f7c4",
|
||||
"references/p-value-interpretation-guide.md": "36bd0903be32d2e94164a3046051191714b48782309fc06e83286cad481ef4a3",
|
||||
"references/result-presentation-templates.md": "7effb28a5262d2ef42b0c355bb44a3469c21ac1594226e9a05f264eb788aa4d4",
|
||||
"references/statistical-method-reference.md": "a8d10650a2acdbb991dfb61f1bd8d63cc48eb79f7add496fddd5062bba14c464"
|
||||
},
|
||||
"experimentation-platform-orchestrator": {
|
||||
"SKILL.md": "75e8c1452c1b3c1881c2e85abad4d43181076f7cb3735af20bbd9c750fd98ea5",
|
||||
"references/common-mistakes.md": "c467ef375142273a4bc4004d24e0704210ec4cbea4bbc4251b1e350761595cee",
|
||||
"references/cost-and-pricing-models.md": "a999b39c66630712609a603e95c48843eb732f6951a8278a5eb5564d1321cb73",
|
||||
"references/governance-and-team-setup.md": "37512f6abb8b95408013f36009f4d2e56bd6d891d4112c05b056b8199c955564",
|
||||
"references/mcp-capability-comparison.md": "9c4d0a278e708ab775b3ae36775f87da7e46498d496ac8a6459e0d54e1aed13b",
|
||||
"references/migration-playbook.md": "968442909815c3e2ff71c33c56a8150c603aed238d389d9f9fd06d0d8066b1df",
|
||||
"references/multi-platform-orchestration.md": "03a113011dfa8cabe29ba4a6874f8d87d25e2d5541e95fdfb7a07e71b357a293",
|
||||
"references/platform-decision-matrix.md": "1c764fcab98fc2773f4894dab0256970d4a71fe792389c2b7449bde70193e46a"
|
||||
},
|
||||
"feature-flagging": {
|
||||
"SKILL.md": "a28f31b35b4726e7cd89447d4cefe715f5e65bdf6e27024ae435574b644052b2",
|
||||
"references/flag-lifecycle-checklist.md": "d35012b27070a4241edc359de60b9de221c77d1858b9f963c26793f56ea6b7fa",
|
||||
"references/flag-naming-conventions.md": "194ee8e2f9dfc056e48611fbb7e59c841a0e71f854a6fa547300780ad636d664",
|
||||
"references/flag-rollout-strategies.md": "5282a340234254f2425fb778d5ae632d59967d98ffe6564f06a157013c038f81",
|
||||
"references/flag-types-reference.md": "469502829e13ec61067e5b40fab54c00753fa3fda33e2226b027b050bf13a0db",
|
||||
"references/governance-and-permissions.md": "45ba6a05092359ca3d38d66155ea03c84cedb09a6ceb401864604f8042fea234",
|
||||
"references/stale-flag-cleanup-playbook.md": "a1fa433e4048135f7e508f778d70e80aed676f9c7a6c70794270b358242ac539",
|
||||
"references/targeting-rule-patterns.md": "0f48ff7c05d602bdbf5bcb2d26dc62c8556b1c555c4b8fcc4abf4fbf869eb017"
|
||||
},
|
||||
"feature-launch-playbook": {
|
||||
"SKILL.md": "c3d0d12ac22d2c84b11c468197af1a0ae1e0b7994be27db175aa0485b71d7bb2",
|
||||
"references/common-launch-failures.md": "f23e57a272c71c1f54de80c23d2aef6df1c7826b1fe596e99d70a0b0b8a4ba32",
|
||||
"references/customer-comms-playbook.md": "38532b0c79bf233347b7aea3de0f6308d4c23b8076b6766bab12be492dd0a9df",
|
||||
"references/internal-alignment-checklist.md": "c956526d9a0b029c00600f5f6dd0ac6d1449cd46aceaaec14b9def8c808a3ec6",
|
||||
"references/launch-tier-decision.md": "71c7b0df513a0ec4ae164ae0fa005929d786ea5ae398a28f730eaf1a845357c6",
|
||||
"references/monitoring-readiness-checklist.md": "f16746da797f14c0699c2663fb14494161fc11a032eb12226c44f39a816a302d",
|
||||
"references/positioning-canvas.md": "71d3e4d76f7204f470dc9fd0074cb34d4d15a04b2f0dcba240b8d0ff83a3b26f",
|
||||
"references/post-launch-measurement-framework.md": "64b1e7cadb366cfd192e6c71c278000f0319f27b93b07842c68466ab8de9d577",
|
||||
"references/rollout-strategy-patterns.md": "97e02d775f55828cb8f8b46b4fd2c21e1684f6312d8b0ba3879f45d2e90f4a89",
|
||||
"references/sales-enablement-template.md": "abc815936fb9ef3c3a98e55e0e03cc779c42aa1f788dfdcaae71b17061efc450",
|
||||
"references/support-readiness-checklist.md": "eba17b8edfcf3112e045b651b0f96977fa3534893d11872cd3b4474ea439bd56"
|
||||
},
|
||||
"form-strategy": {
|
||||
"SKILL.md": "09286f693466cddc5dc8d6bc1d1428fb36ccf757f4ba3d1d3c3aec7dd2b1e56a",
|
||||
"references/form-anatomy-checklist.md": "4fb48222b1de8ee32939d8cdb398f240e406895bdae1e2611710a5f5a32a21c2"
|
||||
},
|
||||
"frontend-component-build": {
|
||||
"SKILL.md": "32c9a8c1e655649fd691f01ca33f80bf9efd0d75b9530f3f2000880bf807d34f",
|
||||
"references/accessibility-patterns.md": "75cd55f7f18e62c7fbf2f14a7cb2d5dc6bbfb48ca307a6f7141648e0e4c962f8",
|
||||
"references/component-api-patterns.md": "e778bea47205bf1e3542f07d9e267097f1d2b3c7aa0e7ad7d44e13e327c95ead",
|
||||
"references/component-spec-template.md": "eac4ca7e0f61e9bbece7138c51813f518b4d8e33a1d4283535b123bf589279cb"
|
||||
},
|
||||
"funnel-flow-architecture": {
|
||||
"SKILL.md": "1388e715dea912dc974e18b45828ebeb6c748d57b8aa419f577b3a868c1495df",
|
||||
"references/architecture-anti-patterns.md": "249fb92d75bacb53e0f3b9218b3a6bdc4cfd8be9fedbaf3a8f7a30431f9cd8e1",
|
||||
"references/audience-and-stage-segmentation.md": "a056a112bc6d50e5d257295106a9b5e6f9f710afd87bce8b6af4174290945108",
|
||||
"references/common-funnel-architecture-failures.md": "a2e75eb73e0ac703e4eb4eb77b17ed1a2d57c0448ed4a85e5fbcf26b1fa2bcc0",
|
||||
"references/cross-tool-data-flow-patterns.md": "759a515c4b02bac24f48914e17fdba085baae1be17e709d361501460df469b43",
|
||||
"references/entry-point-architecture-patterns.md": "a6b5bb4ee8465c95903b50b3e55e47a81ec5c1f8de85e3429b17b5dc771aee09",
|
||||
"references/funnel-iteration-discipline.md": "f496eca2005a357ecacab75558403f40953994187cf7e4b3e1392f7c08c5c091",
|
||||
"references/funnel-measurement-patterns.md": "0fda814628fc1a8eb9699e86f8313cd7b6250bcbbcbf019460e9e3cb2e822f23",
|
||||
"references/nurture-sequence-architecture.md": "e0f57015214126619e3a34f3d5e6c7679b242571cf749eff148042f228937efe",
|
||||
"references/tool-to-funnel-mapping.md": "6654d5665940a9b3e7369d3c13962d5c96d592e9771a468c0be78082949e93c3"
|
||||
},
|
||||
"incident-response": {
|
||||
"SKILL.md": "d50d603c1198d7ed7de6c61764245dea24ade7aa96e16468a9f5f89d7150ab9b",
|
||||
"references/incident-playbook.md": "52615b122a79dfdf3f57258048f726f1ebe4588b58b2aaad56b169b8ad339c1c"
|
||||
},
|
||||
"information-architecture": {
|
||||
"SKILL.md": "5ecfbb75636ac00ba3941a2446332fe0bcec868e0c9006ad6ee9bc7230fd7059",
|
||||
"references/ia-document-template.md": "74c09120e7d6c2cdcd4f7bc1253a6234310f450e7e8acaaa5086faf672f88127",
|
||||
"references/url-pattern-library.md": "235a35a3703a3f94a691343cde949bee543550650952ea1a911eb0fa07c61353"
|
||||
},
|
||||
"integration-orchestrator": {
|
||||
"SKILL.md": "60755b79f1836358b69c5ba29ca289f0175a75bef1255b4d05eb6bb02f00e81b",
|
||||
"references/automation-and-qa-tooling.md": "1ba201adc00dabc48ad05d2b59c990641292dba12ed510f3b6ddab7384ad543e",
|
||||
"references/cadence-patterns.md": "9d1ea9739301052736193f705adccfeaf412478e3f6babd3d394d9079e54f222",
|
||||
"references/example-orchestration.md": "adac8722763e2faa835c20fc4e7f5d5399f3be4cc3c2819746c29f92b99072d6",
|
||||
"references/gate-definitions.md": "8e1a0f538be3fcfb1ad2c4cafe09caa83ec04f8dad753f3ecd20aff1ac632c49",
|
||||
"references/handoff-protocols.md": "01634392d91d15f29ba5f1a2ff49aeedfcd914a794e99fee6570dd41f60eb293",
|
||||
"references/platform-implementation.md": "e7ef3d490607b1d82f8c80beb347ef6f0b6fd148ff559c8bcc2a812d9feebceb",
|
||||
"references/team-size-modulation.md": "fba5969cb6269b6f12cc2536a0aef10684fbc80bbea68a156121f76c5b7eed84"
|
||||
},
|
||||
"interactive-product-tour": {
|
||||
"SKILL.md": "becd45906aef2ea0f3fc42a540686ec61b66c0c55690edb15eda87b6432f4077",
|
||||
"references/common-tour-failures.md": "3c1545aedaf61943bd2a13a86262ad1713518a6d7ae97e83b6f3869529b230f1",
|
||||
"references/completion-tracking-and-re-trigger.md": "a5b0d32fcda6622666dc53d44a71e294fca936b34f2c34d26accb4d7091c4e81",
|
||||
"references/contextual-placement-patterns.md": "18988353f588ef415ca40ae080f03632016b2a8c996f1246c8ab0cbe74c0e99d",
|
||||
"references/dismissal-and-non-intrusion-patterns.md": "9a30a9e2f47ae07e0a7dac24d979659256f649c3976fd5a9310a1a26efccb7d6",
|
||||
"references/power-user-vs-new-user-patterns.md": "497ac732997e57118c39e65a06ea5116b250d50383c53aa52f4c306c4643cce1",
|
||||
"references/tour-anti-patterns.md": "9f351b305db1e1467eb0a65d9c147939e6d90e73c28b237d35766b0471c06f5d",
|
||||
"references/tour-architecture-patterns.md": "0f7450168e4efd18396eb014f862123000087f5518996a98bb82e2c4cb408be3",
|
||||
"references/tour-decision-criteria.md": "33202ba03afa930d82c8cbbfcbf0e419c734abc9dd193e160c1caada1d4c86c0",
|
||||
"references/trigger-logic-patterns.md": "95ae0cfc1f9b501228055a3f4ed7b4b919bfe2d0c86dec50aa2673bd49ffde6d"
|
||||
},
|
||||
"internationalization": {
|
||||
"SKILL.md": "76b12791dff2688827f50917b867b535e6713505cbcd802b8611f2ff5274d7a6",
|
||||
"references/locale-checklist.md": "c4d2d760448ed12f8a77631c31f9619006e2cac53a1cef024dc842d30146e4ae"
|
||||
},
|
||||
"journey-mapping": {
|
||||
"SKILL.md": "67e601e554b8e4e1608a751a7c154c4b3d28ba5b01a5cd29d1db6d342006974e",
|
||||
"references/journey-map-template.md": "6062a7d524126cd89b1d1075b12a1893dbd16b5811670911861290aaafca196d"
|
||||
},
|
||||
"jtbd-framing": {
|
||||
"SKILL.md": "400bf8ca34f5e11979dbf336ef936e4b90ac72c9e006740a2a7cc06d8e3ba297",
|
||||
"references/applying-jtbd-to-discovery.md": "24a4f4bc22673cabe559109cec85f2b7555195b4ae2f8526bce6d6e85b55fc23",
|
||||
"references/applying-jtbd-to-positioning.md": "41f82c8fa88a8a7ef0087504f541c8bb41af990c2d28cd218dd3dcdd991eb699",
|
||||
"references/applying-jtbd-to-prioritization.md": "22855cd3a942d6470a734e62c5bff1514504be34f8b68ddd646d8e6654b4e71f",
|
||||
"references/common-jtbd-failures.md": "ce94c5bd7688ce6aecb7d2f217dbb3e9a5eb2eb70a0ce29904a91e36c8511d3a",
|
||||
"references/functional-emotional-social-dimensions.md": "b28a1771dfed2a254d44cf9b7cbe61f4229ae58d19e14c733ab5972b910dd8d7",
|
||||
"references/hire-and-fire-criteria.md": "cb4d1a2fdc6d525d37b40073554c157a80977908636cfa17dd1a742ba8ed0f64",
|
||||
"references/identifying-struggling-moments.md": "ce7683c317251c8949c791836039ab2b99a059722d9df9af8119954415b5411a",
|
||||
"references/job-statement-structure-patterns.md": "80cac04e5df9c3b27ce922d6e606e00914d899fa2df88053369c3f333fff0033"
|
||||
},
|
||||
"landing-page-copy": {
|
||||
"SKILL.md": "1e0f504ce254ab088d3af8419d0591646de7a792a618be29448cfb34329a7a4b",
|
||||
"references/hero-formulas.md": "654fedde24827379c2ef62f9f9c5ef283cf23d0a1e58b991a51714b65d9a47cb",
|
||||
"references/objection-library.md": "bc0ee97281d1d5710dfb453f1018434d0d86c090fc1f5991506f93e4789ea585"
|
||||
},
|
||||
"launch-runbook": {
|
||||
"SKILL.md": "8d1f7b18667dfd507d3bdfb31858f5b5ff48205230060785cff40701e8a21adf",
|
||||
"references/runbook-template.md": "3413ba76c18bf4d1852e0145b6b53e31352a3522b65b4cc306b3ebbdb02f4ad8"
|
||||
},
|
||||
"lead-magnet-design": {
|
||||
"SKILL.md": "aad4e66576f4f61061f802cf15e1fba9e5b7d5c35bf456ec064571aa95fbcd8d",
|
||||
"references/audience-fit-qualification.md": "ec967a6a705c86a016ab97101cd79e0f84c32d1ca015ee6ed4640b5d6d4a1699",
|
||||
"references/common-lead-magnet-failures.md": "ca053b6e50f08a31bd2af37397431ec4b2bd53df2beef595b6d7d597ea9cf527",
|
||||
"references/delivery-and-follow-up-sequences.md": "19834c41389a46b3ef52f3d6999e3337884157a16b935f89b9324012c7a80002",
|
||||
"references/format-selection-patterns.md": "fb389f392becc328880708dfcd64bb048f436ee73c48cf104d40143b4e4d5170",
|
||||
"references/format-specific-quality-gates.md": "04a3f5181444bc8475d406bd81bc8e5ef3cd1c9d9d4f6f9b20b078717f56f616",
|
||||
"references/lead-magnet-anti-patterns.md": "38d25e6dae7882a5f3218569816af81bff49b8883a3cbe4aaeff714e2e14a65d",
|
||||
"references/lead-magnet-decision-criteria.md": "bb02fa9def76479951b50ec6a8e7ed55df3d1ee60016f3de054701936a1da638",
|
||||
"references/title-and-presentation-discipline.md": "24bf554b55e78aca2ea1248cec3fb5b77e5c92c0868bad9423571ddb617413dc",
|
||||
"references/would-they-pay-for-this-test.md": "258ad4d02453d608e4f8a10f6aeaace320abee8de23465b7b0eacae758f0da7b"
|
||||
},
|
||||
"logo-design": {
|
||||
"SKILL.md": "81f4dce86b45e901a89c93fa1f5f2e82d6ecb1754fe1ac7b6077d78de1db0711",
|
||||
"references/application-contexts.md": "5aad2091c8e66c6fc256e75b307544a23095e387d5c8e3f6c493ee0add9fb70e",
|
||||
"references/architectures-explained.md": "4e23b69addb6837c148c4fd0a23a3cd4586af83c64fdb65a3abcf20cff7a080b",
|
||||
"references/category-conventions.md": "8e90ead85e315275de3afda451b0af21a9707c0252bb2fee1aeaa257ad4d9546",
|
||||
"references/client-package.md": "47f4ebb7f34ef971a838f2199dc166cd1a7bab7f11646da9755d0233a3660bd6",
|
||||
"references/example-variant-spec.md": "7c10711a934233c2b0210d345acae580bbe15aec06dc7feea6cb3bb32361d05e",
|
||||
"references/symbol-approaches.md": "8d96f44908898be707c76ee6a78ef71ab214a4bc3f6efd53d041d7e66cf974c7",
|
||||
"references/typographic-registers.md": "df34f7cdb4d24eb5237c163c29aefc1156bce480eb024a5ddbc1c117061e451a"
|
||||
},
|
||||
"long-form-content-frameworks": {
|
||||
"SKILL.md": "78a9699621fe4249617d1d994308631856602826d83597dd9d737265aea3a67e",
|
||||
"references/attention-sustaining-techniques.md": "6b059285cec33ab70755a0a2322ab1e33d87aa108ee2452d6f999cfe884ada39",
|
||||
"references/breakouts-and-visualization.md": "532a234b3d8b04b4084f0c9340c3ea4ceffa30653cc3e8c8103ea236b08cd702",
|
||||
"references/citation-and-source-authority.md": "ed8515980e30e768c3c62617e1421c51162b0fe583cbd0395a6851b61d7df86f",
|
||||
"references/closing-patterns.md": "843c1d5889c2991ed5e70dd7f9bcf06f7a8922e827b66647dec94648e7c1c702",
|
||||
"references/common-long-form-failures.md": "0c737d666fbc47050f480f5975dd37e31c82cc06bb0cc65f62cca13b62d40df7",
|
||||
"references/format-decision-framework.md": "5b5bcac5d254696fcf3fb1ee9c8ec6240289bcd44a77e5b1dabd6045054ac096",
|
||||
"references/lede-patterns-for-long-form.md": "c11e46c604c9f526580a3be9485a5563a676b3347e2196be011ab1d28721a19f",
|
||||
"references/section-weight-calibration.md": "18970774b92adf7c540aa5bff04eea1aa48b3270d3cec8d74db0b8eedfc4b9aa",
|
||||
"references/structural-archetype-patterns.md": "02d8e18dff2e4ebfee8e55d04375f836e10b265522dfd67121c93d4de22a0b24"
|
||||
},
|
||||
"media-asset-management": {
|
||||
"SKILL.md": "869278da1465f2b1ae622ef71c7d8396ec41de50775dfc65a3a80d7ff7d74fe4",
|
||||
"references/responsive-image-patterns.md": "eb7db1ac10ffd4ba5fd054af7f0e5254c642e65387c53783868dcdb2f8ef3db8"
|
||||
},
|
||||
"monitoring-and-alerting": {
|
||||
"SKILL.md": "49c6556d04de2e03bb3ef0617b994fc933ff941e5ba917afd7fd34658d0c89fc",
|
||||
"references/slo-design-guide.md": "b1dca1a7bec8b45b490899c918dc6a40f5c2206e29b3e9aecceb466379d2e5ad"
|
||||
},
|
||||
"multi-step-form-design": {
|
||||
"SKILL.md": "b72db037ba83253b07fc9f80da42514b4267d0aaed8f99908285b51a6481e517",
|
||||
"references/common-multi-step-form-failures.md": "c277a033d0ef841441f2f5e25d8ffc6f3f2e64e551a50561e14ca2483ac1a3e5",
|
||||
"references/conditional-logic-patterns.md": "93989ed33af310ad55b699e5220e9749a8503a9a93cd0729595b4f89b7335314",
|
||||
"references/drop-off-measurement-and-remediation.md": "65e524171cdf346401255d71a06ba39fa9181de25a98e111de15aaabb88c781f",
|
||||
"references/form-anti-patterns.md": "02edce5273659dea7dfae0edc5bcbca9dbf4cf5a46cfd78beb4bc87c0a71cd0f",
|
||||
"references/multi-step-decision-criteria.md": "5a728adda666c05ea6345187a265ad917baa72dd9751703911c5f8782de4e902",
|
||||
"references/progress-indicator-patterns.md": "e9f6d7ce7b8d7e846eef842424745af9865df19f5e25a0f7a2dde0e6ae730316",
|
||||
"references/save-and-resume-mechanics.md": "b1d95bd5c2a6a9a0a163edfd723857ce2a1f9b6b10c72b142a4c82fae5a8cb1d",
|
||||
"references/step-architecture-patterns.md": "e4370dca4df49ca19840cf03e9e2b3df4bbaead0a41c6bd22f209f9a7543d2e4",
|
||||
"references/validation-strategy-patterns.md": "2cad091e2954d9dd7025be5b0d9a9412dfd37ba020c44c2c0354764544269eec"
|
||||
},
|
||||
"okr-design": {
|
||||
"SKILL.md": "b58bfa9db5b15d67d5e0a663d62f2d2804acdb32c700130181d37996e7ef7298",
|
||||
"references/cascading-okrs-decisions.md": "8b97e746534784ffe1b151bb87c2cf13ca1b92bb1e473c3fb06847cd22d9c510",
|
||||
"references/common-okr-failures.md": "c52cad5ce5ad3d2a615cd491e2b261e3f77bd1741104a0328c5a85552c844ca8",
|
||||
"references/key-result-design-patterns.md": "2effbc61c0d5890759faf550515e4bb5ca7b235e05e07d3f2be64346eb18fdcc",
|
||||
"references/mid-quarter-recalibration.md": "8c0239c292537f4d71e4384b386df54976104b0de5540991ff31c7ce85c69672",
|
||||
"references/objective-design-patterns.md": "43d51421d9e6397f8fe2d2896f0f4ff5f273d8f33a666e669746cf38c8022553",
|
||||
"references/okr-anti-patterns.md": "3b2f7d2e6fc07f39b175c947599cc11919743452ebd28f163b4c0fe1828f3073",
|
||||
"references/okrs-vs-roadmap-vs-metrics.md": "7d7947e628174b06b70727cb7f6d8ec1f8d743a274404c20e018a9d416f67ee4",
|
||||
"references/review-cadence-templates.md": "4fdf95ef0ab4d90e6a3cb1bbfb1a470354798a66a4383b60a9d61fa509d63910",
|
||||
"references/scoring-discipline.md": "887182a483d8bb8deac61f4cbdbea660550c70279ab6d938b7f74813666778b4"
|
||||
},
|
||||
"onboarding-wizard-design": {
|
||||
"SKILL.md": "381fcce8e470a997f484c2be54f343d7aa41198cc59e5714904362d92b0e8cb3",
|
||||
"references/ah-ha-moment-engineering.md": "b2f1a28b064627f1f4aea1d676f054683b0bc37ddb82531fc95fecaf42fa05e6",
|
||||
"references/common-onboarding-failures.md": "4f2dd5ab5188dc2edd5f7b38351803f05a4bd3397046ca558c02bc244010678f",
|
||||
"references/drop-off-measurement-templates.md": "423885a14780235112d12f9756f7023538d77122ef018695ab36fe74b296660e",
|
||||
"references/progressive-disclosure-patterns.md": "87437dc481f787cad8cd3da59bea84a3f9747cf2a1ddb6039177d47a821263f7",
|
||||
"references/skip-and-resume-mechanics.md": "5ac7f072095c922bcb264de259a0b066f1842278f1b19008e5e17630ab2dc7e6",
|
||||
"references/step-architecture-patterns.md": "4e60cf7e001f6a25ca611eb1394005afd0253d6c58983b689cff470e2c2a6b82",
|
||||
"references/user-type-variation-patterns.md": "4a84476fbaed635e3fa51d2e16b8625b234b25a450823b4cf56439db6ea4ba80",
|
||||
"references/wizard-anti-patterns.md": "7464f2124504187fde7c8655db0ba303878ddf9e91cefaba6200a5c967e4355f",
|
||||
"references/wizard-decision-criteria.md": "4e976611c41b6b2c3281bd053f458bee5f5e69daaf706df04f808bc4daa8895a"
|
||||
},
|
||||
"paid-media-strategy": {
|
||||
"SKILL.md": "afb2aae08a0d45a30c09c44de958ea56cd13eafea7589bdce1306dc23ead2f20",
|
||||
"references/ads-platform-comparison.md": "133636975a25f212a9e913975b3ba3696b34a8c42b894eb8b8ace1424e7a1af3",
|
||||
"references/audience-segmentation-patterns.md": "ede2b4d02b6c2316a310cf5cbbb52f56aaab1d55b76bfb28cf7a9cea14b675a3",
|
||||
"references/bid-strategy-reference.md": "4797fb17d4b30a96a59a5ba039a115266faf55f5e4012bcb46ab29f392030d60",
|
||||
"references/budget-allocation-templates.md": "53aaaa53dab15cfc86874c0986ed3544e6de1fce7c051ce8371e2722832e0e0c",
|
||||
"references/campaign-type-reference.md": "8a2f977a925fa6372b02f81ed652819d4a9b943755435a3977150598537a1cc1",
|
||||
"references/channel-decision-matrix.md": "e5e74225e2a09fe39ec5d79d0cb1ee26e8b3ae87cd7a744149845ad48b62edc6",
|
||||
"references/common-failures.md": "55c73def01e20f38568f193f0c0345b2a9f9e784875044eaa4b7e657fea2e871"
|
||||
},
|
||||
"performance-optimization": {
|
||||
"SKILL.md": "197dff3e07f0a2ec39f8e043232c4a8a8957c16491a7126997ac43b1537c8ad0",
|
||||
"references/audit-template.md": "d260fcce01ba0b8ba6bd858498cb774744a17ec4411cffb2f69b68e6ea2e9d0f",
|
||||
"references/optimization-checklist.md": "ed962ef8d94a9d86d8ae42020c573890fe9572504da5504915204afb0785a267",
|
||||
"references/optimization-playbook.md": "83ec500dea69fde32516886089ad1f90a267a1944c0e0f1985d51976bf6082ec"
|
||||
},
|
||||
"pillar-content-architecture": {
|
||||
"SKILL.md": "f64af5943682f8da197fb2b8d920c1ef91133aef2685289c99e91ff0f10b4855",
|
||||
"references/cluster-piece-anatomy.md": "aed7fa2644890fc1946eccf95fee0c2a0bdf71f775801b70982b99f291569219",
|
||||
"references/cluster-planning-patterns.md": "68750375b26afebe62e49f8e86a4001d8da899ace946b8afbc4f37d67cdaa1d0",
|
||||
"references/common-pillar-failures.md": "751c4ee9e88f6d84378c03921c3c9fabf5989de09aa6e4e9cb83c0180ca1c4f3",
|
||||
"references/content-refresh-patterns.md": "9968c4b0bfadcdf49016e4003e5fa1cd966f44df9658baa1ca2359e14509ec36",
|
||||
"references/internal-linking-architecture.md": "3fab78ff4dfacc00f81ccd701454d5ec1bffb1d12c9dd37f79429fdd98da3ee5",
|
||||
"references/pillar-cluster-decision.md": "03d57c506c7b88d8020a90989f4939463188a91393d6ae1cc89f45a6ad6a4c6b",
|
||||
"references/pillar-page-anatomy.md": "c0b38f0b943be933095d9d08cc035fd3ad3f4a87675fd30950e87ad6f9bdece8",
|
||||
"references/topic-selection-criteria.md": "41f4db72d83096095f97468aba5c060f1c1be4e2223177db4be9490bda674606",
|
||||
"references/topical-authority-signals.md": "c4b1da3952b4f64c906bbf8663a1fbd716fda4432708546b99d7009456441b33",
|
||||
"references/url-structure-patterns.md": "2949bbd359b36fba00e71bb6ae63eafa5c4da036ca6b54275db7b0891218a68d"
|
||||
},
|
||||
"pm-spec-writing": {
|
||||
"SKILL.md": "a0863ad6146f264d311d75e2678e400930b40bf377b34403dafdf3b18246f957",
|
||||
"references/dev-brief-template.md": "4c253a2a71243d65407de0098323fbc542ba72f03c572ed41df8c5189d2e9f31",
|
||||
"references/feature-spec-template.md": "f9b19f192d9e65b6882e97aaf23f4b1862a46a39d2e9f8b86eb6562aec55fe13",
|
||||
"references/prioritization-frameworks.md": "b8b7696ecc60f95d56ce2c91cf67d32b4aed6e9432db90eba319935431cd7e8a"
|
||||
},
|
||||
"product-analytics-setup": {
|
||||
"SKILL.md": "dd468374cde1a89d29f344604c8657ba67b9304398343dd410e91d15c3fe917e",
|
||||
"references/cohort-definition-patterns.md": "efac882d9b59a04e2f7be066d502a4e633797ce4b8a9e374597d794f9673498a",
|
||||
"references/common-failures.md": "97a65cea3da7d9739c9698581f8f027886980c7403fc9bc3e3f5beea1931f1f9",
|
||||
"references/event-taxonomy-template.md": "41c337b25785fd484cdd5a26207229171b2a6341fe12612a5b516e23be754212",
|
||||
"references/funnel-design-templates.md": "9bc3b1e81b75f06ebd91ff5bb9f6ba9ab8a413ce8e1f5e762dabadf0d00cd377",
|
||||
"references/instrumentation-audit-checklist.md": "2bfb6ee57316174d2e3de9ea240c4957401f98844f6cb50c410ce93d2f88b337",
|
||||
"references/naming-convention-reference.md": "ec10f6ea1567a79ead0e2d81d860c8bc01a2e821961071023a73b71dc617f674",
|
||||
"references/north-star-metric-selection.md": "45959db9ed267c0ed9f26873e1ca1c816b15d3f24cdb6d6cefac8ce88ee71dff",
|
||||
"references/property-design-patterns.md": "5b496ca6447f06f72dccc48a1fb36b1f0c533d3339f207baf97160c8bba90907",
|
||||
"references/schema-versioning-patterns.md": "f69f7fa458621a6104f842f62b013175dcfa5bb01ee1ec6653ce49c3cd48adb6"
|
||||
},
|
||||
"product-configurator-design": {
|
||||
"SKILL.md": "cd0b2ae4d2e3e605545fd198fd627fa5e3378842344c20e434ef478412d1f854",
|
||||
"references/common-configurator-failures.md": "36237cc604675bab8299b7c7cc9223badc3090e7bfbf6cacf69a3fcb65a168ab",
|
||||
"references/configurator-anti-patterns.md": "2270f06cabfeaa4fa3dba69c282ae511bb08e124e98c0d9c95025054e801da8b",
|
||||
"references/configurator-decision-criteria.md": "f1587bd82d9aca953ca2b9473d5decc3dc9d75e217f00473a62ccc79e8fbbe72",
|
||||
"references/configurator-to-cart-handoff.md": "dded80a2806dc007deed369981f5cdb1002a943817b18b4b77716f22f4635a4c",
|
||||
"references/constraint-logic-patterns.md": "043ddef7a83686cf93f481674e0ddd390da1b1cbc74a50dd7adc41a5239ab68c",
|
||||
"references/default-configuration-design.md": "2d5961060b72d0074de0514dee763bf01e2524a321dc147a30c9604ae638b313",
|
||||
"references/real-time-pricing-patterns.md": "ab5c60b500215b2a0f94b0288dde93dc74e6322c4c3edf1eb6e311005882abd8",
|
||||
"references/save-and-share-mechanics.md": "241966cddc019c782b1d96959a7c5c0d90f2c15eb349c5af82ada464b1a1e672",
|
||||
"references/validation-and-error-patterns.md": "5bc422c04ce9a2458c786787d5c190cae83111c471cae14aec83ae86b5726b94"
|
||||
},
|
||||
"programmatic-seo": {
|
||||
"SKILL.md": "7e2ff674899054540a189c9c7e2abea60f6391900ce3a9c2de0f97b5e3735bce",
|
||||
"references/aeo-geo-for-programmatic-pages.md": "f04d05294b10277eb867c46f6eabd2266edce2712f2bac9602af10be829f87f6",
|
||||
"references/common-pseo-failures.md": "b0a2e494867adabfc5fb189ee75d232a366e4888a84cc407819570364e4bcfb2",
|
||||
"references/crawl-budget-management.md": "5f6b2aa8c412dd3676ce33ba222818aed199a77f81b191f4477b8cd3578329ef",
|
||||
"references/data-source-identification-patterns.md": "2f5b6722b920a9c656ff00a4cc1131df47f5cf72b0175485e777d0201d390663",
|
||||
"references/internal-linking-at-scale.md": "89f218ad8f63b6289f6cd3dac10ba1c7fda60177c42400b29efccc3363c4755b",
|
||||
"references/quality-control-at-scale.md": "ff90f0add9dc35e969b8d9362150ee8b48a834378bd262c48d25272c0717df53",
|
||||
"references/refresh-at-scale.md": "b8535c4698d65b4ed8b5d0a98922b63b5cc8ef1837deb4fac04b687247c0a955",
|
||||
"references/schema-design-patterns.md": "fe7a97b09dcd4d1e9d477b8cb9c8ac433d86ce389a070b634029e2c21578d8f9",
|
||||
"references/template-design-patterns.md": "74077b84135df3f90a9b03e41cb053481e33443eee18892698a98a2f5d2dcc90",
|
||||
"references/when-pseo-works-decision.md": "3033a8f6687e9533fb0ff996267b80ef48a1e964b23694c8706b1ec1213bedc4"
|
||||
},
|
||||
"qa-testing": {
|
||||
"SKILL.md": "605f8489de7d3860b01056be0d4380ca5753ec3cca4baab4e8b957a9c28ad85b",
|
||||
"references/qa-report-template.md": "241fbc871bfee946964decd1496e0ec4ad87861e8a77a8ca0565e3559c358358"
|
||||
},
|
||||
"quiz-and-assessment-design": {
|
||||
"SKILL.md": "9e2a56cb5c4439eca01b7f81bcc590303b1fa1d04948be89c6d5a504030d4b9a",
|
||||
"references/clickbait-vs-actionable-distinctions.md": "dbeecb34f43b62a8b3459043ef31b938496bb16acc0eff5bd922b48ec7e799f1",
|
||||
"references/common-quiz-failures.md": "0f2f6cc2d417e825ca1d288b0fe2695687fda9cdb715b8e415f9bab799b1ffde",
|
||||
"references/lead-capture-integration-patterns.md": "36a6e98fb92143fd12af8a98d200adf23f5fcf07644673dac03ff9fe762e9a79",
|
||||
"references/question-architecture-patterns.md": "0f064dcf6c5cb28d137a6cf7cc2173e665df2e718d294e8457c927650dddb069",
|
||||
"references/quiz-anti-patterns.md": "aa0bd4d86434a31675b119d16a699522dd044d8bc646c4a42872c9a882926ffd",
|
||||
"references/quiz-investment-criteria.md": "6d6ddc708c9af2142e7f70e7223012bbba1b588c68844923f9a8b2d7a64a65cc",
|
||||
"references/result-categorization-patterns.md": "c1b790239dc0a25610deed73950a24021c264815fd2a0bd5833e70c912071f66",
|
||||
"references/result-to-recommendation-mapping.md": "b2ed7f77d79f163d5e7a6b4005c9679c5a0033bda9d8b58eb80fc5b27fba1917",
|
||||
"references/scoring-algorithm-patterns.md": "20a0e5f83b1612e4a77e5d5037b1cf3d6e27f89d9dd9dc3d6ac279c8eb031cd5"
|
||||
},
|
||||
"roadmap-planning": {
|
||||
"SKILL.md": "136b637fe06e0c1082989bccb2ff7a22fc00f98ce31ca676f4eb76a8e9285273",
|
||||
"references/prioritization-frameworks.md": "6c8870e8f09e2d7100ce49dead148cb32fb58183690a8123854a8e93ffca656c"
|
||||
},
|
||||
"scheduler-and-booking-design": {
|
||||
"SKILL.md": "ece48cc9d88aae68c738dc2aa336feceb90cc37cabf39578a2f449f4359d9d02",
|
||||
"references/availability-logic-patterns.md": "b26ff752f4ff3d4f5ef0ccd66fcb300c17edf6319f6bfddbe88327a576b477ab",
|
||||
"references/common-scheduler-failures.md": "26635ae57c012ccad9d278bcf9842d772c3b58607104bc60449ebe9257c9b992",
|
||||
"references/prep-automation-patterns.md": "e9c9bbd477faae2bc1e0e86c89f66733fa83be43154d8e1505a36d12467981df",
|
||||
"references/qualification-field-design.md": "389ebd480124b9e1197790aa7cfba71923a041bd20b1d967b28ce19d5519fcd7",
|
||||
"references/reminder-sequence-patterns.md": "f7a089bfdc72b9edf2215ed5e5c79226a6b28a4ad7e4ddde803f7c7b879ca5cf",
|
||||
"references/reschedule-and-no-show-handling.md": "9c27075150ad137f013ec4e882ac75c9d5f7534d2b637fa7678b61eb75d80709",
|
||||
"references/routing-patterns.md": "18ddac97df1f5911495d82a91208e96ccb597906138907b235493f49f62f3896",
|
||||
"references/scheduler-anti-patterns.md": "c96273744dd333e96233fc24c67e9c9ebebba62db86f837e79d086e3e1633ed7",
|
||||
"references/scheduler-decision-criteria.md": "02a4237ac2d3101ab0d84c273f9b5f22d501d530fd76d250775e311d2f403196"
|
||||
},
|
||||
"security-baseline": {
|
||||
"SKILL.md": "8af28729093ff8a97796cba7b37db6d621e50d5d31e684baf1ba8bc98383daaf",
|
||||
"references/headers-checklist.md": "5e24408454905148cccf616dcf3f707204e971b3e28a5ea017a13e88a76cad95"
|
||||
},
|
||||
"seo-aeo-geo": {
|
||||
"SKILL.md": "573caeaa6d9e988fb7539bb79c397756ca7fb4645ab4f79a69d3a14017988529",
|
||||
"references/extraction-friendly-patterns.md": "85b0653394d246a848e1bec3c6595d4d19f6156e209de66871aea07e0883490f",
|
||||
"references/llms-txt-guide.md": "008c48e172172ae440564956e7486014b91fdd93831bdcdc52e2dfbae3a00063"
|
||||
},
|
||||
"seo-audit-orchestration": {
|
||||
"SKILL.md": "5763168e22bf43e990a875222d757352eea86fbff92339280b28ad95b19cb68e",
|
||||
"references/audit-rollup-template.md": "70563185132deda3957df63a228a0f0cd59c302d72351dc8b73427433f81f456"
|
||||
},
|
||||
"seo-backlink-audit": {
|
||||
"SKILL.md": "37551a8024bdc7491038fc73c19953b363659f7b2e76a0b65a8c327e6f8a8808",
|
||||
"references/toxic-link-criteria.md": "aa73226858f36bbf1ca830045045565ea28ed4fe5e5b27c13d6a29cf60ab97d0"
|
||||
},
|
||||
"seo-competitor": {
|
||||
"SKILL.md": "4296f3a7d88431b3912c41486bec657f73d8e4a9a786f820e409ab148e3eec23",
|
||||
"references/competitive-audit-template.md": "0fe2971545f422c63edcb9aab9c6dbd87c80397617b65cb6da7eb63e9ffb133b",
|
||||
"references/content-gap-method.md": "c330977140a343b11f7fab31972c4cc1b77d35f8c9dc5dd0807f964da9773994"
|
||||
},
|
||||
"seo-content-audit": {
|
||||
"SKILL.md": "f0588f9f0437140d6527a881e9ad7f8c24aaec519da4b9022b2bcf889e1f3ffe",
|
||||
"references/audit-template.md": "fd85c836d4bf3baf72565cce07018a510e0f905b68690a199bc2acfa52465028",
|
||||
"references/cannibalization-resolution.md": "1644a14351a85bf12fedb57b495ea95eb4b0f3f9a503777913023ce721740637"
|
||||
},
|
||||
"seo-content-gap-audit": {
|
||||
"SKILL.md": "3baa95158c522c8ee66f1716baaa281dd3910b9cd0a4c1be63c52c6c1a4cd324",
|
||||
"references/content-decision-matrix.md": "c5d333754ba3e269d8a274e05195537b465b27bc0d989bb89c185bcffc8c7b7d"
|
||||
},
|
||||
"seo-keyword": {
|
||||
"SKILL.md": "376462a53fb1bbbbb08fe89f745c7d8c647863c9bb64e8b4d7751738e141169e",
|
||||
"references/intent-classification-guide.md": "8570e2862107ee41e856f47d8410a07182329751f21861b0c32bb0ea692e6c01",
|
||||
"references/keyword-research-template.md": "68d252b32e2c977a8ecf5bf2b5c9583316e6aaff3cdb257a7cd362ba3d1c57c5"
|
||||
},
|
||||
"seo-keyword-gap-audit": {
|
||||
"SKILL.md": "094cc3f266928d838a71834e1884354179d77287cf894bc39b99880ef0013cd2",
|
||||
"references/opportunity-scoring-rubric.md": "0fdc3312bad1f6b1b0dc25d594700c09dbb3ab5da65b46a50999b6b9bea330a3"
|
||||
},
|
||||
"seo-offpage": {
|
||||
"SKILL.md": "34f047ae8e48c8e7bc911345029bec572b8729a87665f9c517aa23a87c7a7748",
|
||||
"references/linkable-assets-guide.md": "03c09bb5272ba30455df405f6b97f0fbc0e92023753bd85e1009297c8f24f6ee",
|
||||
"references/outreach-templates.md": "ac5b76f5825a16f9476f09c6c946a6e7ffcda8496090b68d3fa9a7a2b9bfc5a0"
|
||||
},
|
||||
"seo-onpage": {
|
||||
"SKILL.md": "06e7759b22585cb673b44a492b7343ebb9f345669fca60fe509706602587077b",
|
||||
"references/audit-template.md": "e533f58b133340d11467232c5303a42e0467b723975a82de10965f34dcb41071",
|
||||
"references/onpage-checklist.md": "4d2938783d3ac9a6a4f942b732bf752d031f13f83275baaa01e71df11245d21d",
|
||||
"references/title-and-meta-patterns.md": "174d10417509e11d5c3654d0e4e018343f79e5bec317fa55d8003f7988c67ae6"
|
||||
},
|
||||
"seo-rank-tracking": {
|
||||
"SKILL.md": "d3c729f8de84247999ec04d6a525e804c6b75e96fa016add9c4901fd23262454",
|
||||
"references/dashboard-template.md": "efb302269ec3f0e9122a99034e1e95e0a65976b4833c9a6bd91353efde924feb"
|
||||
},
|
||||
"seo-site-health-audit": {
|
||||
"SKILL.md": "78684edafdac6e2f73ce48c23d261ae81386fbd04a26b56ea0003334a8d1bb1e",
|
||||
"references/issue-impact-table.md": "e59a5c298f0130d60ba9ad1c6855217e95168161a743e67c0988f766bb9efd24"
|
||||
},
|
||||
"seo-technical": {
|
||||
"SKILL.md": "8b874b2a102ac52c059f8860aae1119d36c14ecd8a63b5e7bcda7c04830d79f4",
|
||||
"references/audit-template.md": "71d840bec52223e82eaebf518ad20636dcff163a316edc79923a5703f82ce92b",
|
||||
"references/migration-checklist.md": "7f9a4dbdd9653d4a2d8a9c8795376562ac26545568db6f493a21c3f5bc485bb9"
|
||||
},
|
||||
"seo-traffic-diagnosis": {
|
||||
"SKILL.md": "c692568650d16f9f17cd4a9474c3126b9d78852d742e219872f98e464262c6e1",
|
||||
"references/diagnosis-checklist.md": "f1d2a4bff1a9b764e6523b3f17fc78a4e6f9515ff939ff05346326106e933848"
|
||||
},
|
||||
"skill-creation-walkthrough": {
|
||||
"SKILL.md": "d9562ff1d9ee3620cf728d0b7a062f2cc1a58508fcf9043b344bf23805e5608e",
|
||||
"references/description-cookbook.md": "b174690a9064f7b0cddb6aa289951321ecf96c34a7e18eed3307741fc0c76688",
|
||||
"references/methodology-vs-implementation.md": "f4fc2991e1ee8cafc3ed976dc3bbab10ceaee3a362df7e9b9461f9f491f64557",
|
||||
"references/skill-template.md": "f0e0e61d8183b9ad71179a060d99bea7f997f70f2e58e0d191491200f3213a93"
|
||||
},
|
||||
"stakeholder-communication": {
|
||||
"SKILL.md": "a3686760ebe73d64c55f37df38b9948a36fe3b291e3fc7e5c2b10212dbb78580",
|
||||
"references/update-templates.md": "fed66af683d5e0b6b88cc54734d5218584064749743df545f085d63a90823fb3"
|
||||
},
|
||||
"team-onboarding-playbook": {
|
||||
"SKILL.md": "185dade0ab8c88c197d664d8d7acca5bf1b106dfd1d314afb7f95792488960aa",
|
||||
"references/onboarding-checklist.md": "5309269c3f1336c51277de30f5cd8bde41aaa0b56c4c60c91cb4aae078748eb7"
|
||||
},
|
||||
"upgrade-flow-design": {
|
||||
"SKILL.md": "60041e7b729da406d0b674863487f187604e899ac6f26a71c496f16a1b5cb4c2",
|
||||
"references/churn-prevention-upstream.md": "d0f407c73f90ca41f896deca4b1889c21b1b168ccfcf09662222bf48724805e8",
|
||||
"references/common-upgrade-failures.md": "cf13f043259d72b02cad638b528f31f74db3face233aa3a6301a369bbd829366",
|
||||
"references/free-tier-decision-criteria.md": "7652fedbf15a951aa7bcb40d6d694c8bc54c806d8b1744162e018cd2ac6918ae",
|
||||
"references/paywall-presentation-patterns.md": "926a9d7cafe9f291cc6cab949fdc4181ad0bc512bdd2ef37976080cd70c30528",
|
||||
"references/plan-structure-patterns.md": "0384fffe5c71649e32028fc1c437daa4d700f3900d7aacaab773c6c4c6595897",
|
||||
"references/trigger-moment-design.md": "ff44f0fd8f278f4e8f5af5330cd4c0fb90d2d56e85fcd2f14579c08a296c1e88",
|
||||
"references/upgrade-flow-anti-patterns.md": "16d74c0b43a304b4af82d5e116cde8ed72144530e9d0c863553a2b764c48e66f",
|
||||
"references/upsell-vs-downsell-logic.md": "6fc45503c6228af8138b2cfc351bebb53580f032afcf3f64da1f0e8d3dd2207d",
|
||||
"references/win-back-flow-patterns.md": "91489d5e1b49254334eb75e09e2fcf7d93fe4d20dcf80d5c203d1dd83862045e"
|
||||
},
|
||||
"usability-testing": {
|
||||
"SKILL.md": "20a5eeeab1e6330f3c0934858b7e5624181255a6278b6d86e096b7f45c3e2efa",
|
||||
"references/task-script-patterns.md": "ef6f52b28935f89c671077692dc71c739e6bbff86f572fbd9e49746a3ed60ffc"
|
||||
},
|
||||
"user-feedback-aggregation": {
|
||||
"SKILL.md": "0e15fc40121b21d733b9a0738d7180efd931c508bcd40aa2beeec61b4ef409cc",
|
||||
"references/categorization-and-tagging-at-scale.md": "b32f86ca6c1408c0a4ae0c9782add748956b2139cb1b46fb13cb2e9211ad13c9",
|
||||
"references/channel-source-weighting.md": "57bdeb70e53273164c6471f6b4e662fe58baf76eafb6a16ac27c497849f4b876",
|
||||
"references/channel-types-and-what-each-surfaces.md": "19d44154994213c597e9150e66325e6e223f24a9349e2a1110892d124966f1a0",
|
||||
"references/closing-the-loop-with-users.md": "7795ce98dec28b859acbdaf2ddc0ce98da305bdcfa51a9c2408ef015ba573e9d",
|
||||
"references/common-feedback-aggregation-failures.md": "55b6b83283de8ab1733e3c6b35fa59757cb9148619ac208bb9a144fe0031ec16",
|
||||
"references/detecting-drift-in-feedback.md": "e7ef824cb41fcfcc8207f7c3f02d333af292432a386bc98518534a03ce9a4422",
|
||||
"references/frequency-vs-intensity.md": "1d6b37e905ee936a14fc30c3c22f78019eb20216514470f23c76e9f61bc1e395",
|
||||
"references/from-feedback-to-product-decision.md": "21d4e9a3d1c693c74bc1bbaf5fa6519c5c43f2fb309bf1c112c24fc686cc2d94",
|
||||
"references/tooling-considerations.md": "ae97ffe4bbbcbb3036bb8c2c3ced470f97a311f996c209f089f5853591adea7f"
|
||||
},
|
||||
"ux-research": {
|
||||
"SKILL.md": "0febd308046598e5f3004b7dac784a96b695e8e2a7c9be257a350424439f3ef1",
|
||||
"references/interview-guide-template.md": "1e5200c96ad7b02b75b7d38f2f343f24fd62cf8fa71c56462f9373b81820a207"
|
||||
},
|
||||
"vendor-evaluation": {
|
||||
"SKILL.md": "99a61bca3d0d2185ac225426e506e00b7cb882a9891c59d6ba6273e16b16ac4d",
|
||||
"references/evaluation-rubric.md": "955546c1813905f7362ac8579aa0e33ec844dd91c18c6279a6f3e0e09ee2e553"
|
||||
},
|
||||
"vertical-site-conventions": {
|
||||
"SKILL.md": "f7477db56b1ad8ae4ba7539cca137d4dc0d2577aa51b4709b92cbacef6a4b302",
|
||||
"references/shape-b2b-manufacturer.md": "d4bfeed8109ab099d44a494b8a9ea1d509c33dcbf4b91537647593f2454b61eb",
|
||||
"references/shape-conventions-checklist.md": "7a05af5427e74dbe85df1ad522b9bf5fd507dfcbddbedabef7b9ed2ac752d7c7",
|
||||
"references/shape-directory-marketplace.md": "07a763dadfb06db0c5aea036dfc2b911bff113e70a34483f3a86375fea4595a7",
|
||||
"references/shape-ecommerce-catalog.md": "dd6e1035986ef13af56795e24a7345905cfa0fb0e4899f7158430866cf9d05e6",
|
||||
"references/shape-ecommerce-standout.md": "95a36fa81428a16cacc34d0e8f05c2001fa4c65622166a7489e34b7e58879e6e",
|
||||
"references/shape-hospitality-experience.md": "8d3f0b8296227b7dfc65d50cccb7a097a000034d6119588046523a537d2acc36",
|
||||
"references/shape-hospitality-food.md": "18807c5d7cb1a2f28b2ee03ad8d67ca0399641e5c15a08bf1964a5d309978a68",
|
||||
"references/shape-institution-mission.md": "9e387053434d21931e083e4eb092fea2958a6954a57a9d9722619c4b2095fb7c",
|
||||
"references/shape-inventory-listing.md": "3301fa4c10d02d22fc4827bfb62702237fcc9fea424c2ee3b5bbb95714bf5b54",
|
||||
"references/shape-local-service-booking.md": "3f27d354c81fbb9f21f786df46ec722d1eac02735c28f458c1ff2a03cb6a75fe",
|
||||
"references/shape-subscription-app.md": "66550ed130fd9878666ebb16d03aff4f9aeb29232915f330c910b7aba4188807"
|
||||
}
|
||||
}
|
||||
@@ -0,0 +1,239 @@
|
||||
# Skill Authoring Guide
|
||||
|
||||
This doc locks in the structure every skill in this repo follows. If you contribute a skill, it follows this pattern. If you fork the repo, this is the pattern to replicate.
|
||||
|
||||
Uniformity is the point. A reader should be able to pick up any skill and know where to look for the trigger description, the framework, the workflow, and the references. No surprises.
|
||||
|
||||
---
|
||||
|
||||
## File structure
|
||||
|
||||
```
|
||||
skills/
|
||||
skill-name/
|
||||
SKILL.md (required)
|
||||
references/ (recommended)
|
||||
template.md (a fillable template the user can copy)
|
||||
checklist.md (a runbook or checklist for the work)
|
||||
example.md (one or two worked examples)
|
||||
[domain-deep-dive.md] (optional: deeper reference content)
|
||||
```
|
||||
|
||||
Skill folder names are lowercase, hyphenated, verb-noun or category-noun. `seo-onpage`, `brand-voice`, `code-review-web`. No org branding in skill names.
|
||||
|
||||
---
|
||||
|
||||
## SKILL.md structure
|
||||
|
||||
Every SKILL.md follows this exact section order. If a section does not apply, omit it cleanly. Do not invent new top-level sections.
|
||||
|
||||
The eight required headers are: `## When to use`, `## When NOT to use`, `## Required inputs`, `## The framework`, `## Workflow`, `## Failure patterns`, `## Output format`, `## Reference files`. Each header MUST start with the canonical text and MAY append a colon-suffix descriptive label (e.g., `## The framework: 5 phases`, `## The framework: brief structure`, `## Workflow for an active incident`). Do not rename the canonical word itself (no `## The brief structure` in place of `## The framework`).
|
||||
|
||||
**Optional `## Deep dive: [topic]` sections.** Teaching skills (skills whose primary job is to instruct the reader on a craft, not to produce a deliverable) MAY add `## Deep dive: [topic]` sections after `## Workflow` and before `## Failure patterns` for pedagogical depth that does not fit inside the canonical sections. The `Deep dive:` prefix is the only sanctioned non-canonical section pattern. Use it sparingly: most skills should not need any deep dives, and a skill with more than two is a signal the content should split into reference files. This is not a license for arbitrary section drift; the canonical eight still carry the load.
|
||||
|
||||
```markdown
|
||||
---
|
||||
name: skill-name
|
||||
description: "A pushy, trigger-rich description. Two to four sentences. See description rules below."
|
||||
category: category-id
|
||||
catalog_summary: "One-line description for the README catalog table"
|
||||
display_order: 1
|
||||
---
|
||||
|
||||
# Skill Name
|
||||
|
||||
[One sentence purpose statement. What this skill does in plain language.]
|
||||
|
||||
---
|
||||
|
||||
## When to use
|
||||
|
||||
- [Bullet 1]
|
||||
- [Bullet 2]
|
||||
- [Bullet 3]
|
||||
|
||||
## When NOT to use
|
||||
|
||||
- [Bullet 1, with redirect to the right skill]
|
||||
- [Bullet 2]
|
||||
|
||||
---
|
||||
|
||||
## Required inputs
|
||||
|
||||
[List of things the skill needs before producing output. If it can elicit them, say so.]
|
||||
|
||||
---
|
||||
|
||||
## The framework
|
||||
|
||||
[The core methodology. Could be sections, dimensions, layers, or steps. This is the durable IP of the skill.]
|
||||
|
||||
---
|
||||
|
||||
## Workflow
|
||||
|
||||
1. [Step 1]
|
||||
2. [Step 2]
|
||||
3. [Step 3]
|
||||
...
|
||||
|
||||
---
|
||||
|
||||
## Failure patterns
|
||||
|
||||
[Patterns that signal the work is going wrong. What to push back on.]
|
||||
|
||||
---
|
||||
|
||||
## Output format
|
||||
|
||||
[What the deliverable looks like, where it goes, naming conventions.]
|
||||
|
||||
---
|
||||
|
||||
## Reference files
|
||||
|
||||
- `references/file.md` - [What it is and when to read it]
|
||||
- `references/file.md` - [What it is and when to read it]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Frontmatter fields
|
||||
|
||||
Every SKILL.md frontmatter has five required fields. The first two are the trigger surface; the last three drive the README catalog generator.
|
||||
|
||||
| Field | Type | Notes |
|
||||
|---|---|---|
|
||||
| `name` | string | Must match the folder name. Used by Claude when loading the skill. |
|
||||
| `description` | string | 2 to 4 sentences. See description rules below. |
|
||||
| `category` | string | One of: `strategy-and-discovery`, `brand`, `design`, `content`, `seo-foundation`, `seo-audit-suite`, `product`, `development`, `qa`, `operations`, `growth`, `research`, `cross-cutting`, `process-and-team`. Determines the catalog section the skill renders into. |
|
||||
| `catalog_summary` | string | One-line description used as the third column of the catalog table. Aim for under 140 characters. No trailing punctuation. |
|
||||
| `display_order` | integer | Position within the category. Smallest first. Skills with no `display_order` render after the ordered ones, alphabetically by slug. |
|
||||
|
||||
After editing any of these fields, run `python scripts/generate_readme_catalog.py --write` to regenerate the README catalog content. CI runs `--check` and fails the build if the README is out of sync.
|
||||
|
||||
---
|
||||
|
||||
## Description rules
|
||||
|
||||
The description is the most important part of the skill. It is the only thing Claude reads on every turn. Good descriptions trigger reliably. Bad descriptions either over-trigger (annoying) or under-trigger (useless).
|
||||
|
||||
**Format:** 2 to 4 sentences, in quotes in the YAML frontmatter.
|
||||
|
||||
**Sentence 1:** What the skill does and the artifact it produces.
|
||||
|
||||
**Sentence 2:** Explicit "use this skill whenever the user..." with verbs and contexts.
|
||||
|
||||
**Sentence 3 (optional):** A list of trigger phrases ("Triggers on X, Y, Z"). Be generous. Cover synonyms, common typos, and casual phrasings.
|
||||
|
||||
**Sentence 4 (optional):** Edge case triggers. "Also triggers when the user [implicit case], even if they do not say [explicit term]."
|
||||
|
||||
**Be pushy.** Claude tends to under-trigger skills. The description should err toward triggering when relevant rather than waiting for a perfect match.
|
||||
|
||||
**Bad description:**
|
||||
> "A skill for SEO audits."
|
||||
|
||||
**Good description:**
|
||||
> "Run a comprehensive on-page SEO audit covering title tags, meta descriptions, header structure, content quality, internal links, image optimization, and URL hygiene. Use this skill whenever the user asks to optimize a page, audit on-page SEO, fix titles or meta tags, review headers, check internal linking, or improve a single URL's search performance. Triggers on on-page SEO, page audit, title tag, meta description, H1, header structure, internal links, image alt, URL slug, page optimization. Also triggers for any single-page review where ranking or click-through is the goal."
|
||||
|
||||
---
|
||||
|
||||
## Length rules
|
||||
|
||||
- **SKILL.md**: aim for under 250 lines. Hard cap at 500.
|
||||
- **Reference files**: aim for under 400 lines. If longer, add a table of contents at the top.
|
||||
- **Whole skill folder**: a reader should be able to scan everything in 15 minutes.
|
||||
|
||||
If a skill is bursting past these limits, that is a signal it should split into two skills.
|
||||
|
||||
---
|
||||
|
||||
## Voice and style rules
|
||||
|
||||
- **Punchy short sentences.** Default to declarative. Earn every long sentence.
|
||||
- **No em dashes.** Use commas, parens, periods, or colons. (See `creative-brief/references/voice-and-tone-guide.md` for the full voice argument; we picked a side for this repo.)
|
||||
- **Direct address.** Talk to the reader as "you." Talk about the user as "the user."
|
||||
- **No hype words.** Skip "leverage," "synergy," "best-in-class," "cutting-edge," "revolutionary." If a sentence works without them, they were padding.
|
||||
- **Concrete examples beat abstract advice.** If you write a principle, follow it with one specific example.
|
||||
|
||||
---
|
||||
|
||||
## Future-proofing rules
|
||||
|
||||
These skills are meant to age well. Five years from now, "your favorite framework" will be different. The principles will be the same.
|
||||
|
||||
**Do reference:**
|
||||
- W3C and WHATWG specs (HTML, CSS, ARIA, HTTP)
|
||||
- Schema.org vocabulary
|
||||
- WCAG accessibility levels
|
||||
- MDN Web Docs (for browser APIs)
|
||||
- Nielsen Norman Group (for UX principles)
|
||||
- Stable concepts: semantic HTML, progressive enhancement, REST, content security, signal-to-noise
|
||||
|
||||
**Do NOT reference:**
|
||||
- Specific framework versions ("React 18", "Next.js 14") - say "your component framework" or give the principle
|
||||
- Specific algorithm updates by name (they get superseded)
|
||||
- Specific tool versions or pricing tiers (they change)
|
||||
- This year's trending technique (it might not trend next year)
|
||||
- Vendor-specific marketing terms
|
||||
|
||||
When you must name a tool, name 2 to 3 alternatives or write "your X tool of choice." This protects the reader who uses something you didn't think of.
|
||||
|
||||
---
|
||||
|
||||
## Stack-agnostic rules
|
||||
|
||||
Every skill must work for someone on Next.js, WordPress, Shopify, Webflow, plain HTML, or whatever comes next.
|
||||
|
||||
- **Default to principle.** "Set the canonical tag to the production URL" works everywhere. "Use the `metadata` export in app/layout.tsx" only works in Next.js App Router.
|
||||
- **Stack-specific patterns go in reference files**, not SKILL.md. Name them clearly: `references/nextjs-patterns.md`, `references/wordpress-patterns.md`.
|
||||
- **In SKILL.md, point at the reference**: "If using Next.js, see `references/nextjs-patterns.md` for the App Router and Pages Router equivalents."
|
||||
|
||||
---
|
||||
|
||||
## Reference files
|
||||
|
||||
Every skill should ship with at least one reference file. The strongest skills have three: a template, a checklist, and an example.
|
||||
|
||||
**Templates** are fillable. Copy and use. Markdown structure with bracketed fields the user replaces.
|
||||
|
||||
**Checklists** are runnable. Items the user (or Claude) verifies one by one before declaring the work done.
|
||||
|
||||
**Examples** are filled-in versions of the template, applied to a fictional but realistic case. Show what "good" looks like.
|
||||
|
||||
Reference files use the same voice and length rules as SKILL.md.
|
||||
|
||||
---
|
||||
|
||||
## Naming conventions
|
||||
|
||||
| Type | Pattern | Example |
|
||||
|---|---|---|
|
||||
| Skill folder | lowercase-hyphenated | `seo-onpage` |
|
||||
| SKILL.md | exactly `SKILL.md` | `SKILL.md` |
|
||||
| Template | `[noun]-template.md` | `audit-template.md` |
|
||||
| Checklist | `[noun]-checklist.md` | `prelaunch-checklist.md` |
|
||||
| Example | `example-[scenario].md` | `example-saas-brief.md` |
|
||||
| Stack guide | `[stack]-patterns.md` | `nextjs-patterns.md` |
|
||||
| Domain reference | `[topic]-guide.md` or `[topic]-reference.md` | `voice-and-tone-guide.md` |
|
||||
|
||||
---
|
||||
|
||||
## Triggering checklist
|
||||
|
||||
Before publishing a skill, run this check:
|
||||
|
||||
- [ ] Does the description name the artifact produced?
|
||||
- [ ] Does the description list at least 5 trigger phrases?
|
||||
- [ ] Does it cover at least one implicit trigger ("even if they do not say...")?
|
||||
- [ ] Does the SKILL.md have a "When NOT to use" section that points at sibling skills?
|
||||
- [ ] Is the framework section the durable IP, or is it filler?
|
||||
- [ ] Does the workflow have numbered steps a reader can follow?
|
||||
- [ ] Does the failure-patterns section call out specific bad inputs to push back on?
|
||||
- [ ] Are reference files actually referenced from SKILL.md with guidance on when to read them?
|
||||
- [ ] Does it work without any specific tool or framework named?
|
||||
- [ ] Has someone (you) used it on a real project at least once before publishing?
|
||||
|
||||
If all 10 boxes check, ship it. If they don't, rewrite.
|
||||
@@ -0,0 +1,77 @@
|
||||
{
|
||||
"autonomy-review": {
|
||||
"file": "autonomy-review.md",
|
||||
"sha256": "14bf6e2a8188c92c816529b95ebbb3e3e6f4b1a43df67ebbf68024e1ab72ecc3",
|
||||
"status": "template"
|
||||
},
|
||||
"ci-prove-gate-wiring": {
|
||||
"file": "ci-prove-gate-wiring.md",
|
||||
"sha256": "137d850bef7d84b4c0351e8b85a37c77aea8674dd93c9d2b7d5de9be8e75ac17",
|
||||
"status": "template"
|
||||
},
|
||||
"content-pipeline-prove-gates": {
|
||||
"file": "content-pipeline-prove-gates.md",
|
||||
"sha256": "31948660c4d2c97098edb79c3ca88b123dd0e9f54fd6643c65ddf49ed39c4431",
|
||||
"status": "validated"
|
||||
},
|
||||
"conversion-by-source-diagnosis": {
|
||||
"file": "conversion-by-source-diagnosis.md",
|
||||
"sha256": "56c2965d1612f152365fac22fae68b41d0e8f9a7c2016fbaaaf95d2e1c8e9908",
|
||||
"status": "template"
|
||||
},
|
||||
"corpus-integrity-and-correction": {
|
||||
"file": "corpus-integrity-and-correction.md",
|
||||
"sha256": "f700641957273b279a9656b5bb5b4675bfddc1a6db2759abea8fff4607e15832",
|
||||
"status": "template"
|
||||
},
|
||||
"data-surface-integrity": {
|
||||
"file": "data-surface-integrity.md",
|
||||
"sha256": "786f573deff77b6182064d98a2ded989e8ab30dad7d5a75269bc29e3bfb27241",
|
||||
"status": "template"
|
||||
},
|
||||
"experiment-loop-with-pre-registered-gates": {
|
||||
"file": "experiment-loop-with-pre-registered-gates.md",
|
||||
"sha256": "cb64aac8a19f31f87d0631a1b9f6e1b054458949ea2c40a6349611ce79a5784b",
|
||||
"status": "template"
|
||||
},
|
||||
"incident-response-and-lane-demotion": {
|
||||
"file": "incident-response-and-lane-demotion.md",
|
||||
"sha256": "e547a5cff6fcdf990bf630faf4f4846aa3d5bae69d9eb30752bf4861eae2e0bb",
|
||||
"status": "template"
|
||||
},
|
||||
"link-graph-and-metadata-parity-audit": {
|
||||
"file": "link-graph-and-metadata-parity-audit.md",
|
||||
"sha256": "b541c4f63c63a29191c913bc8f3620d365c2a4776694a4df1011c8f200ea5fe3",
|
||||
"status": "template"
|
||||
},
|
||||
"migration-with-verification": {
|
||||
"file": "migration-with-verification.md",
|
||||
"sha256": "20524d52acc1739745560d09ebb7b8b0500204c4bbf4e1a7d9dbef99e55565b6",
|
||||
"status": "template"
|
||||
},
|
||||
"post-deploy-live-verification": {
|
||||
"file": "post-deploy-live-verification.md",
|
||||
"sha256": "944d20aa8740eb54f12fba5457b3f897b4f66cbed7a20e09dc89341e11bea90c",
|
||||
"status": "template"
|
||||
},
|
||||
"regulated-content-compliance-gate": {
|
||||
"file": "regulated-content-compliance-gate.md",
|
||||
"sha256": "b518f64433a1ff410f003a3d2ec81d8ea957c962f3aa4aaf6057b7cb74210254",
|
||||
"status": "template"
|
||||
},
|
||||
"revenue-tracking-integrity": {
|
||||
"file": "revenue-tracking-integrity.md",
|
||||
"sha256": "9a94e01de89e4a5e79c276ecee1618ce3a958ef2f40fa3bf6089e37d707f1ddd",
|
||||
"status": "template"
|
||||
},
|
||||
"traffic-drop-triage": {
|
||||
"file": "traffic-drop-triage.md",
|
||||
"sha256": "2f00f2c4f2d08e0df0699d057b5061300254a2adb0b9f7344eee2d9cf5cf8569",
|
||||
"status": "template"
|
||||
},
|
||||
"warehouse-data-plane-standup": {
|
||||
"file": "warehouse-data-plane-standup.md",
|
||||
"sha256": "0d1b753d34023c8344b5f4bb5ecc9a74a644a7a1a8fff1ba80bb11eec413d303",
|
||||
"status": "template"
|
||||
}
|
||||
}
|
||||
Binary file not shown.
|
After Width: | Height: | Size: 573 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 539 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 518 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 556 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 60 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 104 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 58 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 105 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 299 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 202 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 140 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 104 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 483 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 483 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 112 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 266 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 373 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 192 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 184 KiB |
+239
@@ -0,0 +1,239 @@
|
||||
---
|
||||
name: accessibility-audit
|
||||
description: "Run a comprehensive WCAG accessibility audit covering perceivable, operable, understandable, and robust principles. Use this skill whenever the user wants to audit accessibility, review WCAG compliance, fix accessibility issues, prepare for accessibility certification, address an accessibility lawsuit risk, or systematically improve a site's accessibility. Triggers on accessibility audit, WCAG audit, a11y audit, accessibility compliance, ADA compliance, screen reader test, keyboard navigation, accessibility report, fix accessibility, axe scan. Also triggers when accessibility issues have been reported and need systematic remediation."
|
||||
category: development
|
||||
catalog_summary: "WCAG compliance audit with remediation plan"
|
||||
display_order: 3
|
||||
---
|
||||
|
||||
# Accessibility Audit
|
||||
|
||||
Run a thorough accessibility audit and produce a remediation plan. Stack-agnostic. Anchored to WCAG 2.1 AA, with notes on AAA where relevant.
|
||||
|
||||
This skill goes deeper than the accessibility checks in `qa-testing` and `design-standards`. Use this when accessibility itself is the goal.
|
||||
|
||||
---
|
||||
|
||||
## When to use
|
||||
|
||||
- Pre-launch accessibility verification
|
||||
- Compliance preparation (ADA, EN 301 549, AODA, Section 508)
|
||||
- Remediation after an audit finding or complaint
|
||||
- Annual or quarterly accessibility health check
|
||||
- Onboarding accessibility into a team that hasn't prioritized it before
|
||||
|
||||
## When NOT to use
|
||||
|
||||
- General QA after deploys (use `qa-testing`)
|
||||
- Component-level accessibility implementation (use `frontend-component-build`)
|
||||
- Color contrast for design tokens (use `design-standards` or `brand-identity`)
|
||||
|
||||
---
|
||||
|
||||
## Required inputs
|
||||
|
||||
- The site or product under audit
|
||||
- The scope (full site, specific section, specific user flow)
|
||||
- The target standard (WCAG 2.1 AA is most common)
|
||||
- Any specific concerns or known issues
|
||||
- Tools available (automated scanners, screen readers, manual testing)
|
||||
|
||||
---
|
||||
|
||||
## The framework: WCAG's 4 principles
|
||||
|
||||
WCAG organizes accessibility around four principles. The audit covers each in depth.
|
||||
|
||||
### 1. Perceivable
|
||||
|
||||
Information and UI must be presentable in ways users can perceive.
|
||||
|
||||
**Audit checks:**
|
||||
|
||||
- **Text alternatives.** All non-decorative images have descriptive `alt` text. Decorative images use `alt=""`. Complex images (charts, infographics) have long descriptions.
|
||||
- **Time-based media.** Videos have captions. Pre-recorded audio has transcripts. Live audio has live captions where required.
|
||||
- **Adaptable.** Content structure is conveyed through markup (semantic HTML), not just visual styling. Reading order makes sense when CSS is disabled.
|
||||
- **Distinguishable.** Color is not the sole means of conveying information. Text contrast meets AA (4.5:1 normal, 3:1 large). UI element contrast meets 3:1. Audio can be paused, stopped, or muted.
|
||||
|
||||
### 2. Operable
|
||||
|
||||
UI components and navigation must be operable.
|
||||
|
||||
**Audit checks:**
|
||||
|
||||
- **Keyboard accessible.** All functionality available via keyboard alone. No keyboard traps. Focus visible.
|
||||
- **Enough time.** Time limits can be adjusted, paused, or extended. Auto-updating content can be paused.
|
||||
- **Seizures and physical reactions.** No content that flashes more than 3 times per second.
|
||||
- **Navigable.** Skip links present. Pages have descriptive titles. Focus order is logical. Link purpose clear from text or context. Multiple ways to find pages (sitemap, search, navigation). Headings and labels are descriptive.
|
||||
- **Input modalities.** Pointer gestures have keyboard alternatives. Pointer cancellation supported (mouse-up, not mouse-down for activation). Labels match accessible names. Motion-triggered functionality has alternatives.
|
||||
|
||||
### 3. Understandable
|
||||
|
||||
Information and operation must be understandable.
|
||||
|
||||
**Audit checks:**
|
||||
|
||||
- **Readable.** Page language declared (`<html lang="...">`). Unusual words and abbreviations have definitions or expansions. Reading level appropriate to audience.
|
||||
- **Predictable.** Focus does not change context unexpectedly. Input does not change context unexpectedly. Navigation is consistent across pages. Components that look similar behave similarly.
|
||||
- **Input assistance.** Errors are identified clearly. Labels and instructions are provided for input. Error suggestions are given where possible. For pages handling legal commitments or financial transactions, errors can be reviewed and corrected before submission.
|
||||
|
||||
### 4. Robust
|
||||
|
||||
Content must be robust enough to work with current and future user agents.
|
||||
|
||||
**Audit checks:**
|
||||
|
||||
- **Compatible.** Markup is valid. Name, role, and value of UI components are programmatically determinable. Status messages can be programmatically determined and announced.
|
||||
|
||||
---
|
||||
|
||||
## Audit methodology
|
||||
|
||||
### Stage 1: Automated scan
|
||||
|
||||
Run automated scanners across the priority pages. These catch 30 to 50 percent of issues but miss the rest.
|
||||
|
||||
**Tools:**
|
||||
- axe DevTools (browser extension)
|
||||
- Lighthouse (Chrome DevTools accessibility audit)
|
||||
- WAVE (browser extension)
|
||||
- Pa11y (CLI for batch scanning)
|
||||
|
||||
**Output:** A list of automated findings, by page.
|
||||
|
||||
### Stage 2: Manual keyboard testing
|
||||
|
||||
Unplug the mouse. Navigate the priority user flows using only keyboard.
|
||||
|
||||
**Test:**
|
||||
- Tab and Shift+Tab move through interactive elements in logical order
|
||||
- Enter activates buttons and links
|
||||
- Space activates buttons (and toggles checkboxes)
|
||||
- Arrow keys navigate within composite widgets (tabs, menus, listboxes)
|
||||
- Escape dismisses modals, popovers, menus
|
||||
- Focus is always visible
|
||||
- Focus returns to a sensible place after modals or popovers close
|
||||
- No keyboard trap (focus can always leave)
|
||||
|
||||
**Document:** Any flow where keyboard navigation breaks down.
|
||||
|
||||
### Stage 3: Screen reader testing
|
||||
|
||||
Test with at least one real screen reader. Each combination has quirks.
|
||||
|
||||
**Common combinations:**
|
||||
- VoiceOver + Safari (macOS / iOS)
|
||||
- NVDA + Firefox or Chrome (Windows)
|
||||
- JAWS + Chrome (Windows; commercial but common in enterprise)
|
||||
- TalkBack + Chrome (Android)
|
||||
|
||||
**Test:**
|
||||
- Page structure announced correctly (headings, landmarks)
|
||||
- Form labels read with their inputs
|
||||
- Errors announced when they appear
|
||||
- Status changes announced (loading, success, error)
|
||||
- Modal context announced when opened
|
||||
- Images have meaningful alt text (or are correctly identified as decorative)
|
||||
|
||||
### Stage 4: Visual testing
|
||||
|
||||
Verify the visual aspects of accessibility.
|
||||
|
||||
**Test:**
|
||||
- Color contrast for all text/background pairs (use a contrast checker)
|
||||
- UI element contrast (3:1 for icons, borders, focus rings)
|
||||
- Color-blindness simulation (deuteranopia at minimum)
|
||||
- Zoom to 200% - content remains usable, no horizontal scroll
|
||||
- Reflow at 320px viewport
|
||||
- Text spacing applied (line height, letter spacing) - no content cut off
|
||||
- Motion can be reduced (`prefers-reduced-motion` honored)
|
||||
|
||||
### Stage 5: Cognitive accessibility
|
||||
|
||||
Often overlooked. Critical for inclusive products.
|
||||
|
||||
**Test:**
|
||||
- Reading level appropriate
|
||||
- Instructions clear
|
||||
- Error messages explain how to fix the error, not just that one occurred
|
||||
- Forms allow correction before submission
|
||||
- Time limits avoidable or extendable
|
||||
- Important content not dependent on memory of prior pages
|
||||
|
||||
---
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Define scope.** Full site? Specific flows? Specific page templates?
|
||||
2. **Run automated scans.** Document findings per page.
|
||||
3. **Manual keyboard pass.** Test all priority flows.
|
||||
4. **Screen reader pass.** Test with at least one combination.
|
||||
5. **Visual checks.** Contrast, zoom, color blindness, motion.
|
||||
6. **Cognitive checks.** Reading level, error handling, time limits.
|
||||
7. **Score against WCAG.** Per success criterion (level A, AA, AAA).
|
||||
8. **Prioritize findings.** Critical (blocks users), Important (degrades experience), Minor (polish).
|
||||
9. **Write the report.** Use the template in [`references/audit-report-template.md`](references/audit-report-template.md).
|
||||
10. **Build a remediation plan.** Sequenced fixes with effort and impact estimates.
|
||||
|
||||
---
|
||||
|
||||
## Severity classification
|
||||
|
||||
For prioritization:
|
||||
|
||||
**Critical (P0):**
|
||||
- Blocks an entire user flow for an assistive-tech user
|
||||
- Renders a key page completely inaccessible
|
||||
- Examples: form with no labels, modal without focus management, primary CTA not keyboard-accessible
|
||||
|
||||
**Important (P1):**
|
||||
- Significantly degrades the experience for assistive-tech users
|
||||
- Examples: missing alt text on key images, low-contrast body text, error messages that don't announce
|
||||
|
||||
**Minor (P2):**
|
||||
- Affects edge cases or specific assistive technology combinations
|
||||
- Examples: minor focus order issues, missing decorative alt attributes, edge case keyboard handling
|
||||
|
||||
**Polish (P3):**
|
||||
- Above-AA improvements that benefit accessibility but aren't compliance-blocking
|
||||
- Examples: AAA contrast targets, additional reduced-motion variants, language attributes on inline foreign words
|
||||
|
||||
---
|
||||
|
||||
## Failure patterns
|
||||
|
||||
- **Automated scan only.** Catches 30 to 50 percent of issues. The remaining 50 to 70 percent are in keyboard, screen reader, and cognitive testing.
|
||||
- **Testing only on the home page.** The home page is usually the most accessible. Bugs hide in deeper flows.
|
||||
- **Treating accessibility as a one-time project.** Accessibility erodes with every deploy. Bake it into the development cycle.
|
||||
- **Fixing without root cause.** Patching individual issues without understanding why they happened means new ones keep appearing.
|
||||
- **Ignoring screen reader testing.** Hard to do well, easy to skip. Single biggest source of "we thought we were accessible" surprises.
|
||||
- **Confusing AA and AAA.** AAA is rarely the right target. AA is the practical baseline for most products.
|
||||
- **Treating accessibility as a designer or developer responsibility alone.** Content, product, QA, and leadership all need to participate.
|
||||
- **Assuming compliance equals accessibility.** WCAG conformance is a floor, not a ceiling. Real users may still struggle.
|
||||
|
||||
---
|
||||
|
||||
## Output format
|
||||
|
||||
Default output is a comprehensive audit report at `accessibility-audit.md`.
|
||||
|
||||
Structure:
|
||||
1. Executive summary
|
||||
2. Methodology (tools used, pages tested, screen readers used)
|
||||
3. Findings by WCAG principle
|
||||
4. Critical findings (P0) with specific URLs and fixes
|
||||
5. Important findings (P1)
|
||||
6. Minor findings (P2)
|
||||
7. Polish (P3)
|
||||
8. Remediation roadmap (sequenced and prioritized)
|
||||
9. Appendices (full automated scan results, keyboard navigation notes, screen reader notes)
|
||||
|
||||
Plus a remediation tracking spreadsheet with one row per finding.
|
||||
|
||||
---
|
||||
|
||||
## Reference files
|
||||
|
||||
- [`references/audit-report-template.md`](references/audit-report-template.md) - Full audit report template.
|
||||
- [`references/wcag-quick-reference.md`](references/wcag-quick-reference.md) - Condensed WCAG 2.1 AA criteria with audit checks.
|
||||
- [`references/aria-patterns.md`](references/aria-patterns.md) - Decision-grade ARIA patterns. Semantic-HTML-first principle, common interactive widgets (accordion, tabs, modal, toggle, disclosure, navigation), live regions, hiding patterns, labeling, state indicators, anti-patterns.
|
||||
@@ -0,0 +1,471 @@
|
||||
# ARIA patterns reference
|
||||
|
||||
Decision-grade ARIA patterns for the audit. Covers when to use ARIA, when to skip it, and the common patterns that recur across web products.
|
||||
|
||||
ARIA is powerful and easy to misuse. The most common mistake is reaching for ARIA when semantic HTML would have done the job already. The second most common mistake is applying ARIA without the supporting JavaScript that makes the attribute true (e.g., `aria-expanded="false"` on a button that does not actually toggle anything).
|
||||
|
||||
This file expands the audit checks in [SKILL.md](../SKILL.md) with the specific patterns auditors should verify and the anti-patterns to flag.
|
||||
|
||||
---
|
||||
|
||||
## The semantic-HTML-first principle
|
||||
|
||||
Before reaching for ARIA, check whether semantic HTML already does what is needed.
|
||||
|
||||
**The principle.** ARIA exists to fill gaps in HTML. When semantic HTML provides the same semantics natively, the semantic element is the right answer. Adding ARIA on top of semantic HTML is usually redundant and sometimes broken.
|
||||
|
||||
**Examples of redundant ARIA.**
|
||||
|
||||
- `<button role="button">` is redundant; the element is already a button.
|
||||
- `<nav role="navigation">` is redundant; `<nav>` already has the role.
|
||||
- `<a href="..." role="link">` is redundant; the element is already a link.
|
||||
- `<input type="checkbox" role="checkbox">` is redundant.
|
||||
|
||||
**Examples of correct ARIA.**
|
||||
|
||||
- A `<div>` styled to behave like a button needs `role="button"`. A real `<button>` does not.
|
||||
- A custom dropdown built on `<div>`s needs `role="combobox"` plus full keyboard handling. A `<select>` does not.
|
||||
- A live status region needs `role="status"` or `aria-live`. A static element does not.
|
||||
|
||||
**The audit check.** For every ARIA attribute on a page, ask: would this element have the same semantics without ARIA? If yes, the ARIA is redundant; flag it.
|
||||
|
||||
**The first ARIA rule.** No ARIA is better than bad ARIA. Bad ARIA actively confuses assistive technology; missing ARIA at most leaves a feature inaccessible (which is bad, but recoverable). Bad ARIA misrepresents the UI to the user, which is worse.
|
||||
|
||||
---
|
||||
|
||||
## Interactive widget patterns
|
||||
|
||||
Patterns that recur across products.
|
||||
|
||||
### Accordion (expandable disclosure section)
|
||||
|
||||
**Required ARIA.**
|
||||
|
||||
- Trigger button: `aria-expanded="true"` or `aria-expanded="false"` reflecting state.
|
||||
- Trigger button: `aria-controls="<id-of-panel>"` pointing to the controlled region.
|
||||
- Panel: `id="<the-id>"` matching `aria-controls`.
|
||||
|
||||
**Required behavior.**
|
||||
|
||||
- Trigger is a `<button>` (not a `<div>` or `<a>`).
|
||||
- Trigger toggles `aria-expanded` when activated.
|
||||
- Click and keyboard (Enter, Space) both work.
|
||||
|
||||
**Audit checks.**
|
||||
|
||||
- `aria-expanded` reflects current state, not a stale value.
|
||||
- `aria-controls` ID exists in the DOM.
|
||||
- Multiple accordions on a page: focus stays on trigger after toggle (does not jump unexpectedly).
|
||||
|
||||
### Tabs
|
||||
|
||||
**Required ARIA.**
|
||||
|
||||
- Tab list: `role="tablist"`.
|
||||
- Each tab: `role="tab"`, `aria-selected="true"` or `aria-selected="false"`, `aria-controls="<panel-id>"`.
|
||||
- Each panel: `role="tabpanel"`, `id="<panel-id>"`, `aria-labelledby="<tab-id>"`.
|
||||
|
||||
**Required behavior.**
|
||||
|
||||
- Arrow keys move between tabs.
|
||||
- Tab key moves into and out of the tablist (not between tabs).
|
||||
- Selected tab has `tabindex="0"`; non-selected tabs have `tabindex="-1"` (roving tabindex).
|
||||
- Activating a tab updates `aria-selected` and shows the corresponding panel.
|
||||
|
||||
**Audit checks.**
|
||||
|
||||
- All tabs reachable via arrow keys.
|
||||
- Tab key escapes the tablist after one press.
|
||||
- Only one tab has `aria-selected="true"` at a time.
|
||||
|
||||
### Modal / dialog
|
||||
|
||||
**Required ARIA.**
|
||||
|
||||
- Container: `role="dialog"` (or `role="alertdialog"` for confirmations).
|
||||
- Container: `aria-modal="true"` when modal.
|
||||
- Container: `aria-labelledby="<heading-id>"` pointing to the dialog's heading, or `aria-label="<purpose>"`.
|
||||
- Optional: `aria-describedby="<description-id>"` pointing to descriptive content.
|
||||
|
||||
**Required behavior.**
|
||||
|
||||
- Focus moves into the modal when opened (typically to the first focusable element or the dialog itself).
|
||||
- Focus is trapped within the modal while open (Tab cycles within; cannot escape).
|
||||
- Escape closes the modal.
|
||||
- Focus returns to the triggering element when the modal closes.
|
||||
- Background content has `inert` attribute or `aria-hidden="true"` (and is not focusable).
|
||||
|
||||
**Audit checks.**
|
||||
|
||||
- Focus management on open and close (the most common modal failure).
|
||||
- Tab does not escape into background content.
|
||||
- Screen reader does not read background content while modal is open.
|
||||
|
||||
### Toggle button (button that holds state)
|
||||
|
||||
**Required ARIA.**
|
||||
|
||||
- `aria-pressed="true"` or `aria-pressed="false"` reflecting state.
|
||||
|
||||
**Examples.** Mute button, favorite button, bold/italic in a text editor.
|
||||
|
||||
**Audit checks.**
|
||||
|
||||
- `aria-pressed` reflects state, not a stale value.
|
||||
- Toggling produces an audible state change (some screen readers announce the new pressed state).
|
||||
- Use of toggle button is appropriate (the button is genuinely a toggle, not a momentary action).
|
||||
|
||||
### Disclosure widget (show/hide additional content)
|
||||
|
||||
**Required ARIA.**
|
||||
|
||||
- Trigger: `<button>` with `aria-expanded="true"` or `aria-expanded="false"`.
|
||||
- Optional: `aria-controls="<region-id>"` if the controlled region is not adjacent.
|
||||
|
||||
**Examples.** "Show more" buttons, "Read more" expansions.
|
||||
|
||||
**Difference from accordion.** Accordions are typically grouped (multiple panels in a related set, often only one open at a time); disclosure widgets are standalone reveals. The ARIA is similar; the surrounding pattern differs.
|
||||
|
||||
### Navigation
|
||||
|
||||
**Required ARIA.**
|
||||
|
||||
- `<nav>` element (semantic; no `role="navigation"` needed).
|
||||
- For multiple navs on a page: each `<nav>` should have `aria-label` or `aria-labelledby` to distinguish them ("Primary", "Footer", "Breadcrumb").
|
||||
- Current page link: `aria-current="page"`.
|
||||
|
||||
**Audit checks.**
|
||||
|
||||
- Multiple navs are distinguishable to screen readers.
|
||||
- The current page is identified.
|
||||
- Skip link is present and works (typically "Skip to main content").
|
||||
|
||||
---
|
||||
|
||||
## Live region patterns
|
||||
|
||||
Regions that announce dynamically.
|
||||
|
||||
### aria-live
|
||||
|
||||
**Values.**
|
||||
|
||||
- `aria-live="polite"`: announces when the user is idle. Most common.
|
||||
- `aria-live="assertive"`: announces immediately, interrupting the user. Use sparingly.
|
||||
- `aria-live="off"`: do not announce. Default; rarely set explicitly.
|
||||
|
||||
**The polite-vs-assertive choice.**
|
||||
|
||||
- Polite for status updates that can wait (form save confirmation, content updates).
|
||||
- Assertive for urgent messages (errors that block submission, session timeout warnings, security alerts).
|
||||
|
||||
**Anti-pattern.** Assertive on routine updates. The screen reader interrupts whatever the user was doing; trust degrades quickly.
|
||||
|
||||
### aria-atomic
|
||||
|
||||
`aria-atomic="true"` tells screen readers to announce the entire region when any part changes, not just the changed part.
|
||||
|
||||
**When to use.** When the announcement only makes sense in context (e.g., "5 of 10 items processed" should announce as a whole, not just "5").
|
||||
|
||||
**When not to use.** For long regions where atomic announcements would be repetitive.
|
||||
|
||||
### role="status"
|
||||
|
||||
Implicit `aria-live="polite"`. Use for non-urgent status messages.
|
||||
|
||||
**Examples.** "Item added to cart," "Form saved," "Loading complete."
|
||||
|
||||
### role="alert"
|
||||
|
||||
Implicit `aria-live="assertive"` and `aria-atomic="true"`. Use for urgent messages.
|
||||
|
||||
**Examples.** Form submission errors, session timeout warnings, security alerts.
|
||||
|
||||
**Audit checks.**
|
||||
|
||||
- Status and alert regions exist where needed (audit dynamic flows).
|
||||
- They announce when content changes (test with screen reader).
|
||||
- The region is not assertive when polite would do.
|
||||
- The region is not used for static content (status/alert are for dynamic announcements).
|
||||
|
||||
---
|
||||
|
||||
## Hiding from screen reader patterns
|
||||
|
||||
When and how to hide content.
|
||||
|
||||
### aria-hidden
|
||||
|
||||
`aria-hidden="true"` removes the element and its children from the accessibility tree.
|
||||
|
||||
**When to use.**
|
||||
|
||||
- Decorative icons that have an adjacent text label (the icon is redundant; hide it).
|
||||
- Background visual elements that have no semantic meaning.
|
||||
- Modal closed state (when not using `inert`).
|
||||
|
||||
**When NOT to use.**
|
||||
|
||||
- On focusable elements. A focusable element with `aria-hidden="true"` produces a confusing experience: keyboard users can focus it, but screen readers will not announce it.
|
||||
- On meaningful content. If the content is meaningful enough to render visually, it is meaningful enough to announce.
|
||||
- On entire interactive widgets. The keyboard user can still tab into them; the screen reader cannot announce them.
|
||||
|
||||
**Audit check.** For every `aria-hidden="true"`, verify the element is not focusable and contains no focusable descendants. The combination is the most common ARIA bug.
|
||||
|
||||
### Visually-hidden CSS class
|
||||
|
||||
A CSS pattern that hides content visually but keeps it in the accessibility tree.
|
||||
|
||||
**Common implementation.**
|
||||
|
||||
```css
|
||||
.visually-hidden {
|
||||
position: absolute;
|
||||
width: 1px;
|
||||
height: 1px;
|
||||
padding: 0;
|
||||
margin: -1px;
|
||||
overflow: hidden;
|
||||
clip: rect(0, 0, 0, 0);
|
||||
white-space: nowrap;
|
||||
border: 0;
|
||||
}
|
||||
```
|
||||
|
||||
**When to use.**
|
||||
|
||||
- Skip links that should be invisible until focused.
|
||||
- Form labels that the design hides but accessibility requires.
|
||||
- Additional context for screen reader users (e.g., "Item 3 of 10 in shopping cart").
|
||||
|
||||
**Anti-pattern.** Using `display: none` or `visibility: hidden` for content that should remain in the accessibility tree. Both remove from the tree; visually-hidden does not.
|
||||
|
||||
---
|
||||
|
||||
## Description and labeling patterns
|
||||
|
||||
How to give elements accessible names and descriptions.
|
||||
|
||||
### aria-label
|
||||
|
||||
Provides an accessible name when no visible label exists.
|
||||
|
||||
**When to use.**
|
||||
|
||||
- Icon-only buttons (`<button aria-label="Close">`).
|
||||
- Generic links that need context (`<a aria-label="Read more about pricing" href="...">Read more</a>`).
|
||||
- Form inputs without visible labels (rare; usually a visible label is better).
|
||||
|
||||
**When not to use.**
|
||||
|
||||
- When a visible `<label>` exists. The visible label is the accessible name.
|
||||
- For decorative content. Use `aria-hidden` instead.
|
||||
|
||||
### aria-labelledby
|
||||
|
||||
Points to one or more existing elements whose text becomes the accessible name.
|
||||
|
||||
**When to use.**
|
||||
|
||||
- When the visible label is in another element (e.g., a `<legend>` for a fieldset).
|
||||
- When the accessible name comes from multiple elements (e.g., "Add to cart" combined with the product name).
|
||||
- For dialogs labeled by their heading.
|
||||
|
||||
**Syntax.** `aria-labelledby="id1 id2"` (space-separated IDs; the names concatenate).
|
||||
|
||||
### aria-describedby
|
||||
|
||||
Points to one or more existing elements whose text becomes the accessible description (announced after the name and role).
|
||||
|
||||
**When to use.**
|
||||
|
||||
- Form fields with help text that should announce after the label.
|
||||
- Buttons with secondary explanation.
|
||||
- Errors associated with form inputs (`aria-describedby="error-id"`).
|
||||
|
||||
**Syntax.** Same as `aria-labelledby`.
|
||||
|
||||
**The labeling priority.** Browsers compute the accessible name in this priority order: `aria-labelledby` > `aria-label` > `<label>` > placeholder/title (last-resort and unreliable). The accessible description follows: `aria-describedby` > `title`.
|
||||
|
||||
---
|
||||
|
||||
## State indicator patterns
|
||||
|
||||
ARIA attributes for component state.
|
||||
|
||||
### aria-busy
|
||||
|
||||
`aria-busy="true"` tells assistive tech that the element is in a transitional state (e.g., loading).
|
||||
|
||||
**When to use.**
|
||||
|
||||
- Sections being updated dynamically.
|
||||
- Long-running operations where partial content would be confusing.
|
||||
|
||||
**Audit check.** `aria-busy` is removed when the operation completes.
|
||||
|
||||
### aria-disabled
|
||||
|
||||
`aria-disabled="true"` indicates an element is disabled.
|
||||
|
||||
**When to use vs `disabled` attribute.**
|
||||
|
||||
- Native HTML `disabled` removes the element from the tab order and prevents interaction.
|
||||
- `aria-disabled="true"` keeps the element focusable but indicates disabled state. Useful when you want users to focus and read why the element is disabled, but cannot activate it.
|
||||
|
||||
**Audit check.** When using `aria-disabled`, the element should still appear disabled visually and click handlers should be suppressed.
|
||||
|
||||
### aria-invalid
|
||||
|
||||
`aria-invalid="true"` indicates a form input has a validation error.
|
||||
|
||||
**When to use.**
|
||||
|
||||
- After validation finds an error.
|
||||
- Combined with `aria-describedby` pointing to the error message.
|
||||
|
||||
**Audit check.** `aria-invalid` is set/cleared as validation state changes; not a stale attribute.
|
||||
|
||||
---
|
||||
|
||||
## Common ARIA anti-patterns
|
||||
|
||||
Patterns to flag in the audit.
|
||||
|
||||
### Overusing roles on semantic elements
|
||||
|
||||
**Pattern.** `<button role="button">`, `<nav role="navigation">`, `<a role="link">`.
|
||||
|
||||
**Why it fails.** Redundant; clutters markup; sometimes overrides correct semantics.
|
||||
|
||||
**Cure.** Remove the redundant role.
|
||||
|
||||
### ARIA without supporting behavior
|
||||
|
||||
**Pattern.** `aria-expanded="false"` on a button that has no JavaScript to toggle it.
|
||||
|
||||
**Why it fails.** The attribute lies; assistive tech reports state that does not match reality.
|
||||
|
||||
**Cure.** Either implement the behavior or remove the attribute.
|
||||
|
||||
### Focusable element with aria-hidden
|
||||
|
||||
**Pattern.** A `<button>` or `<a>` with `aria-hidden="true"`.
|
||||
|
||||
**Why it fails.** Keyboard users can focus it; screen readers ignore it. The user encounters a focused element with no announcement.
|
||||
|
||||
**Cure.** Either remove `aria-hidden` (if the element is meaningful) or remove from tab order with `tabindex="-1"` and disable interaction.
|
||||
|
||||
### Modal without focus management
|
||||
|
||||
**Pattern.** `role="dialog"` opens; focus stays on the triggering element behind the modal.
|
||||
|
||||
**Why it fails.** Screen reader users do not realize a modal opened. Keyboard users can tab into background content.
|
||||
|
||||
**Cure.** Move focus into the modal on open. Trap focus while open. Return focus to trigger on close.
|
||||
|
||||
### Live region without dynamic updates
|
||||
|
||||
**Pattern.** Static `<div role="status">Loading complete</div>` rendered in initial HTML.
|
||||
|
||||
**Why it fails.** Live regions only announce when their content changes after page load. Static content in a live region announces nothing.
|
||||
|
||||
**Cure.** Either remove the role (if the content is static) or update the content dynamically.
|
||||
|
||||
### Assertive live region for routine updates
|
||||
|
||||
**Pattern.** `role="alert"` on every form-save confirmation.
|
||||
|
||||
**Why it fails.** Each confirmation interrupts whatever the user was doing. Trust degrades quickly.
|
||||
|
||||
**Cure.** Use `role="status"` (polite) for non-urgent updates; reserve `role="alert"` for urgent messages.
|
||||
|
||||
### Form input without accessible name
|
||||
|
||||
**Pattern.** `<input type="text">` with placeholder but no label.
|
||||
|
||||
**Why it fails.** Screen reader announces "edit" or similar generic; user does not know what the input is for. Placeholder disappears when typing, removing context.
|
||||
|
||||
**Cure.** Add a visible `<label>` (preferred) or `aria-label`. Placeholder is not a label.
|
||||
|
||||
### Error message not associated with input
|
||||
|
||||
**Pattern.** Error text appears near a form input but no programmatic association.
|
||||
|
||||
**Why it fails.** Screen reader users do not hear the error when focused on the input.
|
||||
|
||||
**Cure.** Use `aria-describedby="error-id"` on the input, with the error message in an element with that ID. Optionally add `aria-invalid="true"`.
|
||||
|
||||
### Tab order broken by tabindex
|
||||
|
||||
**Pattern.** Positive `tabindex` values (`tabindex="1"`, `tabindex="2"`) used to control order.
|
||||
|
||||
**Why it fails.** Positive tabindex creates a separate tab order that often conflicts with DOM order; very brittle; almost always wrong.
|
||||
|
||||
**Cure.** Use `tabindex="0"` to add to natural order, `tabindex="-1"` to remove from natural order. Avoid positive values.
|
||||
|
||||
---
|
||||
|
||||
## ARIA in audit reports
|
||||
|
||||
What to flag in audit findings.
|
||||
|
||||
**Per finding, document:**
|
||||
|
||||
- The element (URL plus selector or screenshot).
|
||||
- The current ARIA (or its absence).
|
||||
- The behavior observed.
|
||||
- The behavior expected.
|
||||
- The fix.
|
||||
|
||||
**Severity calibration.**
|
||||
|
||||
- Modal without focus management: P0 (blocks assistive-tech users).
|
||||
- Form input without accessible name: P0.
|
||||
- Live region using assertive for routine updates: P1.
|
||||
- Redundant `role="button"` on a `<button>`: P3 (cosmetic, but trims technical debt).
|
||||
|
||||
The severity tracks user impact, not specification adherence per se. A redundant role does not block users; a missing label does.
|
||||
|
||||
---
|
||||
|
||||
## ARIA testing approach
|
||||
|
||||
How auditors verify ARIA.
|
||||
|
||||
**Tooling.**
|
||||
|
||||
- Browser DevTools accessibility tree (Chrome, Firefox, Safari) shows what assistive tech sees.
|
||||
- axe DevTools flags many ARIA misuses.
|
||||
- Screen reader testing is the ultimate verification.
|
||||
|
||||
**Common verification steps.**
|
||||
|
||||
- Inspect the accessibility tree for each interactive component.
|
||||
- Verify dynamic ARIA attributes change when state changes.
|
||||
- Verify focus management on open/close patterns (modals, menus, popovers).
|
||||
- Test with at least one screen reader to hear what users hear.
|
||||
|
||||
The accessibility tree (DevTools) often reveals issues invisible to automated scanners. Make it part of the audit.
|
||||
|
||||
---
|
||||
|
||||
## ARIA references
|
||||
|
||||
Beyond this file.
|
||||
|
||||
- W3C ARIA Authoring Practices Guide (APG): https://www.w3.org/WAI/ARIA/apg/. Patterns and examples.
|
||||
- WAI-ARIA 1.2 specification: https://www.w3.org/TR/wai-aria-1.2/. Canonical reference.
|
||||
- The W3C ARIA Roles, States, and Properties listing: https://www.w3.org/TR/wai-aria-1.2/#role_definitions. Searchable.
|
||||
|
||||
The APG is the most practical resource. Most patterns in this file are simplified summaries of APG patterns; for production implementation, consult the APG examples.
|
||||
|
||||
---
|
||||
|
||||
## Methodology-level choices that stay in the public skill
|
||||
|
||||
The semantic-HTML-first principle. Required ARIA and behavior for common interactive patterns (accordion, tabs, modal, toggle button, disclosure, navigation). Live region patterns (aria-live, aria-atomic, role="status", role="alert"). Hiding patterns (aria-hidden, visually-hidden CSS). Description and labeling patterns (aria-label, aria-labelledby, aria-describedby). State indicators (aria-busy, aria-disabled, aria-invalid). Common anti-patterns. ARIA in audit reports. ARIA testing approach. References.
|
||||
|
||||
## Implementation choices that stay internal
|
||||
|
||||
Specific component implementations in the team's framework. Specific JavaScript and class-name conventions for live regions, focus management, and ARIA toggling. Specific design-system patterns for dialogs, tabs, and accordions. The team's ARIA testing protocols and tooling configurations. These vary by team and stack.
|
||||
+228
@@ -0,0 +1,228 @@
|
||||
# Accessibility Audit Report Template
|
||||
|
||||
A fillable accessibility audit template. Customize the level (AA, AAA, EN 301 549) and scope (page, component, site) per project.
|
||||
|
||||
---
|
||||
|
||||
## Audit metadata
|
||||
|
||||
**Audited:** [URL or component name]
|
||||
**Date:** [YYYY-MM-DD]
|
||||
**Auditor:** [Name]
|
||||
**Compliance target:** [WCAG 2.1 AA / WCAG 2.1 AAA / EN 301 549]
|
||||
**Scope:** [What was and was not tested]
|
||||
**Methodology:** [Tools used, manual tests performed]
|
||||
|
||||
---
|
||||
|
||||
## Executive summary
|
||||
|
||||
[2 to 3 paragraph overview. The state of accessibility, the most important issues, the recommended path forward.]
|
||||
|
||||
**Issue counts:**
|
||||
|
||||
| Severity | Count |
|
||||
|---|---|
|
||||
| Critical | |
|
||||
| Major | |
|
||||
| Minor | |
|
||||
| **Total** | |
|
||||
|
||||
**Top 3 priorities:**
|
||||
|
||||
1. [Priority]
|
||||
2. [Priority]
|
||||
3. [Priority]
|
||||
|
||||
---
|
||||
|
||||
## Tools and methods used
|
||||
|
||||
**Automated:**
|
||||
- [ ] axe DevTools
|
||||
- [ ] Lighthouse accessibility audit
|
||||
- [ ] WAVE
|
||||
- [ ] Pa11y (or other CI tool)
|
||||
|
||||
**Manual:**
|
||||
- [ ] Keyboard-only navigation
|
||||
- [ ] Screen reader: [NVDA / JAWS / VoiceOver / TalkBack]
|
||||
- [ ] 200% zoom
|
||||
- [ ] Mobile reflow at 320px width
|
||||
- [ ] Color blindness simulation
|
||||
- [ ] Windows High Contrast (or browser equivalent)
|
||||
- [ ] Reduced motion preference
|
||||
|
||||
---
|
||||
|
||||
## Critical findings
|
||||
|
||||
Findings that block usage for some users. Must be fixed before sign-off.
|
||||
|
||||
### Critical 1: [Issue name]
|
||||
|
||||
- **WCAG criterion:** [e.g., 2.1.1 Keyboard]
|
||||
- **Severity:** Critical
|
||||
- **Affected users:** [Keyboard / screen reader / low vision / etc.]
|
||||
- **Reproduction steps:**
|
||||
1. [Step]
|
||||
2. [Step]
|
||||
3. [Step]
|
||||
- **Expected:** [What should happen]
|
||||
- **Actual:** [What does happen]
|
||||
- **Recommended fix:** [Specific solution]
|
||||
- **Estimated effort:** [Hours / days]
|
||||
- **Owner:** [Team or person]
|
||||
|
||||
### Critical 2: [Issue name]
|
||||
|
||||
[Same structure]
|
||||
|
||||
---
|
||||
|
||||
## Major findings
|
||||
|
||||
Findings that significantly degrade experience. Should be fixed before broad launch.
|
||||
|
||||
### Major 1: [Issue name]
|
||||
|
||||
[Same structure as critical]
|
||||
|
||||
### Major 2: [Issue name]
|
||||
|
||||
[Same structure]
|
||||
|
||||
---
|
||||
|
||||
## Minor findings
|
||||
|
||||
Findings that add friction without blocking. Tracked and addressed in normal iteration.
|
||||
|
||||
### Minor 1: [Issue name]
|
||||
|
||||
[Brief structure]
|
||||
|
||||
- **WCAG criterion:**
|
||||
- **Issue:**
|
||||
- **Recommended fix:**
|
||||
|
||||
---
|
||||
|
||||
## WCAG 2.1 AA scorecard
|
||||
|
||||
For full audits, score each criterion. For partial audits, score only those in scope.
|
||||
|
||||
### 1. Perceivable
|
||||
|
||||
| Criterion | Pass / Fail / N/A | Notes |
|
||||
|---|---|---|
|
||||
| 1.1.1 Non-text content | | |
|
||||
| 1.2.1 Audio-only and video-only | | |
|
||||
| 1.2.2 Captions (prerecorded) | | |
|
||||
| 1.2.3 Audio description or media alternative | | |
|
||||
| 1.2.4 Captions (live) | | |
|
||||
| 1.2.5 Audio description (prerecorded) | | |
|
||||
| 1.3.1 Info and relationships | | |
|
||||
| 1.3.2 Meaningful sequence | | |
|
||||
| 1.3.3 Sensory characteristics | | |
|
||||
| 1.3.4 Orientation | | |
|
||||
| 1.3.5 Identify input purpose | | |
|
||||
| 1.4.1 Use of color | | |
|
||||
| 1.4.2 Audio control | | |
|
||||
| 1.4.3 Contrast (minimum) | | |
|
||||
| 1.4.4 Resize text | | |
|
||||
| 1.4.5 Images of text | | |
|
||||
| 1.4.10 Reflow | | |
|
||||
| 1.4.11 Non-text contrast | | |
|
||||
| 1.4.12 Text spacing | | |
|
||||
| 1.4.13 Content on hover or focus | | |
|
||||
|
||||
### 2. Operable
|
||||
|
||||
| Criterion | Pass / Fail / N/A | Notes |
|
||||
|---|---|---|
|
||||
| 2.1.1 Keyboard | | |
|
||||
| 2.1.2 No keyboard trap | | |
|
||||
| 2.1.4 Character key shortcuts | | |
|
||||
| 2.2.1 Timing adjustable | | |
|
||||
| 2.2.2 Pause, stop, hide | | |
|
||||
| 2.3.1 Three flashes or below threshold | | |
|
||||
| 2.4.1 Bypass blocks | | |
|
||||
| 2.4.2 Page titled | | |
|
||||
| 2.4.3 Focus order | | |
|
||||
| 2.4.4 Link purpose (in context) | | |
|
||||
| 2.4.5 Multiple ways | | |
|
||||
| 2.4.6 Headings and labels | | |
|
||||
| 2.4.7 Focus visible | | |
|
||||
| 2.5.1 Pointer gestures | | |
|
||||
| 2.5.2 Pointer cancellation | | |
|
||||
| 2.5.3 Label in name | | |
|
||||
| 2.5.4 Motion actuation | | |
|
||||
|
||||
### 3. Understandable
|
||||
|
||||
| Criterion | Pass / Fail / N/A | Notes |
|
||||
|---|---|---|
|
||||
| 3.1.1 Language of page | | |
|
||||
| 3.1.2 Language of parts | | |
|
||||
| 3.2.1 On focus | | |
|
||||
| 3.2.2 On input | | |
|
||||
| 3.2.3 Consistent navigation | | |
|
||||
| 3.2.4 Consistent identification | | |
|
||||
| 3.3.1 Error identification | | |
|
||||
| 3.3.2 Labels or instructions | | |
|
||||
| 3.3.3 Error suggestion | | |
|
||||
| 3.3.4 Error prevention (legal, financial, data) | | |
|
||||
|
||||
### 4. Robust
|
||||
|
||||
| Criterion | Pass / Fail / N/A | Notes |
|
||||
|---|---|---|
|
||||
| 4.1.1 Parsing | | |
|
||||
| 4.1.2 Name, role, value | | |
|
||||
| 4.1.3 Status messages | | |
|
||||
|
||||
---
|
||||
|
||||
## Remediation roadmap
|
||||
|
||||
Sequenced by severity and dependency.
|
||||
|
||||
### Phase 1: Critical fixes (target: [date])
|
||||
|
||||
- [ ] [Critical 1]
|
||||
- [ ] [Critical 2]
|
||||
|
||||
### Phase 2: Major fixes (target: [date])
|
||||
|
||||
- [ ] [Major 1]
|
||||
- [ ] [Major 2]
|
||||
|
||||
### Phase 3: Minor fixes (target: [date])
|
||||
|
||||
- [ ] [Minor 1]
|
||||
- [ ] [Minor 2]
|
||||
|
||||
### Phase 4: Process improvements
|
||||
|
||||
- [ ] Add automated a11y checks to CI
|
||||
- [ ] Establish a11y review in PR process
|
||||
- [ ] Train design and engineering teams on common failures
|
||||
- [ ] Set up regular re-audit schedule
|
||||
|
||||
---
|
||||
|
||||
## Re-audit schedule
|
||||
|
||||
- **Verify critical fixes:** [Date, typically 1 to 2 weeks post-remediation]
|
||||
- **Verify major fixes:** [Date, typically 4 weeks]
|
||||
- **Full re-audit:** [Date, typically 6 to 12 months]
|
||||
- **Trigger-based re-audit:** Significant design system updates, major feature launches
|
||||
|
||||
---
|
||||
|
||||
## Sign-off
|
||||
|
||||
Critical fixes verified by: [Name and date]
|
||||
Major fixes verified by: [Name and date]
|
||||
Final approval: [Name and date]
|
||||
+250
@@ -0,0 +1,250 @@
|
||||
# WCAG 2.1 AA Quick Reference
|
||||
|
||||
A condensed list of WCAG 2.1 AA success criteria with the practical audit check for each.
|
||||
|
||||
For the canonical specification, refer to W3C: https://www.w3.org/TR/WCAG21/
|
||||
|
||||
---
|
||||
|
||||
## Principle 1: Perceivable
|
||||
|
||||
### 1.1 Text alternatives
|
||||
|
||||
**1.1.1 Non-text content (A)**
|
||||
- All meaningful images have descriptive `alt` text
|
||||
- Decorative images have `alt=""` (empty alt)
|
||||
- Complex images have long descriptions
|
||||
- Form inputs have associated labels
|
||||
- CAPTCHA has alternatives for users who cannot perceive it
|
||||
- Audit check: scan for `<img>` without `alt`, run alt-text quality review
|
||||
|
||||
### 1.2 Time-based media
|
||||
|
||||
**1.2.1 Audio-only and video-only prerecorded (A)**
|
||||
- Audio-only content has a transcript
|
||||
- Video-only content (no audio) has a description or transcript
|
||||
|
||||
**1.2.2 Captions prerecorded (A)**
|
||||
- Pre-recorded video content has captions
|
||||
|
||||
**1.2.3 Audio description or media alternative (A)**
|
||||
- Pre-recorded video has audio description OR an alternative
|
||||
|
||||
**1.2.4 Captions live (AA)**
|
||||
- Live video content has captions
|
||||
|
||||
**1.2.5 Audio description prerecorded (AA)**
|
||||
- Pre-recorded video has audio description
|
||||
|
||||
### 1.3 Adaptable
|
||||
|
||||
**1.3.1 Info and relationships (A)**
|
||||
- Structure conveyed through markup, not just visual styling
|
||||
- Headings use `<h1>` through `<h6>`, not styled `<div>`
|
||||
- Lists use `<ul>`, `<ol>`, `<li>`
|
||||
- Tables use `<table>`, `<th>`, `<td>` correctly with `scope` attributes
|
||||
- Form inputs have `<label>` associated via `for`/`id` or `aria-labelledby`
|
||||
|
||||
**1.3.2 Meaningful sequence (A)**
|
||||
- Reading order makes sense without CSS
|
||||
- Audit check: disable CSS, read the page top to bottom
|
||||
|
||||
**1.3.3 Sensory characteristics (A)**
|
||||
- Instructions don't rely solely on shape, size, color, or position
|
||||
- Audit check: avoid "click the green button" or "the button on the right"
|
||||
|
||||
**1.3.4 Orientation (AA)**
|
||||
- Content does not restrict view to a single orientation (portrait or landscape)
|
||||
|
||||
**1.3.5 Identify input purpose (AA)**
|
||||
- Form fields collecting user information use `autocomplete` attributes correctly
|
||||
|
||||
### 1.4 Distinguishable
|
||||
|
||||
**1.4.1 Use of color (A)**
|
||||
- Color is not the only way information is conveyed
|
||||
- Audit check: check error states, status indicators, chart elements
|
||||
|
||||
**1.4.2 Audio control (A)**
|
||||
- Audio that plays automatically for more than 3 seconds has pause/stop control
|
||||
|
||||
**1.4.3 Contrast minimum (AA)**
|
||||
- Normal text contrast ratio at least 4.5:1
|
||||
- Large text (18pt regular or 14pt bold) at least 3:1
|
||||
- Audit check: contrast checker on every text/background pair
|
||||
|
||||
**1.4.4 Resize text (AA)**
|
||||
- Text can be resized to 200% without loss of content or functionality
|
||||
- Audit check: zoom to 200% in the browser, verify usability
|
||||
|
||||
**1.4.5 Images of text (AA)**
|
||||
- Use real text, not images of text, except for logos or where customization is essential
|
||||
|
||||
**1.4.10 Reflow (AA)**
|
||||
- Content can be presented without horizontal scrolling at 320px viewport
|
||||
- Audit check: resize to 320px, verify no horizontal scroll
|
||||
|
||||
**1.4.11 Non-text contrast (AA)**
|
||||
- UI components and graphical objects at least 3:1 contrast ratio against adjacent colors
|
||||
- Audit check: borders, icons, form field outlines, focus rings
|
||||
|
||||
**1.4.12 Text spacing (AA)**
|
||||
- No loss of content or functionality when text spacing is increased to specific minimums
|
||||
- Audit check: apply line-height: 1.5, letter-spacing: 0.12em, word-spacing: 0.16em, paragraph-spacing: 2x font size
|
||||
|
||||
**1.4.13 Content on hover or focus (AA)**
|
||||
- Hover/focus tooltips can be dismissed, hovered, and persist until dismissed
|
||||
|
||||
---
|
||||
|
||||
## Principle 2: Operable
|
||||
|
||||
### 2.1 Keyboard accessible
|
||||
|
||||
**2.1.1 Keyboard (A)**
|
||||
- All functionality available from keyboard
|
||||
- Audit check: navigate the entire site without a mouse
|
||||
|
||||
**2.1.2 No keyboard trap (A)**
|
||||
- Focus can always be moved away from any component using keyboard alone
|
||||
- Audit check: open every modal, dropdown, widget; verify Tab can leave
|
||||
|
||||
**2.1.4 Character key shortcuts (A)**
|
||||
- If single-character keyboard shortcuts exist, they can be turned off, remapped, or only active on focus
|
||||
|
||||
### 2.2 Enough time
|
||||
|
||||
**2.2.1 Timing adjustable (A)**
|
||||
- Time limits can be turned off, adjusted, or extended (with exceptions for real-time and essential)
|
||||
|
||||
**2.2.2 Pause, stop, hide (A)**
|
||||
- Auto-updating content can be paused or stopped (with exceptions for essential)
|
||||
|
||||
### 2.3 Seizures and physical reactions
|
||||
|
||||
**2.3.1 Three flashes or below threshold (A)**
|
||||
- Nothing flashes more than 3 times per second
|
||||
|
||||
### 2.4 Navigable
|
||||
|
||||
**2.4.1 Bypass blocks (A)**
|
||||
- Skip link present at the top of the page
|
||||
- Or, use proper landmarks (`<header>`, `<nav>`, `<main>`, `<footer>`)
|
||||
|
||||
**2.4.2 Page titled (A)**
|
||||
- Each page has a unique, descriptive `<title>`
|
||||
|
||||
**2.4.3 Focus order (A)**
|
||||
- Focus order matches visual and logical reading order
|
||||
|
||||
**2.4.4 Link purpose in context (A)**
|
||||
- Link purpose is clear from the link text alone, or from text + immediate surrounding context
|
||||
- Avoid "click here," "read more," "learn more" without context
|
||||
|
||||
**2.4.5 Multiple ways (AA)**
|
||||
- Multiple ways to find content (sitemap, search, navigation menu)
|
||||
|
||||
**2.4.6 Headings and labels (AA)**
|
||||
- Headings and labels are descriptive
|
||||
|
||||
**2.4.7 Focus visible (AA)**
|
||||
- Keyboard focus indicator is visible
|
||||
- Audit check: Tab through the page; can you always see where focus is?
|
||||
|
||||
### 2.5 Input modalities
|
||||
|
||||
**2.5.1 Pointer gestures (A)**
|
||||
- Multipoint or path-based gestures have single-point alternative
|
||||
|
||||
**2.5.2 Pointer cancellation (A)**
|
||||
- Down-event does not trigger action; action triggers on up-event or has way to abort
|
||||
|
||||
**2.5.3 Label in name (A)**
|
||||
- Accessible name (for screen readers) contains the visible label text
|
||||
|
||||
**2.5.4 Motion actuation (A)**
|
||||
- Motion-triggered functionality has UI alternative and can be disabled
|
||||
|
||||
---
|
||||
|
||||
## Principle 3: Understandable
|
||||
|
||||
### 3.1 Readable
|
||||
|
||||
**3.1.1 Language of page (A)**
|
||||
- Page language declared in HTML: `<html lang="en">`
|
||||
|
||||
**3.1.2 Language of parts (AA)**
|
||||
- Inline foreign-language passages marked: `<span lang="fr">...</span>`
|
||||
|
||||
### 3.2 Predictable
|
||||
|
||||
**3.2.1 On focus (A)**
|
||||
- Receiving focus does not change context (no auto-submit, no unexpected navigation)
|
||||
|
||||
**3.2.2 On input (A)**
|
||||
- Changing a setting does not automatically change context unless user is warned
|
||||
|
||||
**3.2.3 Consistent navigation (AA)**
|
||||
- Navigation appears in the same relative order across pages
|
||||
|
||||
**3.2.4 Consistent identification (AA)**
|
||||
- Components with the same function are identified consistently
|
||||
|
||||
### 3.3 Input assistance
|
||||
|
||||
**3.3.1 Error identification (A)**
|
||||
- Errors are identified and described in text (not just color or icon)
|
||||
|
||||
**3.3.2 Labels or instructions (A)**
|
||||
- Labels or instructions provided for inputs requiring user input
|
||||
|
||||
**3.3.3 Error suggestion (AA)**
|
||||
- When errors occur and suggestions are known, suggestions are provided
|
||||
|
||||
**3.3.4 Error prevention (legal, financial, data) (AA)**
|
||||
- For pages causing legal commitments or financial transactions: submissions are reversible, checked for errors, OR confirmed before final submission
|
||||
|
||||
---
|
||||
|
||||
## Principle 4: Robust
|
||||
|
||||
### 4.1 Compatible
|
||||
|
||||
**4.1.1 Parsing (A) [removed in 2.2 but still in 2.1]**
|
||||
- Markup is well-formed (no duplicate IDs, properly nested elements)
|
||||
|
||||
**4.1.2 Name, role, value (A)**
|
||||
- For all UI components, name and role can be programmatically determined; states, properties, and values can be set
|
||||
- Use semantic HTML, ARIA where needed
|
||||
|
||||
**4.1.3 Status messages (AA)**
|
||||
- Status messages can be programmatically determined through role or properties so they can be announced by assistive technology
|
||||
- Use `role="status"`, `role="alert"`, or `aria-live`
|
||||
|
||||
---
|
||||
|
||||
## Audit check summary
|
||||
|
||||
For each criterion, the audit needs to:
|
||||
|
||||
1. **Identify the requirement** (what does WCAG ask for?)
|
||||
2. **Test against the site** (does the site meet it?)
|
||||
3. **Document failures** (which pages, which elements, what's wrong)
|
||||
4. **Specify the fix** (what specific change resolves it)
|
||||
5. **Assign severity** (P0 critical, P1 important, P2 minor, P3 polish)
|
||||
6. **Estimate effort** (small, medium, large)
|
||||
|
||||
A complete audit covers all 30+ AA criteria. Most sites fail 5 to 15 of them on first audit. Don't try to fix all at once. Sequence by severity and impact.
|
||||
|
||||
---
|
||||
|
||||
## What WCAG does NOT cover
|
||||
|
||||
WCAG is a floor, not a ceiling. Some accessibility considerations are outside its scope:
|
||||
|
||||
- **Cognitive accessibility nuances** (reading level, attention, memory) - some basics in 3.1, but limited
|
||||
- **Audience-specific needs** (the cognitive support a user with dyslexia needs vs. a user with autism)
|
||||
- **Mental models** (whether the navigation makes sense to your specific audience)
|
||||
|
||||
For these, supplement WCAG with usability testing including users with disabilities, and with specific design patterns aimed at cognitive accessibility.
|
||||
@@ -0,0 +1,231 @@
|
||||
---
|
||||
name: ads-creative-development
|
||||
description: "How to produce ad creative that converts at performance scale. Hook patterns, format selection, video pacing, variation systems, sequential testing methodology, fatigue detection, brand-voice alignment without conversion dilution, and platform-specific creative norms. Triggers on ad creative, ad design, hook patterns, ad video pacing, creative testing, ad variations, creative refresh, creative fatigue, refresh ad creative, video ads for Meta, TikTok creative, LinkedIn ad creative, ad asset library. Also triggers when a team is producing creative at scale, planning a creative test cycle, or auditing why creative is not converting."
|
||||
category: marketing
|
||||
catalog_summary: "Hook patterns, format selection, video pacing, variation systems, testing methodology, fatigue detection, and the platform-specific creative norms that separate ads from clutter"
|
||||
display_order: 2
|
||||
---
|
||||
|
||||
# Ads Creative Development
|
||||
|
||||
A senior creative strategist's playbook for producing ad creative that performs.
|
||||
|
||||
Performance creative is a different discipline from brand creative. Brand work optimizes for memorability, emotional resonance, and distinctive identity. Performance creative optimizes for stopping the scroll, communicating value in three seconds, and producing a click. Both matter. Mixing them up costs money. Brand creative running as performance ads bleeds budget; performance creative running as brand ads erodes equity.
|
||||
|
||||
This skill is the discipline that produces performance creative without diluting brand. It assumes you know your audience and offer (see `paid-media-strategy`). It assumes you have brand-voice guidance (see `brand-voice`). The hard part is the systematic production of variations that test cleanly and ship without manual approval bottlenecks, and that is what is here.
|
||||
|
||||
When to use this skill: producing ad creative for paid campaigns, planning a creative testing cycle, diagnosing creative fatigue, or auditing why creative is not converting.
|
||||
|
||||
---
|
||||
|
||||
## What this skill is for
|
||||
|
||||
This skill spans creative production, hook patterns, testing methodology, and fatigue diagnosis. It does not cover paid media strategy (use `paid-media-strategy`), result interpretation (use `ads-performance-analytics` once it ships), or brand voice authoring (use `brand-voice`). Pair this skill with the relevant integrations microsite for platform-specific MCP details and example prompts.
|
||||
|
||||
The audience is an ad creative producer, a growth marketer responsible for creative testing, or an agency producing creative at scale. The voice is tactical. There is no "consider every option." Performance creative has shape, and a senior practitioner can map a brief to a production-ready variation matrix in an afternoon.
|
||||
|
||||
---
|
||||
|
||||
## Performance vs brand creative
|
||||
|
||||
The two disciplines optimize for different metrics. Brand creative optimizes for memorability, distinctiveness, and emotional resonance over months. Performance creative optimizes for scroll-stop in 1 second, value comprehension by 5 seconds, and click by 15.
|
||||
|
||||
The shared layer. Both should reflect brand voice. Both should look like they came from the same brand. The difference is structure, pacing, and where the creative effort concentrates.
|
||||
|
||||
The failure mode. Most agency creative tries to do both and does neither well. The brand video that runs as a 60-second performance ad has a strong narrative arc and zero CTR. The performance ad that ignores brand voice converts but trains the audience to not recognize the brand. The fix is not to compromise; it is to produce both, in their respective formats, with shared voice and divergent structure.
|
||||
|
||||
A worked example. A premium coffee brand running a 60-second YouTube awareness ad gets to build the world: cinematography, the founder's hands, slow-pour rituals, music that sets a mood. That same brand running a 15-second Meta Reels performance ad gets 1 second to stop the scroll (a visual pattern interrupt: the steam rising from a cup, fast cut, brand logo dropping in), 4 seconds to clarify the offer (the new flavor, the price, the deal), 8 seconds for social proof (three customer-style testimonials, fast cuts), and 2 seconds for CTA (shop now, end card with logo). Same voice. Different structure. Different pacing. Different creative effort distribution.
|
||||
|
||||
---
|
||||
|
||||
## Hook patterns: the first 3 seconds
|
||||
|
||||
The biggest lever in performance creative. If the hook fails, no amount of body copy or CTA can recover the impression. A user who scrolled past the first second has already decided. The hook is the whole game until the body justifies why the user kept watching.
|
||||
|
||||
Twelve hook patterns work consistently. Detail in [`references/hook-pattern-library.md`](references/hook-pattern-library.md).
|
||||
|
||||
1. **Problem-agitate-solve.** Open with the problem the audience feels. Agitate by naming the consequence. Solve with the offer. Works when the audience recognizes the pain.
|
||||
2. **Direct callout to audience.** "If you are a B2B founder running paid ads..." Triggers self-identification. Works when the audience is narrow and self-aware.
|
||||
3. **Contrarian claim.** "Stop using lookalike audiences." Hooks attention by violating expectation. Works when the audience has heard the conventional wisdom too often.
|
||||
4. **Result-led.** "How we cut CAC 40% in 30 days." Specific number, specific timeframe. Works when the result is real and documented.
|
||||
5. **Curiosity gap.** "The mistake 80% of marketers make..." Promises a payoff after the gap. Works when the gap is real; clickbait without payoff trains the audience to scroll past.
|
||||
6. **Social proof at top.** "Used by 10,000+ teams." Validation before pitch. Works when the proof is impressive enough to do the heavy lifting.
|
||||
7. **Visual pattern interrupt.** A surprising visual that does not match the platform's usual feed flow. Works on TikTok and Reels where the pattern is fast and the interrupt is louder.
|
||||
8. **Question that hits intent.** "Tired of paying $400 for project management software?" The question pre-qualifies the audience. Works when the question matches a real search query the audience has typed.
|
||||
9. **Number-led.** "3 changes that doubled our ROAS." Lists trigger the brain's pattern-completion instinct. Works for educational content; less so for product ads.
|
||||
10. **Personal story open.** "Last year I was burning $50K a month on Meta ads with no return..." First-person specificity is hard to skip. Works when the story is real and the conclusion is action-relevant.
|
||||
11. **Comparison.** "X vs Y: which actually works." Pits two options against each other. Works when the audience is in evaluation mode.
|
||||
12. **Behind-the-scenes / process.** "How we onboard a new client in 7 days..." Demystifies the work. Works when the process is the differentiator.
|
||||
|
||||
For each pattern, the anti-pattern is the same: a hook that does not actually hook. Generic openings ("In today's world...", brand-logo cards, slow zooms over title cards) train the audience to scroll past. The first second is for the hook. The brand can wait.
|
||||
|
||||
---
|
||||
|
||||
## Format selection
|
||||
|
||||
Different formats fit different combinations of audience, platform, and offer.
|
||||
|
||||
- **Static image.** Best for simple value props, retargeting, and quick test cycles. Lowest production cost. Limited room for narrative.
|
||||
- **Carousel.** Best for multi-feature products, educational content, and B2B SaaS. Each card carries one idea; users swipe through at their own pace. Strong for considered purchases.
|
||||
- **Video (in-feed).** Best for demonstration, story, and broad audiences. Higher production cost. Performance correlates strongly with hook quality.
|
||||
- **UGC-style video.** Best for trust building, social proof, and lower production cost. Looks like an ordinary user filmed it. Especially strong on TikTok and Reels.
|
||||
- **Stories or Reels (vertical 9:16).** Best for TikTok, Instagram, and Snap. Native to the platform's primary surface. Skipping anything not vertical here is leaving performance on the table.
|
||||
- **Spark Ads (boosted organic).** Best for TikTok. Promotes an existing organic post as an ad. Retains organic engagement signals; consistently outperforms pure paid creative on TikTok.
|
||||
|
||||
The decision rule. Match format to platform native style and to audience consumption pattern. Detail in [`references/format-decision-matrix.md`](references/format-decision-matrix.md).
|
||||
|
||||
---
|
||||
|
||||
## Video pacing
|
||||
|
||||
Video performance correlates more with pacing than with production value. A well-paced phone-shot video outperforms a poorly-paced agency-produced spot. Specific guidance for the 15-second performance video.
|
||||
|
||||
| Time window | Job |
|
||||
|---|---|
|
||||
| 0 to 1s | Hook. Visual pattern interrupt plus audio hook. |
|
||||
| 1 to 3s | Clarify what this is. Brand and offer registered. |
|
||||
| 3 to 7s | Value proposition. The problem-solution moment. |
|
||||
| 7 to 12s | Social proof or demonstration. Show, do not just tell. |
|
||||
| 12 to 15s | CTA. End card with logo and call to action. |
|
||||
|
||||
Anything past 15 seconds in a performance video is awareness territory. Performance creative should resolve by 15s.
|
||||
|
||||
Platform variations. TikTok performs at 15 to 30 seconds; the platform tolerates longer because the audience is in a longer dwell mode. Meta In-Feed performs at 15s. YouTube Shorts at 15 to 60s. Long-form YouTube at 30s+ for awareness, with the value prop still front-loaded.
|
||||
|
||||
---
|
||||
|
||||
## Variation systems
|
||||
|
||||
The systematic way to produce 20 to 50 ad variations from one core concept without manual creative authoring per variation.
|
||||
|
||||
The decomposition. A creative is a hook plus a body plus a CTA in a format. Treat each as a variable.
|
||||
|
||||
- 1 concept times 5 hooks times 4 bodies times 3 CTAs times 2 formats equals 120 theoretical variations.
|
||||
- Most are not worth shipping. The matrix narrows to 20 to 40 variations the team will actually run.
|
||||
- Asset library structure: organize by concept, not by date. `concepts/launch-2026/hooks/`, `concepts/launch-2026/bodies/`, etc.
|
||||
|
||||
Naming convention. Use a structured naming system so the analyst can join performance data back to creative components. Example: `launch2026_meta-reel_hookA_bodyB_ctaC_v1`. The analyst pulls the report, joins on the naming components, and identifies which hook is winning across body and CTA combinations.
|
||||
|
||||
Worked example in [`references/creative-variation-templates.md`](references/creative-variation-templates.md). A half-day production session produces 40 variations from one core concept by using the matrix. Without the matrix, the same 40 variations require five days of authoring overhead.
|
||||
|
||||
---
|
||||
|
||||
## Sequential testing methodology
|
||||
|
||||
The waterfall. Most teams test everything at once and lose the signal. Sequential testing isolates the variable that matters at each step.
|
||||
|
||||
1. **Test hooks first.** 5 to 10 hook variants, same body, same CTA, same format. The hook is the biggest lever; isolate it first.
|
||||
2. **Winners advance to body testing.** Top 2 to 3 hooks each get 5 to 10 body variants. Now you are testing what the audience watches after the hook lands.
|
||||
3. **Winners advance to CTA testing.** Top hook plus body combinations each get 3 to 5 CTAs. Smaller search space at this stage; the differences are usually marginal.
|
||||
4. **Winners advance to format testing.** Top combinations each render in 2 to 3 formats (vertical video, carousel, static). Catches format-specific drop-offs.
|
||||
5. **Top combos go into evergreen rotation.** Two to four winners run on rotation. Refresh on the cadence below.
|
||||
|
||||
The common mistake. Testing all variables at once. Variance compounds; the team cannot tell whether the hook, the body, the CTA, or the format made the difference. Sequential is slower but produces real learnings the team can apply to the next campaign.
|
||||
|
||||
Detail in [`references/testing-cadence-playbook.md`](references/testing-cadence-playbook.md).
|
||||
|
||||
---
|
||||
|
||||
## Creative fatigue detection
|
||||
|
||||
Fatigue is real. The same audience seeing the same creative six times a week tunes it out, or worse, develops negative associations. Five signals indicate fatigue.
|
||||
|
||||
1. **Frequency above 4 to 5 per user per week.** Set explicit caps. Defaults are usually too high.
|
||||
2. **CTR declining 30%+ week over week.** The creative is no longer fresh to the audience.
|
||||
3. **CPM increasing without audience saturation explanation.** The platform is having to bid harder to deliver impressions because engagement signals are weakening.
|
||||
4. **Negative comments increasing.** A direct user signal that the audience is irritated.
|
||||
5. **Hide ratio increasing.** Meta exposes this as "negative feedback rate." TikTok exposes "not interested" rate.
|
||||
|
||||
Refresh cadence. Weekly for high-spend campaigns ($50K+/month). Biweekly for medium spend. Monthly for low spend. The economics: producing a fresh variant is cheaper than running tired creative for one extra week.
|
||||
|
||||
The decision tree. If a top performer's metrics are still strong but frequency is climbing, ship variants of the same concept (same hook structure, different copy and visuals). If the metrics are dropping, retire the concept and ship a new one. Detail in [`references/fatigue-detection-checklist.md`](references/fatigue-detection-checklist.md).
|
||||
|
||||
---
|
||||
|
||||
## Brand-voice alignment without conversion dilution
|
||||
|
||||
The tension. Brand voice can feel off-brand when squeezed into 15-second ads. The fix is hierarchy, not compromise.
|
||||
|
||||
Voice attributes that survive compression. Tone (playful, serious, expert, irreverent). Cadence (short sentences vs long-form). Vocabulary (industry-specific or accessible). Visual treatment (color, type, motion language). These survive in 15s because they live in the texture of every frame.
|
||||
|
||||
Voice attributes that do not survive compression. Deep narrative arcs. Complex metaphors. Layered humor that requires setup. Long-form storytelling. These need 30s+ of runtime to land. Forcing them into 15s produces diluted versions that read as off-brand.
|
||||
|
||||
The hierarchy. Brand voice in every frame; performance discipline in the structure. The brand voice shows up in tone, cadence, vocabulary, and visual treatment. The performance discipline shows up in pacing, hook strength, and CTA placement.
|
||||
|
||||
A worked example. A brand whose voice is "warm and direct, slightly contrarian, plain-language" runs three creatives. The 60-second YouTube awareness piece has the founder talking to camera, plain language, contrarian framing of the category. The 15-second Meta performance ad has fast cuts, plain language captions on screen, contrarian hook ("Stop overpaying for project management software"), specific value prop, CTA. The static carousel has 6 cards, plain language, contrarian opening card, value prop progression, CTA on the last card. Same voice. Different structure. None feels off-brand to a customer who has seen all three.
|
||||
|
||||
Detail in [`references/brand-voice-performance-balance.md`](references/brand-voice-performance-balance.md).
|
||||
|
||||
---
|
||||
|
||||
## Platform-specific creative norms
|
||||
|
||||
Each platform has native norms. Violating them tanks performance. The fix is producing platform-native, not repurposing.
|
||||
|
||||
**Meta (Facebook plus Instagram).** In-feed visual hierarchy. Captions on by default (most users watch sound-off). Native-feeling production beats studio production for direct response. Vertical 9:16 for Reels and Stories; 1:1 or 4:5 for in-feed. CTAs above the fold or in first 2 lines of caption.
|
||||
|
||||
**TikTok.** Vertical 9:16 only. Native-creator aesthetic; phone-shot is the default. Fast cuts every 1 to 2 seconds. Captions for accessibility. Music-driven; trending sounds compound reach but expire fast. Spark Ads (boost an existing organic post) consistently outperform pure paid because they retain organic engagement signal.
|
||||
|
||||
**LinkedIn.** Professional tone. Slower pacing tolerated; B2B audiences are in research mode rather than scroll mode. B2B vocabulary is fine; consumer-style copy reads as off-platform. Thought leadership angle works; product pitches feel salesy.
|
||||
|
||||
**Google Search.** Text-only headlines plus descriptions. Character limits are real constraints (30-character headlines, 90-character descriptions). RSA (Responsive Search Ads) optimization rewards 15+ headline variations and 4+ descriptions; the platform mixes them.
|
||||
|
||||
**Google Display and YouTube.** Depends on placement. YouTube allows longer narrative (15s to 6m); Display is fast banner-style. Skippable YouTube ads need to earn the next second of attention; non-skippable annoys.
|
||||
|
||||
Detail in [`references/platform-creative-norms.md`](references/platform-creative-norms.md).
|
||||
|
||||
---
|
||||
|
||||
## Common failures
|
||||
|
||||
Eight patterns recur across creative production work. The short version.
|
||||
|
||||
- "We made a beautiful brand video and ran it as performance." Wrong format and length for the channel. Brand video belongs in awareness; performance ads need the 15-second structure.
|
||||
- "All our ads use the same hook." Saturation. Ship five to ten hook variants per concept and rotate.
|
||||
- "Our ads stopped working after 3 days." Fatigue plus narrow audience. Either ship more variants or expand the audience; usually both.
|
||||
- "We A/B tested 50 ad variations." Too many simultaneous variables. Run sequential tests instead.
|
||||
- "Creative passes brand approval but underperforms." Brand discipline at the cost of performance discipline. The hierarchy is wrong; voice in every frame, performance in the structure.
|
||||
- "TikTok ad uses Meta-style production." Platform norm violation. TikTok rejects polished ad creative; phone-shot native wins.
|
||||
- "Our hooks all start with the brand logo." Kills the first-3-second hook. Brand logo belongs at second 1 to 3 (after the hook lands), not at second 0.
|
||||
- "We never refresh creative because the old set still works ok." Incremental loss compounds. CTR decay is gradual; the team that does not refresh discovers a 40% performance gap when they finally check.
|
||||
|
||||
---
|
||||
|
||||
## The framework: 10 considerations for sustainable creative production
|
||||
|
||||
When designing or auditing ad creative, walk these 10 considerations.
|
||||
|
||||
1. **Performance vs brand.** Name what this creative is optimizing for; do not mix.
|
||||
2. **Hook strength.** First 3 seconds. Scroll-stopping. Specific.
|
||||
3. **Format-platform fit.** Native to the channel.
|
||||
4. **Pacing.** Value prop hits within 5 seconds; CTA by 15s.
|
||||
5. **Variation system.** Matrix-based, not ad-hoc.
|
||||
6. **Sequential testing.** Hooks, then bodies, then CTAs, then formats.
|
||||
7. **Fatigue monitoring.** Frequency, CTR decay, CPM trend, negative feedback.
|
||||
8. **Brand-voice alignment.** Voice that survives compression; performance in the structure.
|
||||
9. **Platform creative norms.** Vertical for short-video platforms, captions on, native production.
|
||||
10. **Refresh cadence.** Weekly to monthly by spend tier.
|
||||
|
||||
The output of the framework is a production plan. A list of variations to ship in the next testing cycle, the testing waterfall to run, the fatigue thresholds that trigger refresh, and the platform-specific norms the variations respect. Three answers from the framework: ship as planned, revise the plan, or stop because a precondition is missing.
|
||||
|
||||
---
|
||||
|
||||
## Reference files
|
||||
|
||||
- [`references/hook-pattern-library.md`](references/hook-pattern-library.md) - Twelve hook patterns with worked examples and anti-patterns for each.
|
||||
- [`references/format-decision-matrix.md`](references/format-decision-matrix.md) - Audience-objective context to recommended format with reasoning and common alternatives.
|
||||
- [`references/creative-variation-templates.md`](references/creative-variation-templates.md) - Matrix-based production system, naming conventions, asset library structure, half-day worked example.
|
||||
- [`references/testing-cadence-playbook.md`](references/testing-cadence-playbook.md) - Sequential testing waterfall with per-stage variant counts, durations, and winner-advancement criteria.
|
||||
- [`references/fatigue-detection-checklist.md`](references/fatigue-detection-checklist.md) - Five fatigue signals with thresholds and refresh decision tree.
|
||||
- [`references/platform-creative-norms.md`](references/platform-creative-norms.md) - Per-platform aspect ratios, lengths, audio expectations, caption norms, and native-aesthetic anti-patterns.
|
||||
- [`references/brand-voice-performance-balance.md`](references/brand-voice-performance-balance.md) - Voice attributes that survive 15-second compression vs those that do not, with a four-format worked example.
|
||||
|
||||
---
|
||||
|
||||
## Closing: the hook is the whole game
|
||||
|
||||
In performance creative, the hook is the whole game. If the hook fails, no body copy or CTA can recover the impression. A user who scrolled past the first second has already decided.
|
||||
|
||||
Spend the disproportionate creative effort on the first 3 seconds. The rest is delivery. The team that puts 60% of its creative effort into the hook and 40% into everything else outperforms the team that distributes effort evenly. The team that puts 90% of its effort into hooks and 10% into delivery beats both, as long as it ships enough variations for the testing waterfall to find which hooks actually work.
|
||||
|
||||
When in doubt, ship the variant. A weak variant ships; a perfect variant never does. The sequential testing waterfall finds the winners; the variation system makes shipping cheap. The asymmetric cost of inaction is real; the asymmetric cost of shipping a marginal variant is small.
|
||||
Vendored
+101
@@ -0,0 +1,101 @@
|
||||
# Brand voice plus performance balance
|
||||
|
||||
How to keep brand voice intact at 15-second performance scale without diluting conversion.
|
||||
|
||||
The tension. Brand voice often feels off-brand when squeezed into a 15-second ad. The instinct is to compromise: water down the voice for the format, or sacrifice the format for the voice. Both are wrong. The fix is hierarchy.
|
||||
|
||||
---
|
||||
|
||||
## Voice attributes that survive compression
|
||||
|
||||
Four attributes carry the brand voice in 15 seconds without consuming runtime.
|
||||
|
||||
**Tone.** Playful, serious, expert, irreverent, warm, blunt. Tone lives in the texture of every frame; it does not need narrative space to land. A blunt brand can write blunt captions in 15 seconds. A warm brand can shoot warm faces.
|
||||
|
||||
**Cadence.** Short sentences vs long-form. Short and punchy fits the 15-second frame; long sentences need 30+ seconds to land. The brand whose voice is short and punchy is naturally well-fit for performance creative.
|
||||
|
||||
**Vocabulary.** Industry-specific or accessible. Plain or formal. The brand voice that uses certain words and not others can preserve that vocabulary in any format.
|
||||
|
||||
**Visual treatment.** Color, type, motion language, photographic style. Visual identity survives in 1 second; it survives in 15.
|
||||
|
||||
---
|
||||
|
||||
## Voice attributes that do not survive compression
|
||||
|
||||
Three attributes need runtime to land. Forcing them into 15-second performance creates diluted versions that read as off-brand.
|
||||
|
||||
**Deep narrative arcs.** Hero's journey, character development, story-with-resolution. These need 30 to 60 seconds minimum. A 15-second compression of a narrative is the trailer, not the story.
|
||||
|
||||
**Complex metaphors.** A brand whose voice relies on extended metaphors needs runtime to set up the metaphor and pay it off. 15 seconds of metaphor is the setup with no payoff; the audience leaves confused.
|
||||
|
||||
**Layered humor that requires setup.** Jokes that depend on a long setup work in long-form. In 15 seconds the joke is too rushed to land. Punchline-style humor works; setup-dependent humor does not.
|
||||
|
||||
The implication. A brand whose voice is built on narrative depth or complex metaphor will struggle with performance creative. The fix is not to compromise the voice; the fix is to use the appropriate format for the voice. Long-form awareness ads carry the narrative; performance creative carries the tone, cadence, vocabulary, and visual treatment without trying to land the full narrative in 15 seconds.
|
||||
|
||||
---
|
||||
|
||||
## The hierarchy
|
||||
|
||||
Brand voice in every frame. Performance discipline in the structure.
|
||||
|
||||
**Voice in every frame.** The tone, cadence, vocabulary, and visual treatment of every clip, caption, and CTA reflects the brand. The audience watching three different ad variations should recognize the same brand across all of them.
|
||||
|
||||
**Performance in the structure.** The pacing, hook strength, value-prop placement, and CTA placement follow performance norms. Hook in 1 to 3 seconds. Value prop by 5 seconds. Social proof or demo by 7 to 12. CTA by 15. The structure is platform-driven, not voice-driven.
|
||||
|
||||
The two layers do not compete. Voice operates at the texture level; structure operates at the timing level. A blunt brand can be blunt in 1 second (texture) and structured in performance pacing (timing).
|
||||
|
||||
---
|
||||
|
||||
## Worked example: same voice, four formats
|
||||
|
||||
A brand whose voice is "warm and direct, slightly contrarian, plain-language" runs four creatives.
|
||||
|
||||
### 60-second YouTube awareness piece
|
||||
|
||||
The founder talks to camera. Plain language. Contrarian framing of the category. The opening question hooks; the middle 40 seconds tell the story of why the brand exists; the closing 10 seconds invite the audience to learn more.
|
||||
|
||||
Voice carries because there is runtime. Structure is narrative-led.
|
||||
|
||||
### 15-second Meta Reels performance ad
|
||||
|
||||
Fast cuts. Plain language captions on screen. Contrarian hook in second 1 ("Stop overpaying for project management software"). Specific value prop in seconds 4 to 7 ("$10 per user per month, all features"). Social proof in seconds 8 to 12 ("Used by 10,000+ teams"). CTA in seconds 13 to 15 ("Start your free trial").
|
||||
|
||||
Voice carries through tone (direct, plain) and visual treatment (consistent typography). Structure is performance-led.
|
||||
|
||||
### 15-second TikTok Spark Ad
|
||||
|
||||
Phone-shot. Creator-style. Plain language captions. Contrarian opening line spoken to camera ("Most project management tools cost too much"). Demonstration in seconds 4 to 9 (creator showing the product on their laptop). CTA in seconds 12 to 15.
|
||||
|
||||
Voice carries through tone and the conversational cadence. Production aesthetic is platform-native (phone-shot, not studio).
|
||||
|
||||
### Static carousel (6 cards)
|
||||
|
||||
Card 1: Contrarian opening ("Most PM tools cost too much"). Card 2: The number ($10/user). Card 3: The features. Card 4: The customer logos. Card 5: The story (one customer who switched). Card 6: CTA.
|
||||
|
||||
Voice carries through plain-language copy and consistent visual treatment. Structure is card-by-card progression, not narrative.
|
||||
|
||||
The check. A customer who has seen all four pieces should recognize them as the same brand. The voice is consistent. The structure is format-appropriate. None of the four feels off-brand.
|
||||
|
||||
---
|
||||
|
||||
## When voice and performance genuinely conflict
|
||||
|
||||
Two situations where the conflict is real, not solvable.
|
||||
|
||||
**The brand voice is built on narrative depth.** Some brands (especially heritage brands, premium brands, brands with founders who write long-form) have voices that genuinely require runtime. Performance creative for these brands often works better as static or carousel (where the depth lives in the copy) than as 15-second video (where the runtime is too short for the voice).
|
||||
|
||||
**The performance objective requires a tone the brand does not use.** Direct response often pushes toward urgency, scarcity, and aggressive CTAs. A brand whose voice is calm and considered will read as off-brand if the performance ad uses high-urgency CTAs. The fix is to push back on the performance team's CTA defaults; calm-and-considered brands can have calm-and-considered CTAs that still convert when the offer is right.
|
||||
|
||||
The default. Resolve the conflict by adjusting the format choice (use static or carousel for narrative-deep brands; use longer awareness pieces alongside performance) or by adjusting the CTA register (calm CTAs for calm brands). Do not compromise the voice; the voice is the long-term asset. Do not compromise the performance; the performance is the short-term revenue. Find the format and register that keeps both intact.
|
||||
|
||||
---
|
||||
|
||||
## Common mistakes
|
||||
|
||||
**Watering down the voice for the format.** A brand whose voice is sharp produces a soft 15-second ad to "fit the format." The audience does not recognize the brand; the ad converts marginally; the brand erodes.
|
||||
|
||||
**Sacrificing the format for the voice.** A brand whose voice is narrative-deep produces a 60-second performance ad with no hook. The audience scrolls past in 1 second; the voice never lands.
|
||||
|
||||
**Treating voice and structure as the same axis.** Voice is texture; structure is timing. They do not compete unless the voice depends on structure (narrative-led brands), in which case the format choice is the lever, not the voice itself.
|
||||
|
||||
**No brand-voice review on performance creative.** The performance team produces ads that convert but read as off-brand. A 5-minute brand-voice review on every variation catches the off-brand drift before it ships.
|
||||
+123
@@ -0,0 +1,123 @@
|
||||
# Creative variation templates
|
||||
|
||||
The matrix-based production system. How to produce 20 to 50 ad variations from one core concept in a half-day session.
|
||||
|
||||
The principle. A creative is a hook plus a body plus a CTA in a format. Treat each as a variable. The matrix lets you ship dozens of variations from minimal authoring overhead, which is what the sequential testing waterfall requires.
|
||||
|
||||
---
|
||||
|
||||
## The decomposition
|
||||
|
||||
A single creative is composed of independent components.
|
||||
|
||||
| Component | Example | Authoring cost |
|
||||
|---|---|---|
|
||||
| Concept | Theme or message ("the project management tax") | High (the strategy work) |
|
||||
| Hook | First 3 seconds, scroll-stop | Medium (per variant) |
|
||||
| Body | The middle 5 to 10 seconds | Medium |
|
||||
| CTA | The closing call to action | Low |
|
||||
| Format | Vertical video, carousel, static, etc. | Medium (rendering) |
|
||||
|
||||
The math. 1 concept times 5 hooks times 4 bodies times 3 CTAs times 2 formats equals 120 theoretical variations. Most are not worth shipping; the matrix typically narrows to 20 to 40 the team will actually run. The point is that authoring 5 hooks plus 4 bodies plus 3 CTAs equals 12 components total, which compose into 60 hook-body-CTA combinations.
|
||||
|
||||
---
|
||||
|
||||
## Variation matrix template
|
||||
|
||||
A simple spreadsheet that drives the production session.
|
||||
|
||||
| Concept | Hook ID | Body ID | CTA ID | Format | Variant ID | Status |
|
||||
|---|---|---|---|---|---|---|
|
||||
| launch2026 | hook_a | body_a | cta_a | meta-reel | v001 | drafted |
|
||||
| launch2026 | hook_b | body_a | cta_a | meta-reel | v002 | drafted |
|
||||
| launch2026 | hook_c | body_a | cta_a | meta-reel | v003 | drafted |
|
||||
| launch2026 | hook_a | body_b | cta_a | meta-reel | v004 | drafted |
|
||||
| launch2026 | hook_a | body_a | cta_b | meta-reel | v005 | drafted |
|
||||
| launch2026 | hook_a | body_a | cta_a | tiktok-vertical | v006 | drafted |
|
||||
| launch2026 | hook_a | body_a | cta_a | static-1x1 | v007 | drafted |
|
||||
|
||||
The status column tracks the production pipeline: drafted, rendered, approved, shipped, paused, retired.
|
||||
|
||||
---
|
||||
|
||||
## Naming conventions
|
||||
|
||||
Every variation has a structured name so the analyst can join performance data back to creative components.
|
||||
|
||||
```
|
||||
{concept}_{platform-format}_{hook}_{body}_{cta}_v{n}
|
||||
```
|
||||
|
||||
Examples:
|
||||
|
||||
```
|
||||
launch2026_meta-reel_hookA_bodyB_ctaC_v1
|
||||
launch2026_tiktok-vertical_hookE_bodyA_ctaA_v3
|
||||
launch2026_static-1x1_hookA_bodyA_ctaB_v2
|
||||
```
|
||||
|
||||
The analyst pulls the report, splits the names on the underscore, joins to a master variant table, and reports performance by component. "Hook E is winning across body and CTA combinations on TikTok" becomes a query, not a manual review.
|
||||
|
||||
---
|
||||
|
||||
## Asset library structure
|
||||
|
||||
Organize files by concept, not by date.
|
||||
|
||||
```
|
||||
concepts/
|
||||
launch2026/
|
||||
hooks/
|
||||
hookA-direct-callout.txt
|
||||
hookB-contrarian-claim.txt
|
||||
hookC-result-led.txt
|
||||
hookD-curiosity-gap.txt
|
||||
hookE-personal-story.txt
|
||||
bodies/
|
||||
bodyA-feature-list.txt
|
||||
bodyB-customer-story.txt
|
||||
bodyC-comparison.txt
|
||||
bodyD-process-walkthrough.txt
|
||||
ctas/
|
||||
ctaA-shop-now.txt
|
||||
ctaB-start-trial.txt
|
||||
ctaC-book-demo.txt
|
||||
visuals/
|
||||
hero-product-shot.png
|
||||
ugc-customer-1.mp4
|
||||
founder-camera.mp4
|
||||
rendered/
|
||||
meta-reel/
|
||||
tiktok-vertical/
|
||||
static-1x1/
|
||||
```
|
||||
|
||||
Date-based organization rots fast. Concept-based organization composes; the team that runs three concepts a quarter has three folders, each with a clean inventory of components. Six months in, the library is searchable.
|
||||
|
||||
---
|
||||
|
||||
## Half-day production session worked example
|
||||
|
||||
The goal. Produce 40 variations of one core concept in 4 hours. The team: one creative strategist, one editor, one copywriter.
|
||||
|
||||
**Hour 1: matrix planning.** Strategist drafts 5 hooks, 4 bodies, 3 CTAs against the concept brief. Copywriter refines language. Output: 12 component scripts.
|
||||
|
||||
**Hour 2: visual asset prep.** Editor pulls the visual library (hero product shot, two UGC videos, two founder-to-camera takes). Copywriter writes captions per platform. Output: visual atoms ready to compose.
|
||||
|
||||
**Hour 3: rendering.** Editor renders the matrix using a video editor's template feature (or a tool like Pencil, Vidico Forge, or in-house automation). The hook component swaps in; the body component swaps in; the CTA component swaps in; the format renders per platform. Output: 30 rendered variations.
|
||||
|
||||
**Hour 4: review and final renders.** Team reviews the 30 outputs, kills the 5 to 10 that fail the smell test, renders the final 10 that need higher-quality cuts. Output: 20 to 25 production-ready variations.
|
||||
|
||||
The math. 12 component scripts plus a half day of editor time produces 20 to 25 variations. Without the matrix, the same 20 to 25 variations require 5 days of independent authoring per variation.
|
||||
|
||||
---
|
||||
|
||||
## When the matrix breaks down
|
||||
|
||||
Two situations where the matrix is the wrong shape.
|
||||
|
||||
**Concept-driven brand work.** Awareness creative often does not decompose cleanly. The 60-second YouTube spot is one creative, not a matrix. The hook, body, and CTA are integrated into the narrative. For brand work, drop the matrix and produce one strong piece.
|
||||
|
||||
**Highly format-specific creative.** A behind-the-scenes TikTok is not a hook plus body plus CTA; it is a single creator's continuous take. Forcing the matrix produces stilted ads that read as agency-produced. For format-native creative, accept that one format produces one creative; do not try to render the same content into static.
|
||||
|
||||
The rule. Use the matrix for performance creative where direct response is the goal. Drop the matrix for awareness, brand, or format-native creative where the integrity of the piece matters more than ship volume.
|
||||
+110
@@ -0,0 +1,110 @@
|
||||
# Fatigue detection checklist
|
||||
|
||||
Five signals that creative is fatiguing, with thresholds and a refresh decision tree.
|
||||
|
||||
The principle. Creative fatigue is a real economic cost. The tired ad still spends; it just does not convert. The team that monitors fatigue catches the decay early; the team that does not discovers a 30 to 50% performance gap when they finally check.
|
||||
|
||||
---
|
||||
|
||||
## The five signals
|
||||
|
||||
### 1. Frequency above 4 to 5 per user per week
|
||||
|
||||
**Threshold.** Above 4 per user per week for performance ads. Above 5 for awareness ads.
|
||||
|
||||
**Why it matters.** The same audience sees the same creative too many times. CTR drops, irritation rises, brand association erodes.
|
||||
|
||||
**Where to check.** Meta Ads Manager: frequency report at the ad-set level. Google Ads: frequency at the campaign level. TikTok: less granular, but available at the ad group level.
|
||||
|
||||
**Action.** If frequency is climbing past 4, ship variants of the same concept (different copy and visuals, same hook structure). If multiple concepts are all climbing, the audience is too narrow; expand.
|
||||
|
||||
### 2. CTR declining 30%+ week over week
|
||||
|
||||
**Threshold.** A 30% drop week over week is the alarm. A 10 to 15% drop is normal noise; 30% is a signal.
|
||||
|
||||
**Why it matters.** The audience is no longer interested in the creative. Continuing to run it spends without producing the click.
|
||||
|
||||
**Where to check.** Each platform's reporting at the ad level over a 4-week window. Look at the trendline, not just the latest week.
|
||||
|
||||
**Action.** Refresh the creative within 7 days. If multiple ads in the same audience are dropping simultaneously, the audience is fatigued; rotate audiences as well as creative.
|
||||
|
||||
### 3. CPM increasing without audience saturation explanation
|
||||
|
||||
**Threshold.** A 25%+ increase over 14 days, with audience size and competition both stable.
|
||||
|
||||
**Why it matters.** The platform's algorithm is having to bid harder to deliver impressions because engagement signals are weakening. The audience is still there but the platform sees the creative as less relevant.
|
||||
|
||||
**Where to check.** Each platform's CPM trend. Cross-reference with audience overlap reports and competitor activity (Meta Ads Library, SimilarWeb, etc.).
|
||||
|
||||
**Action.** Refresh creative. The CPM will recover within 7 to 14 days of fresh creative landing.
|
||||
|
||||
### 4. Negative comments increasing
|
||||
|
||||
**Threshold.** Comments containing "spam," "stop showing me this," "annoying," or platform-specific negative reactions exceeding 1% of impressions.
|
||||
|
||||
**Why it matters.** Direct user signal of irritation. The audience is mad; the brand is paying for that anger.
|
||||
|
||||
**Where to check.** Meta Ads Manager: comments section per ad. TikTok: comments per ad. Less visible on LinkedIn.
|
||||
|
||||
**Action.** Pull the creative within 24 hours. Negative comments compound; the audience that complains often is the audience that complains to friends.
|
||||
|
||||
### 5. Hide ratio (negative feedback) increasing
|
||||
|
||||
**Threshold.** Meta exposes "negative feedback rate"; trigger refresh when it exceeds 1.5% of impressions or rises 50% week over week.
|
||||
|
||||
**Why it matters.** Hide is a stronger signal than scroll-past. The audience is actively rejecting the ad. Platform algorithms penalize creatives with high hide ratios by reducing reach.
|
||||
|
||||
**Where to check.** Meta Ads Manager: customize columns to expose negative feedback. Other platforms: less direct equivalents (TikTok "not interested" rate is similar).
|
||||
|
||||
**Action.** Pull the creative immediately. The cost is real: the platform will deliver less of all your ads to that audience as it learns to weight negative signals.
|
||||
|
||||
---
|
||||
|
||||
## Refresh cadence by spend tier
|
||||
|
||||
| Monthly spend | Refresh cadence | Variants per refresh |
|
||||
|---|---|---|
|
||||
| Under $5K | Monthly | 2 to 3 |
|
||||
| $5K to $25K | Biweekly | 3 to 5 |
|
||||
| $25K to $100K | Weekly | 5 to 10 |
|
||||
| Above $100K | Twice weekly | 10+ |
|
||||
|
||||
The economics. Producing a fresh variant costs less than running tired creative for one extra week. At $100K per month, even one day of underperformance is meaningful. Higher spend justifies higher refresh investment.
|
||||
|
||||
---
|
||||
|
||||
## Refresh decision tree
|
||||
|
||||
When fatigue signals trigger, three options. Pick based on the diagnosis.
|
||||
|
||||
**Option 1: variant of working concept.** The hook structure is still working but the specific creative is fatigued. Ship 3 to 5 variants of the same concept (different copy, different visuals, same hook structure).
|
||||
|
||||
When. CTR drop with frequency above threshold, but the concept itself was strong (top performer in the testing waterfall).
|
||||
|
||||
Cost. Half-day production session if the matrix is in place. Variants ship within 48 hours.
|
||||
|
||||
**Option 2: replace concept entirely.** The concept is exhausted. Ship a fresh concept (different hook structure, different angle, different value prop emphasis).
|
||||
|
||||
When. Multiple variants of the same concept are dropping simultaneously, or the concept has been in market for 6 to 12 weeks at high frequency.
|
||||
|
||||
Cost. Full production cycle. Variants ship within 1 to 2 weeks.
|
||||
|
||||
**Option 3: full creative rotation.** Multiple concepts are tired across the account. The audience is over-saturated.
|
||||
|
||||
When. CPM rising across multiple campaigns, hide ratio climbing across the account, multiple concepts dropping in parallel.
|
||||
|
||||
Cost. Quarterly creative refresh. Plan ahead; do not let the rotation be reactive.
|
||||
|
||||
---
|
||||
|
||||
## Common mistakes
|
||||
|
||||
**Watching only CTR.** CTR is a fatigue signal but not the only one. CPM and frequency lead CTR; the team watching only CTR is reactive when leading signals would have caught it 1 to 2 weeks earlier.
|
||||
|
||||
**Refreshing too late.** Once CTR has dropped 50%, the audience has already developed negative associations. The next creative inherits that fatigue context. Refresh on leading signals (CPM, frequency).
|
||||
|
||||
**Refreshing without analysis.** Producing fresh creative without understanding what worked about the previous creative. The team ships variants that miss what made the original successful and reverts to baseline performance.
|
||||
|
||||
**Ignoring the platform algorithm's cooldown.** A new creative variant goes through a learning phase (3 to 7 days). Performance during the learning phase is not representative; do not kill a new variant in week 1.
|
||||
|
||||
**Treating all fatigue the same.** Audience fatigue is different from creative fatigue. If multiple creatives are all fatigued, the audience is the problem. Rotate audiences, not just creative.
|
||||
+48
@@ -0,0 +1,48 @@
|
||||
# Format decision matrix
|
||||
|
||||
Audience-objective context to recommended format. Read top to bottom; pick the row that matches your situation.
|
||||
|
||||
---
|
||||
|
||||
## The matrix
|
||||
|
||||
| Context | Primary format | Secondary format | Reasoning and what to avoid |
|
||||
|---|---|---|---|
|
||||
| B2C direct response, fast-scroll platforms (Meta, TikTok) | Vertical video 9:16, 15s | Static image (retargeting) | Native to the feed, scroll-stop in 1s. Avoid horizontal video; it gets letterboxed and ignored. |
|
||||
| B2B SaaS demo or feature explainer | Carousel | Vertical video with captions | Carousel lets users self-pace; B2B audiences are in research mode. Avoid horizontal video for B2B feed placements. |
|
||||
| DTC visual product | UGC-style vertical video | In-feed product carousel | UGC retains organic feel and beats studio production for direct response. Avoid heavily produced product shots; reads as "ad" and gets skipped. |
|
||||
| Trust-led offer (financial, healthcare) | Static with social proof + carousel | UGC video with named customers | Trust requires repeat exposure to credible signals. Avoid moving cuts and music; reads as a pitch. |
|
||||
| Founder-led B2B SaaS | Founder-to-camera video, 15 to 30s | Static quote card | First-person specificity is high-trust. Avoid voiceover with stock footage; reads as agency-produced. |
|
||||
| Education-led content marketing | Long-form video (60s to 3m) | Carousel | Long-form rewards educational content. Use for awareness or top-funnel; not direct response. |
|
||||
| App install | Vertical video with screen recording | Static screenshot grid | Screen recording shows the product in 5 seconds, faster than narration. Avoid feature lists; show the product. |
|
||||
| Local services | Static image + lead form | UGC-style customer quote | Lead capture is the goal; minimize friction. Avoid long video; the audience is conversion-ready. |
|
||||
| Enterprise B2B (>$50K ACV) | LinkedIn Sponsored Content with carousel or static | Long-form video for awareness | Professional tone, slower pacing. Avoid TikTok-style fast cuts; reads as off-platform. |
|
||||
| Retargeting (warm audience) | Static image with offer | Short carousel with social proof | Audience already knows the brand; lead with the offer or social proof, not the brand intro. Avoid full hooks; the audience does not need them. |
|
||||
| Black Friday or peak moment | Static with discount + countdown | Vertical video with offer + urgency | Speed matters in peak; the audience is decision-ready. Avoid long-form storytelling. |
|
||||
| Pre-launch awareness | Long-form vertical video, 30 to 60s | Carousel for waitlist | The audience is curious, not converting. Reward attention with substance. Avoid short performance hooks; they undersell. |
|
||||
|
||||
---
|
||||
|
||||
## Decision rules
|
||||
|
||||
Three rules apply across the matrix.
|
||||
|
||||
**Match the platform's native style.** A 1:1 video on TikTok performs worse than the same video as 9:16 vertical. A horizontal video on LinkedIn performs better than the same vertical, because LinkedIn audiences watch on desktop more than TikTok audiences do. Rules differ; produce per platform.
|
||||
|
||||
**Match the audience's consumption mode.** Scroll mode (TikTok, Reels) needs hook in 1 second. Research mode (LinkedIn, B2B blogs) tolerates longer pacing. Decision mode (retargeting, peak moments) wants the offer up front and skips the hook.
|
||||
|
||||
**Match the offer's complexity to the format's information density.** Simple offers (a discount, a free trial) work in static. Complex offers (a multi-feature product, a service with a process) need carousel or video. Forcing a complex offer into static fails because the audience cannot understand what is being offered in 1 second.
|
||||
|
||||
---
|
||||
|
||||
## Common mistakes
|
||||
|
||||
**One format across all platforms.** A 16:9 video produced for YouTube does not work on TikTok or Reels. The team that ships one format and adapts crops produces underperforming creative on every platform except the one the format was designed for.
|
||||
|
||||
**Format chosen by what is easy to produce.** Static is fastest to make; teams default to it even when video would convert 3x better. The cost of one good vertical video is recouped in one strong campaign; the production overhead is real but worth it for high-spend campaigns.
|
||||
|
||||
**Format chosen without testing.** Most teams pick a format and stick with it. The matrix gives a starting point; the testing waterfall (see `testing-cadence-playbook.md`) gives the real answer for the specific brand and audience.
|
||||
|
||||
**Carousel without progression.** A carousel is a multi-card story. Each card should advance the narrative or value prop. Six cards of the same image with different text waste the format.
|
||||
|
||||
**Vertical video without captions.** Most users watch sound-off. A vertical video without captions communicates only its visual; the value prop disappears. Captions are not optional on Meta and TikTok.
|
||||
+157
@@ -0,0 +1,157 @@
|
||||
# Hook pattern library
|
||||
|
||||
Twelve hook patterns that work consistently in performance creative. For each: what makes it work, when it fits, the anti-pattern, and one or two worked examples.
|
||||
|
||||
A hook is the first 1 to 3 seconds of an ad. If the hook fails, the rest of the creative does not get watched. The hook carries 60% of the performance weight; the body and CTA carry 40%. Spend the creative effort accordingly.
|
||||
|
||||
---
|
||||
|
||||
## 1. Problem-agitate-solve
|
||||
|
||||
**What makes it work.** Names the audience's pain in their own language, then makes the consequence vivid, then offers the way out. The structure mirrors how the audience already thinks.
|
||||
|
||||
**When it fits.** When the audience recognizes the pain and feels it as a real cost. Less effective when the pain is abstract.
|
||||
|
||||
**Anti-pattern.** Skipping the agitate step. The audience hears the problem named and shrugs because the consequence is not vivid.
|
||||
|
||||
**Example.** "Spending 4 hours a week on status updates? That is 200 hours a year. (Pause.) StatusBot writes them for you in 5 minutes."
|
||||
|
||||
---
|
||||
|
||||
## 2. Direct callout to audience
|
||||
|
||||
**What makes it work.** Triggers self-identification in the first second. The viewer thinks "that is me" and watches.
|
||||
|
||||
**When it fits.** When the audience is narrow, self-aware, and proud of the identity. Founders, doctors, parents, runners, B2B SaaS PMs.
|
||||
|
||||
**Anti-pattern.** Calling out an audience that is too broad. "If you are a person on the internet..." triggers nothing.
|
||||
|
||||
**Example.** "If you are a B2B founder running paid ads with no in-house marketer, this is for you."
|
||||
|
||||
---
|
||||
|
||||
## 3. Contrarian claim
|
||||
|
||||
**What makes it work.** Violates expectation. The viewer's brain pauses on the contradiction.
|
||||
|
||||
**When it fits.** When the audience has heard the conventional wisdom too many times and is exhausted by it.
|
||||
|
||||
**Anti-pattern.** Contrarian for its own sake. The claim has to be defensible by the body of the ad; otherwise the audience disengages by second 5.
|
||||
|
||||
**Example.** "Stop using lookalike audiences. Here is the audience strategy that actually scales."
|
||||
|
||||
---
|
||||
|
||||
## 4. Result-led
|
||||
|
||||
**What makes it work.** Specific number plus specific timeframe. The brain treats specificity as a credibility signal.
|
||||
|
||||
**When it fits.** When the result is real and documented. Faked numbers train the audience to scroll past the entire account.
|
||||
|
||||
**Anti-pattern.** Vague results. "We helped a client grow" produces no curiosity; "we cut their CAC 40% in 30 days" does.
|
||||
|
||||
**Example.** "How we cut CAC 40% in 30 days for a Series B SaaS with no creative budget."
|
||||
|
||||
---
|
||||
|
||||
## 5. Curiosity gap
|
||||
|
||||
**What makes it work.** Promises a payoff after the gap. The viewer stays to find out.
|
||||
|
||||
**When it fits.** When the gap is real and the payoff is on-topic. Clickbait without payoff trains the audience to scroll past.
|
||||
|
||||
**Anti-pattern.** Gap without payoff. "The mistake 80% of marketers make..." with no actual mistake named in the body of the ad. Audience feels deceived.
|
||||
|
||||
**Example.** "The mistake 80% of marketers make on Meta Ads is the one that costs them 30% of their budget every month."
|
||||
|
||||
---
|
||||
|
||||
## 6. Social proof at top
|
||||
|
||||
**What makes it work.** Validation before pitch. The audience trusts the offer because someone they trust trusts it.
|
||||
|
||||
**When it fits.** When the proof is impressive enough to do the heavy lifting. Specific names beat generic numbers when the audience knows the names.
|
||||
|
||||
**Anti-pattern.** Generic proof. "Trusted by thousands" is filler. "Used by Notion, Brex, and Figma" is signal.
|
||||
|
||||
**Example.** "Used by 10,000+ teams including Notion, Brex, and Whatnot. Now available for solo founders too."
|
||||
|
||||
---
|
||||
|
||||
## 7. Visual pattern interrupt
|
||||
|
||||
**What makes it work.** A surprising visual that does not match the platform's usual feed flow. The eye snaps to it.
|
||||
|
||||
**When it fits.** TikTok, Reels, Stories. Platforms with fast scroll and high pattern density. Less effective on slower platforms (LinkedIn).
|
||||
|
||||
**Anti-pattern.** Overproduced visual interrupt that reads as ad. The interrupt has to feel native to the platform; a Hollywood-style pattern interrupt on TikTok reads as "ad" and gets skipped.
|
||||
|
||||
**Example.** A creator-style cold open: a person on screen, looking confused at their phone, then turning the camera around to show the screen. Two-second hook before the first word.
|
||||
|
||||
---
|
||||
|
||||
## 8. Question that hits intent
|
||||
|
||||
**What makes it work.** The question pre-qualifies the audience. The audience that does not match disengages immediately, which is fine.
|
||||
|
||||
**When it fits.** When the question matches a real search query the audience has typed. "Tired of paying $400 for project management software" works because that is what the audience googles.
|
||||
|
||||
**Anti-pattern.** Generic questions. "Want to grow your business?" filters nothing.
|
||||
|
||||
**Example.** "Tired of paying $400 a month for project management software you barely use?"
|
||||
|
||||
---
|
||||
|
||||
## 9. Number-led
|
||||
|
||||
**What makes it work.** Lists trigger the brain's pattern-completion instinct. The viewer wants to know all three (or five, or seven) reasons.
|
||||
|
||||
**When it fits.** Educational content, list-style ads. Less effective for product ads where the offer should be specific.
|
||||
|
||||
**Anti-pattern.** Too many items. "10 reasons" is too many for a 15-second ad; 3 to 5 is the sweet spot.
|
||||
|
||||
**Example.** "3 changes that doubled our ROAS in Q4. Number 2 surprised our agency."
|
||||
|
||||
---
|
||||
|
||||
## 10. Personal story open
|
||||
|
||||
**What makes it work.** First-person specificity. The brain treats personal stories as data, not pitch.
|
||||
|
||||
**When it fits.** When the story is real and the conclusion is action-relevant. Founder-led ads especially.
|
||||
|
||||
**Anti-pattern.** Manufactured stories that read as fictional. The audience can usually tell.
|
||||
|
||||
**Example.** "Last year I was burning $50K a month on Meta ads with no return. Here is what I changed in 30 days."
|
||||
|
||||
---
|
||||
|
||||
## 11. Comparison
|
||||
|
||||
**What makes it work.** Pits two options against each other. The audience in evaluation mode wants the comparison.
|
||||
|
||||
**When it fits.** When the audience is actively comparing. "X vs Y" search queries are the tell.
|
||||
|
||||
**Anti-pattern.** Unfair comparisons. The audience smells the spin and discounts the brand.
|
||||
|
||||
**Example.** "Notion vs Linear: which actually works for engineering teams under 50."
|
||||
|
||||
---
|
||||
|
||||
## 12. Behind-the-scenes / process
|
||||
|
||||
**What makes it work.** Demystifies the work. The audience that wonders how something is done watches to find out.
|
||||
|
||||
**When it fits.** When the process is the differentiator. Agencies, services businesses, niche craft.
|
||||
|
||||
**Anti-pattern.** Process content that is actually a sales pitch in disguise. Audience disengages.
|
||||
|
||||
**Example.** "How we onboard a new client in 7 days, end to end, with one PM and no kickoff meeting."
|
||||
|
||||
---
|
||||
|
||||
## The pattern across all twelve
|
||||
|
||||
Every working hook does the same thing: it makes the next second non-optional. The viewer cannot skip without losing something. Specificity, surprise, identification, curiosity, proof. Different mechanisms; same effect.
|
||||
|
||||
The non-working hooks all do the same thing too: they let the viewer skip with no cost. Generic openings. Brand logo cards. Slow zooms over title text. "In today's world..." The first second is for the hook. The brand can wait.
|
||||
+111
@@ -0,0 +1,111 @@
|
||||
# Platform creative norms
|
||||
|
||||
Per-platform creative requirements and unwritten conventions. Each platform has native norms; violating them tanks performance.
|
||||
|
||||
---
|
||||
|
||||
## Meta (Facebook plus Instagram)
|
||||
|
||||
**Aspect ratios.** 9:16 for Reels and Stories. 4:5 for in-feed (preferred over 1:1; uses more vertical real estate). 1:1 acceptable. Avoid 16:9 horizontal in feed.
|
||||
|
||||
**Length.** 15 seconds is the sweet spot for performance. 6-second bumpers work for awareness. Long-form (60s+) only for storytelling formats; performance ads should resolve by 15s.
|
||||
|
||||
**Audio.** Sound-off is the default. Captions are mandatory. Music is helpful when matched to the platform's audio context (low-fi background, not stock library bombast).
|
||||
|
||||
**Captions.** On-screen captions for spoken audio. Bold, high-contrast, animated to track delivery. Avoid tiny captions; they are unreadable at scroll speed.
|
||||
|
||||
**Native aesthetic.** Phone-shot or polished both work. UGC-style outperforms studio for direct response; studio outperforms for awareness. The brand voice and the offer drive which fits.
|
||||
|
||||
**Anti-patterns.** Horizontal video in feed (gets letterboxed). No captions on spoken audio. Brand logo at second 0 (kills the hook). Slow zoom over title cards. Stock music bombast. Overproduced agency-style cuts that signal "ad" before the value lands.
|
||||
|
||||
**What feels native.** Real people on camera. Direct address. Specific value props. Social proof named with brand names. Pacing that respects the user's scroll velocity (cuts every 1 to 2 seconds in the first 5 seconds).
|
||||
|
||||
---
|
||||
|
||||
## TikTok
|
||||
|
||||
**Aspect ratios.** 9:16 vertical only. Anything else is rejected by the algorithm.
|
||||
|
||||
**Length.** 15 to 30 seconds for performance. The platform tolerates and rewards longer dwell than Meta.
|
||||
|
||||
**Audio.** Sound-on is default. Trending sounds compound reach but expire fast. Original audio works. Captions for accessibility, not just for sound-off viewers.
|
||||
|
||||
**Native aesthetic.** Phone-shot, creator-style. Studio production reads as "ad" and gets skipped. Pencil-and-paper aesthetic, jump cuts, unfiltered backgrounds, daylight.
|
||||
|
||||
**Spark Ads.** Boost an existing organic post. Retains organic engagement signal. Outperforms pure paid creative; if the brand has organic content performing, this is the format. The Pipeboard and Synter MCPs cover Spark Ad creation; the integrations microsite covers the tactical setup.
|
||||
|
||||
**Anti-patterns.** Polished agency video. Brand logo at second 0. Voiceover with stock footage. Slow-paced narrative. Music that signals "ad" (cinematic stock library). Anything that does not look like a creator filmed it.
|
||||
|
||||
**What feels native.** Direct-to-camera creator. Fast cuts (1 to 2 seconds). On-screen captions following the speaker. Trending sounds when they fit. Backgrounds that look like a kitchen or bedroom, not a studio.
|
||||
|
||||
---
|
||||
|
||||
## LinkedIn
|
||||
|
||||
**Aspect ratios.** 1:1 or 16:9 for feed. 9:16 vertical works for Stories but Stories has limited reach on LinkedIn relative to other platforms.
|
||||
|
||||
**Length.** 15 to 60 seconds. Slower pacing tolerated; B2B audiences are in research mode rather than scroll mode. 30 seconds is a strong default.
|
||||
|
||||
**Audio.** Sound-off default but sound-on more common than Meta. Captions still recommended. Music optional; many high-performing LinkedIn ads use no music.
|
||||
|
||||
**Voice.** Professional. B2B vocabulary fine; consumer-style copy reads as off-platform. Thought leadership framing works; product pitches feel salesy.
|
||||
|
||||
**Native aesthetic.** Founder-to-camera, expert-to-camera, slide-deck style, screen-recording demos. Studio production fine for LinkedIn; the audience is more tolerant of polished production than TikTok.
|
||||
|
||||
**Anti-patterns.** TikTok-style fast cuts. Bombastic music. Casual or irreverent tone for serious B2B categories. UGC-style production for high-trust offers (financial services, healthcare). Generic "let us help your business grow" copy.
|
||||
|
||||
**What feels native.** Specific industry vocabulary. Named customers and case studies. Slower pacing. Captions over slides. Founder-led specificity beats agency-style polish.
|
||||
|
||||
---
|
||||
|
||||
## Google Search
|
||||
|
||||
**Format.** Text-only headlines plus descriptions plus extensions.
|
||||
|
||||
**Character limits.** Headlines 30 characters; 15 headline variants for RSA. Descriptions 90 characters; 4 description variants. Path 1 and Path 2 in the display URL: 15 characters each.
|
||||
|
||||
**RSA optimization.** Provide 15+ headline variants and 4 description variants. The platform mixes them. More variants give the platform more material to optimize against.
|
||||
|
||||
**Voice.** Direct. Specific. Action-led. The search query is high-intent; the ad's job is to confirm the user is in the right place.
|
||||
|
||||
**Anti-patterns.** Keyword stuffing in headlines. Generic "we do X" headlines. Same value prop in every headline (the platform cannot test variation). Caps lock entire headlines (rejected). Unsubstantiated superlatives.
|
||||
|
||||
**What works.** Specific value props per headline ("Free 14-day trial", "Used by 10,000+ teams", "Deploy in 5 minutes"). Question headlines that match search intent. Geographic specificity for local. Price points where they are the differentiator.
|
||||
|
||||
---
|
||||
|
||||
## Google Display and YouTube
|
||||
|
||||
### Display
|
||||
|
||||
**Format.** Static or short animated banners across the Google Display Network.
|
||||
|
||||
**Anti-patterns.** Unhelpful targeting (broad display drives garbage clicks). Vague creative (the audience is not in search mode; they need the value prop fast).
|
||||
|
||||
**What works.** Retargeting with specific offers. Contextual placements (publisher list filtering). Cart-abandonment creative.
|
||||
|
||||
### YouTube
|
||||
|
||||
**Format.** Skippable video ads (TrueView), non-skippable, bumper (6s), in-feed video.
|
||||
|
||||
**Length.** Skippable: 15s to 6m. Non-skippable: 15s. Bumper: 6s.
|
||||
|
||||
**Audio.** Sound-on default. Captions still recommended for accessibility.
|
||||
|
||||
**Native aesthetic.** YouTube allows longer narrative; the audience is in dwell mode. Both phone-shot and studio production work depending on context.
|
||||
|
||||
**Anti-patterns.** Saving the value prop for the unskippable end. Skippable ads need to earn the next second; the value prop has to land in 5 seconds even on skippable.
|
||||
|
||||
**What works.** First 5 seconds earn the rest. Specific value props. Demonstrations. Skippable with strong hooks routinely outperform non-skippable because the audience self-selects into watching.
|
||||
|
||||
---
|
||||
|
||||
## Cross-platform principles
|
||||
|
||||
Three rules apply across the matrix.
|
||||
|
||||
**Native production beats repurposing.** A 16:9 video produced for one platform and cropped for others performs worse than three platform-native pieces. Produce per platform; do not adapt.
|
||||
|
||||
**Pacing matches the platform's scroll velocity.** TikTok scroll is fast; cuts every 1 to 2 seconds. LinkedIn scroll is slow; longer takes work. Meta is in between.
|
||||
|
||||
**Captions everywhere.** Sound-off is the default on most platforms most of the time. Spoken audio without captions is wasted audio.
|
||||
+121
@@ -0,0 +1,121 @@
|
||||
# Testing cadence playbook
|
||||
|
||||
The sequential testing waterfall. How to find the winning creative without testing 50 things at once.
|
||||
|
||||
The principle. Variance compounds. Testing all variables at once means you cannot tell whether the hook, the body, the CTA, or the format made the difference. Sequential testing isolates the variable that matters at each step.
|
||||
|
||||
---
|
||||
|
||||
## The waterfall
|
||||
|
||||
Five stages. Each stage isolates one variable and advances the winners.
|
||||
|
||||
### Stage 1: Hook test
|
||||
|
||||
**Goal.** Find which hooks stop the scroll.
|
||||
|
||||
**Setup.** 5 to 10 hook variants, same body, same CTA, same format. Each variant gets equal budget initially.
|
||||
|
||||
**Duration.** 7 to 14 days, or until each variant has 50+ conversions or 1M+ impressions, whichever comes first.
|
||||
|
||||
**Winner criteria.** Top 2 to 3 hooks by CTR (the metric that isolates hook performance) plus conversion rate above the floor. Eliminate hooks with high CTR but low conversion (the click is generated by the hook but the ad does not deliver).
|
||||
|
||||
**Output.** 2 to 3 winning hooks advance to Stage 2.
|
||||
|
||||
### Stage 2: Body test
|
||||
|
||||
**Goal.** Find which body copy or middle-section visuals convert best given the winning hooks.
|
||||
|
||||
**Setup.** Winning hooks times 5 to 10 body variants. Same CTA, same format. If two hooks advanced, that is 2 hooks times 5 bodies equals 10 ad sets.
|
||||
|
||||
**Duration.** 7 to 14 days, or until each combination has 50+ conversions.
|
||||
|
||||
**Winner criteria.** Top 2 to 3 hook plus body combinations by conversion rate. CTR is no longer the primary metric; the body is what holds attention after the hook.
|
||||
|
||||
**Output.** 2 to 3 hook plus body combinations advance to Stage 3.
|
||||
|
||||
### Stage 3: CTA test
|
||||
|
||||
**Goal.** Find which CTA produces the strongest action given the winning hook plus body.
|
||||
|
||||
**Setup.** Winning hook plus body combinations times 3 to 5 CTAs. Same format. Differences at this stage are usually marginal; do not over-engineer.
|
||||
|
||||
**Duration.** 5 to 10 days, or until each combination has 30+ conversions.
|
||||
|
||||
**Winner criteria.** Top hook plus body plus CTA combinations by conversion rate plus AOV (if value matters).
|
||||
|
||||
**Output.** 2 to 4 winning combinations advance to Stage 4.
|
||||
|
||||
### Stage 4: Format test
|
||||
|
||||
**Goal.** Find which format works best for the winning combinations.
|
||||
|
||||
**Setup.** Winning combinations rendered in 2 to 3 formats (vertical video, carousel, static).
|
||||
|
||||
**Duration.** 7 to 14 days.
|
||||
|
||||
**Winner criteria.** Top combinations by conversion rate within each format. Different formats may have different winners; that is fine. Run the winning format per surface.
|
||||
|
||||
**Output.** 2 to 4 production-ready creatives ready for evergreen rotation.
|
||||
|
||||
### Stage 5: Evergreen rotation
|
||||
|
||||
**Goal.** Run winners at scale; refresh on cadence.
|
||||
|
||||
**Setup.** 2 to 4 winners running in rotation. Frequency capping per audience.
|
||||
|
||||
**Duration.** Ongoing. Refresh creative on the cadence in `fatigue-detection-checklist.md`.
|
||||
|
||||
---
|
||||
|
||||
## Statistical thresholds
|
||||
|
||||
Two ways to call winners. Pick one and standardize across the team.
|
||||
|
||||
**Statistical significance.** Run until the winner has 95% confidence (or whatever threshold the team agrees on). Some platforms expose a "significance" indicator; others do not.
|
||||
|
||||
**Pre-commit duration plus minimum volume.** Decide before launching: "we will run for 14 days, each variant gets at least 50 conversions, top performer wins." This is the simpler, more honest approach for most performance work. The platform's algorithm will not run a clean test under your nose anyway, so trying for high-confidence statistical significance is often overkill.
|
||||
|
||||
The trap. Calling winners on small samples. A variant with 5 conversions and 10% lift over the other looks impressive but is within margin of platform noise. Wait for volume before declaring.
|
||||
|
||||
---
|
||||
|
||||
## Common mistakes
|
||||
|
||||
**Testing too many variables at once.** The most common mistake. Six hooks times five bodies times three CTAs times two formats equals 180 ad sets. The platform cannot optimize against that many variants; the team cannot interpret the results. Sequential is slower but produces real learnings.
|
||||
|
||||
**Killing variants too early.** A variant in the learning phase has not yet converged. The platform's first 3 days of delivery are not representative. Wait at least 7 days before killing.
|
||||
|
||||
**Calling winners on CTR alone.** A hook can drive high CTR with no conversion follow-through. The hook is doing its job (stopping the scroll) but the body is failing. Use conversion rate as the primary winner criterion; CTR is a hook-quality signal, not a creative-quality signal.
|
||||
|
||||
**No exclusion of recent converters from the test audience.** Recent converters click ads at higher rates because they are warm; mixing them into the test audience produces false-positive results. Exclude.
|
||||
|
||||
**Ignoring fatigue during the test.** A variant that wins the test in week 1 because it is new can underperform in week 4 once frequency builds. Test results are read against frequency; high-frequency winners are unreliable.
|
||||
|
||||
---
|
||||
|
||||
## Per-stage budget guidance
|
||||
|
||||
Rough percentages for the testing budget within a campaign's total spend.
|
||||
|
||||
| Stage | Share of testing budget |
|
||||
|---|---|
|
||||
| Hook test | 40% |
|
||||
| Body test | 25% |
|
||||
| CTA test | 10% |
|
||||
| Format test | 15% |
|
||||
| Buffer (re-tests, lift checks) | 10% |
|
||||
|
||||
The hook test gets the biggest share because it filters the most variants. CTA and format tests are smaller because the differences are usually marginal.
|
||||
|
||||
---
|
||||
|
||||
## When to break the waterfall
|
||||
|
||||
Two situations.
|
||||
|
||||
**Time pressure.** A peak moment (Black Friday, product launch) does not allow 6 weeks of sequential testing. Compress: run a hook test concurrently with format test using your best-guess body and CTA. Accept lower confidence in exchange for speed.
|
||||
|
||||
**Discovery of an outlier.** A hook variant that is winning by 5x at the end of week 1 should not wait for the full 14-day stage. Promote early, but track the long-tail performance to confirm.
|
||||
|
||||
The default is the waterfall. The exceptions are real but rare; do not let "we are on a tight timeline" become the default reason to skip the discipline.
|
||||
@@ -0,0 +1,275 @@
|
||||
---
|
||||
name: ads-performance-analytics
|
||||
description: "How to read paid media dashboards without fooling yourself. Attribution models, platform reporting quirks, multi-platform reconciliation, ROAS vs LTV horizon traps, statistical noise in performance metrics, incrementality testing, and the failure modes that produce expensive lessons. Triggers on read paid media dashboard, attribution analysis, ROAS vs LTV, multi-platform reconciliation, ad incrementality, geo holdout, conversion lift study, ghost bidding, paid media reporting, board-deck paid media metrics, blended CAC, MMM, MTA, last-click attribution. Also triggers when a marketer is about to scale, kill, or rebudget a campaign based on platform metrics, or when reconciling platform reports against warehouse revenue."
|
||||
category: marketing
|
||||
catalog_summary: "Read paid media dashboards without fooling yourself: attribution models, platform reporting quirks, ROAS vs LTV, multi-platform reconciliation, incrementality testing, and the interpretation failures that compound into wasted budget"
|
||||
display_order: 3
|
||||
---
|
||||
|
||||
# Ads Performance Analytics
|
||||
|
||||
A data-team-mentor's playbook for interpreting paid media dashboards without fooling yourself.
|
||||
|
||||
The dashboard is the moment of truth for paid media decisions. The numbers on it determine whether you scale, hold, or kill. They also expose every platform's self-attribution bias, every modeled-conversion shortcut, every cross-platform double-count. Most "scale this campaign" decisions trace back to misreading the dashboard.
|
||||
|
||||
This skill is the discipline that prevents misreading. It assumes the campaign was strategically sound (see `paid-media-strategy`). It assumes the creative was tested properly (see `ads-creative-development`). The hard part is knowing what each number actually means, what it does not, and how to reconcile platform-reported metrics with the truth in your warehouse.
|
||||
|
||||
When to use this skill: any time you are about to scale, kill, or rebudget a campaign based on platform metrics; reconciling platform reports with revenue data; evaluating an agency's reporting; or building a paid media dashboard that will not lie to you.
|
||||
|
||||
---
|
||||
|
||||
## What this skill is for
|
||||
|
||||
This skill spans paid media result interpretation. It does not cover paid media strategy (use `paid-media-strategy`), creative production (use `ads-creative-development`), or platform-specific tooling (covered in the integrations microsites). Pair this skill with the relevant integrations microsite for platform-specific MCP commands and example prompts.
|
||||
|
||||
The audience is a marketer, growth analyst, agency analyst, or founder evaluating paid media reports. The voice is patient and clinical. There is no "trust the platform's number" or "ignore the platform entirely." Both are wrong. The discipline is knowing which numbers from which platform mean what, and what to reconcile against to make the actual decision.
|
||||
|
||||
---
|
||||
|
||||
## The result panel: what every paid media platform should expose
|
||||
|
||||
A trustworthy result panel exposes nine things. Anything missing is a signal to treat reported numbers with extra skepticism.
|
||||
|
||||
1. **Spend, impressions, clicks.** Table-stakes metrics. Should match across platforms within rounding.
|
||||
2. **Conversions with definition and window visible.** Not just a count; the definition of what counts as a conversion and the attribution window applied. Without this, the count is unreadable.
|
||||
3. **Attribution breakdown.** Last-click vs view-through vs modeled. The mix of how the conversions were credited.
|
||||
4. **Frequency.** Impressions per unique user. The fatigue early-warning system.
|
||||
5. **Audience saturation.** Where the platform exposes it. A flat audience-saturation curve means there is room to scale; a steep curve means efficiency is dropping.
|
||||
6. **Time series.** Daily breakdown to spot novelty effects, fatigue, day-of-week patterns, and exogenous variance.
|
||||
7. **Cost metrics in clear currency.** CPC, CPM, CPA, ROAS with the math defined and the currency labeled. Do not assume USD.
|
||||
8. **Conversion path data.** Touchpoints before conversion, where available. Tells you whether a campaign is a closer or an opener.
|
||||
9. **Filters, segments, and exports.** Without these, the panel is a brochure, not a tool.
|
||||
|
||||
Platforms hide what makes their reporting look weakest. Google PMax hides keyword-level and placement-level data. Meta hides the modeled-conversion share. LinkedIn hides cross-device click paths. Treat hidden metrics as the place to dig.
|
||||
|
||||
---
|
||||
|
||||
## Platform-reported vs reality
|
||||
|
||||
Every platform's dashboard is optimized to make the platform look effective. This is not a moral failing; it is a structural incentive. Platforms with rosier reporting attract more spend.
|
||||
|
||||
**Conversion windows.** Meta defaults to 7-day click plus 1-day view. Google defaults to 30-day click plus 1-day view. Different windows, same activity, different reported numbers. If you compare Google's 30-day-click count against Meta's 7-day-click count, you are comparing different definitions and pretending they are the same.
|
||||
|
||||
**View-through attribution.** Counted by Meta and Google for users who saw but did not click. Often half the reported "conversions" are view-through. Treat view-through as a signal of awareness contribution, not as a direct response measurement. The user might have converted from organic search anyway.
|
||||
|
||||
**Modeled conversions.** When iOS users opt out of tracking, Meta and others statistically model what the conversion would have been. Modeled numbers are educated guesses, not measurements. They are useful for direction; they are not reliable for precision.
|
||||
|
||||
**Self-attribution bias.** Every platform's pixel fires on conversion and the platform claims credit. If you ran Meta, Google, and TikTok in the same week, all three platforms report your conversions as theirs. Sum-of-platforms is always greater than 100% of actual conversions.
|
||||
|
||||
The discipline. Never report platform-reported numbers as fact in board decks. Always reconcile against the single source of truth (warehouse, GA4, or unified analytics platform). Detail in [`references/platform-reporting-quirks.md`](references/platform-reporting-quirks.md).
|
||||
|
||||
---
|
||||
|
||||
## Attribution models in practice
|
||||
|
||||
Six models and one anti-model. None is right. They are all approximations. The discipline is picking one, committing, and reading the others as sanity checks.
|
||||
|
||||
**Last-click.** Simple, reproducible, undercredits awareness. The conversion is fully credited to the last click before the conversion event. Easy to compute; easy to compare across channels; bad for understanding upper-funnel contribution.
|
||||
|
||||
**First-click.** Opposite bias. Fully credits the first touchpoint, undercredits closing channels. Useful as a sanity check against last-click; rarely the right primary view.
|
||||
|
||||
**Linear.** Equal credit across all touchpoints. Gives every channel something. Defensible; not informative. Most useful for board reporting where avoiding "Google gets 70% so we cut Meta" politics matters more than precision.
|
||||
|
||||
**Time-decay.** More credit to recent touchpoints. Reflects the intuition that recent ads are more influential. Hard to argue against; hard to verify.
|
||||
|
||||
**U-shaped (position-based).** Heavy on first and last (40% each), light on middle (20% distributed). Honors both opener and closer roles. The default in many MTA tools.
|
||||
|
||||
**Data-driven attribution (DDA, Google).** Machine-learning model that distributes credit based on observed conversion paths. Opaque; hard to audit. The closest to "right" for digital channels but a black box.
|
||||
|
||||
**Marketing mix modeling (MMM).** Regression-based, top-down. Uses spend and revenue time series across channels to estimate channel contributions. Requires 2+ years of data. The strongest defense against platform self-attribution because it does not rely on platform-reported conversions at all.
|
||||
|
||||
**The anti-model: trusting platform-reported attribution.** Each platform's "DDA" or "attributed conversions" is the platform's self-attribution. Sum across platforms exceeds reality. Use platform attribution for in-flight optimization within the platform; use a unified attribution model for cross-channel decisions.
|
||||
|
||||
Practical guidance.
|
||||
|
||||
- Early-stage. Use last-click plus a single guardrail metric (warehouse-attributed CAC). Sophisticated attribution requires data volume you do not have.
|
||||
- Mid-stage. Data-driven attribution from Google plus GA4, with explicit awareness vs closing channel labeling.
|
||||
- Mature. MMM as the canonical incremental reference. MTA for in-flight optimization. Last-click for channel-level decisions where ambiguity is acceptable.
|
||||
|
||||
Detail and a decision matrix in [`references/attribution-model-comparison.md`](references/attribution-model-comparison.md).
|
||||
|
||||
---
|
||||
|
||||
## Multi-platform reconciliation
|
||||
|
||||
The trap. Google says you spent $50K with 800 conversions. Meta says $30K with 600. LinkedIn says $20K with 200. Total reported equals 1,600 conversions. Your warehouse says 950. Where did 650 go?
|
||||
|
||||
The answer. Nowhere. They never existed. Each platform claimed conversions other platforms also claimed.
|
||||
|
||||
The reconciliation pattern.
|
||||
|
||||
- Trust the warehouse for total conversions and total revenue.
|
||||
- Trust platforms for relative ranking within platform (which campaign won, which audience won).
|
||||
- Never trust platform sums.
|
||||
- Compute blended CAC as (total ad spend across platforms) divided by (total new customers from warehouse). Not from platform reports.
|
||||
|
||||
The board-deck pattern. Report warehouse-attributed conversion counts, never platform-summed. Report blended CAC, not channel-by-channel CAC unless explicitly noted as platform-self-attributed. Detail and templates in [`references/dashboard-reconciliation-patterns.md`](references/dashboard-reconciliation-patterns.md).
|
||||
|
||||
---
|
||||
|
||||
## ROAS vs LTV: the time horizon trap
|
||||
|
||||
ROAS is short-term. Revenue from purchases attributed to a campaign in a fixed window, often 7 to 30 days. LTV is long-term. Total customer lifetime revenue.
|
||||
|
||||
Decisions made on ROAS can be wrong if LTV varies by channel. A worked example.
|
||||
|
||||
Meta drives 2.5x ROAS at $40 CAC with $80 LTV. The 7-day-click revenue covers 1.5x payback over the customer lifetime.
|
||||
|
||||
Google drives 1.8x ROAS at $60 CAC with $200 LTV. The 7-day-click revenue covers 3.3x payback over the customer lifetime.
|
||||
|
||||
Google looks worse on ROAS, better on LTV-adjusted return. Allocating budget to Meta because the ROAS is higher is the wrong move.
|
||||
|
||||
The fix. Cohort-based LTV by acquisition channel, updated quarterly. Compare channels on payback period or LTV-CAC ratio, not raw ROAS. The 2x ROAS heuristic is a dangerous shortcut. Same ROAS at different LTVs equals different actual returns.
|
||||
|
||||
The trap that compounds. Performance teams optimize for short-term ROAS because the metric refreshes weekly. Brand and high-LTV channels get cut because their short-term ROAS is lower. Six months later, the brand pipeline has eroded and short-term ROAS itself drops because the cheap channels are saturated. The metric that drove the decision was the wrong horizon.
|
||||
|
||||
---
|
||||
|
||||
## Cohort analysis vs daily metrics
|
||||
|
||||
Daily metrics tell you what happened today. Cohort analysis tells you whether today's customers are different from last month's.
|
||||
|
||||
Three cohort cuts that matter for paid media.
|
||||
|
||||
**By acquisition month.** Are users acquired in March retaining better than users acquired in January? A declining LTV over rolling acquisition cohorts means recent acquisition is lower quality; the daily metrics will show this two to three months later when the retention starts hurting.
|
||||
|
||||
**By acquisition channel.** Are users from Meta retaining better than users from Google? Channel-level cohort divergence is the data behind the LTV-vs-ROAS argument. Meta might drive volume at lower LTV; Google might drive lower volume at higher LTV. The cohort tells the story the daily ROAS hides.
|
||||
|
||||
**By acquisition campaign.** Campaign-level cohort signals. Useful for diagnosing why a campaign that "works" in week 1 produces no recurring revenue.
|
||||
|
||||
The signal to act on. Declining cohort LTV over two consecutive months is the alarm. Pause the channel or campaign before the daily metrics force you to. Detail in [`references/cohort-analysis-templates.md`](references/cohort-analysis-templates.md).
|
||||
|
||||
---
|
||||
|
||||
## Statistical noise in performance metrics
|
||||
|
||||
Most "the campaign improved 15% week over week" stories are noise. Real performance changes are 30% or more in metrics that vary 10 to 20% naturally. Below that threshold, you are looking at variance and calling it signal.
|
||||
|
||||
Sources of noise in paid media metrics.
|
||||
|
||||
- **Day-of-week effects.** B2C tends to weekend dips. B2B tends to weekend gains. A "Monday morning is better" hypothesis often dissolves when day-of-week is normalized.
|
||||
- **Holiday and seasonal effects.** Q4 dwarfs most "optimization" effects. A campaign launched in Q4 looks great because of seasonality, not strategy.
|
||||
- **Weather, news, competitor activity.** Real exogenous variance. Last week's news cycle can shift CPMs across an entire vertical.
|
||||
- **Pixel fire and reporting delay.** Conversions reported on a 7-day click window arrive incrementally. Reading the panel on Monday for last week's performance undercounts.
|
||||
|
||||
The fix. Pre-commit to test duration before drawing conclusions. Use the experimentation discipline from `experimentation-analytics` for any directional change you want to claim is real. The signal-to-noise problem in paid media metrics is the same as the signal-to-noise problem in product experiments; the framework transfers.
|
||||
|
||||
This is where `experimentation-analytics` bridges in. The statistical patterns are the same; the application is different. Read both for the full picture.
|
||||
|
||||
---
|
||||
|
||||
## Incrementality testing
|
||||
|
||||
The honest test. If we had not run this ad, would we still have gotten the conversion? The number above zero is the incremental contribution.
|
||||
|
||||
Most paid media is 30 to 70% incremental, not 100%. Some is zero. Branded search bidding is often 5 to 20% incremental (most converters would have found you organically). Retargeting is often 20 to 40% incremental (many of those users were going to convert anyway). Prospecting is often 50 to 90% incremental.
|
||||
|
||||
Four methods.
|
||||
|
||||
**Geo holdout.** Hold one region out from the campaign. Measure the difference in conversions between the holdout region and the matched test region. The cleanest causal test for paid media at scale.
|
||||
|
||||
**Ghost bidding (Google).** Google's own incrementality tool. Bids on a holdout share of impressions but does not actually serve the ad. Reports incremental conversions. Honest signal; some teams find the math opaque.
|
||||
|
||||
**Conversion lift studies (Meta).** Splits audiences into test and control. Test sees the ad; control does not. Reports incremental lift. The cleanest within-Meta test.
|
||||
|
||||
**PSA tests.** Serve some users a public service announcement instead of your ad. Compare conversion rates. Useful for legacy brands with deep budget.
|
||||
|
||||
Incremental rate ranges by channel type are in [`references/incrementality-testing-playbook.md`](references/incrementality-testing-playbook.md). The discipline is to run incrementality tests at least quarterly on the highest-spend channels. Without them, you are optimizing against platform-reported attribution that systematically overcounts.
|
||||
|
||||
---
|
||||
|
||||
## Geo experiments and holdouts
|
||||
|
||||
For paid media specifically, geo-based testing is the most reliable causal method.
|
||||
|
||||
**Geo holdout.** Turn off paid media in one region. Measure baseline organic conversions. The difference between expected and actual conversions in the holdout region is the incremental paid contribution.
|
||||
|
||||
**Geo lift.** Scale spend in one region by 2x. See if conversions scale linearly. A linear scale means the channel has headroom. A sublinear scale means saturation; further spend is diminishing returns.
|
||||
|
||||
**Switchback.** Alternate weeks of campaign on and off. Compare on-weeks to off-weeks. Useful when geo splitting is not feasible.
|
||||
|
||||
**Pre-and-post analysis.** Launch in a region; measure 30 days before vs 30 days after. Weak design because external factors confound the comparison. Use only when no other test is available.
|
||||
|
||||
The right setup. Matched markets (similar demographics, similar baseline conversion rates). Statistical power calculation upfront (how big a difference can the test actually detect). Pre-committed analysis window (so you do not stop early when the data looks good or wait too long when it looks bad).
|
||||
|
||||
The trap. Calling a geo test successful because of timing-correlated revenue lift. A campaign launched in October will see "lift" because Q4 is starting; without a control region, the lift is not attributable to the campaign.
|
||||
|
||||
---
|
||||
|
||||
## Platform self-attribution bias
|
||||
|
||||
A specific failure mode worth its own section.
|
||||
|
||||
The mechanism. Platform's pixel fires on conversion. Platform claims credit. The user might have converted from any channel; the platform that loaded the pixel last gets the credit on the platform's own dashboard.
|
||||
|
||||
Why platforms reward this design. More credit on the platform dashboard equals better-looking ROAS equals more advertiser spend. Platforms have no incentive to underreport their own contribution.
|
||||
|
||||
Detection patterns. When platform-reported conversions exceed warehouse-attributed conversions for the same channel by more than 30%, you have heavy double-counting. When sum-of-platform-reports exceeds total conversions in the warehouse, you have cross-platform double-counting.
|
||||
|
||||
The fix. Warehouse as canonical for board reporting. Platform reporting as in-flight signal only. Incrementality tests at least quarterly to keep the channel-attribution honest.
|
||||
|
||||
A worked example. A retargeting campaign in Meta showed 3.5x ROAS for six months. The team scaled spend from $20K to $80K per month. A geo holdout test revealed that 65% of the "conversions" would have happened anyway from organic. Real ROAS adjusted for incrementality was 1.2x, not 3.5x. The campaign got cut and warehouse-attributed CAC dropped 18% in the next quarter.
|
||||
|
||||
---
|
||||
|
||||
## Common interpretation failures
|
||||
|
||||
Twelve patterns recur in paid media reporting work. Detail in [`references/common-interpretation-failures.md`](references/common-interpretation-failures.md).
|
||||
|
||||
- "ROAS dropped 20% week over week, kill the campaign." Could be noise. Pre-commit a test window before acting on weekly variance.
|
||||
- "Meta says 500 conversions, my warehouse says 200, who is right?" Both are wrong; warehouse is closer to truth, Meta self-attributes. Reconcile, do not pick a winner.
|
||||
- "We turned off Google PMax and conversions did not drop." PMax was harvesting branded search you would have gotten free. Audit branded queries inside PMax.
|
||||
- "The new campaign hit 5x ROAS in week 1." Likely retargeting hot leads. Check the audience composition before declaring victory.
|
||||
- "We A/B tested and one creative wins by 12%." Within margin of platform noise. Not significant.
|
||||
- "Our LTV calculation says this channel is profitable." Check cohort age. Recent cohorts may not have hit LTV yet; the calculation is a projection, not a measurement.
|
||||
- "The platform says high frequency is fine because conversions are still happening." Fatigue masked by free organic conversions. The campaign is taking credit for conversions that would have happened anyway.
|
||||
- "Last-click attribution shows Meta at 60% credit." Last-click bias. First-click view of the same data shows different. Pick a model and stick.
|
||||
- "We scaled spend 5x and conversions only doubled." Saturation. The channel found its ceiling; the marginal CAC at the new spend level is much higher.
|
||||
- "Brand campaigns underperform on direct ROAS." They do not have to. Brand impact shows up in other channels' efficiency. Measure brand against brand-search lift, not direct ROAS.
|
||||
- "ROAS held steady but profit dropped." The mix shifted toward lower-margin products. Channel-level ROAS hides product-mix effects.
|
||||
- "Agency reported a 4x ROAS month." Whose number? Platform-reported, warehouse-attributed, or model-adjusted? The unit of measurement matters more than the magnitude.
|
||||
|
||||
---
|
||||
|
||||
## The framework: 12 considerations for trustworthy paid media interpretation
|
||||
|
||||
When reading a paid media dashboard about to inform a decision, walk these 12 considerations. Skipping any of them is how teams ship the wrong call.
|
||||
|
||||
1. **Result panel completeness.** What is the platform showing vs hiding.
|
||||
2. **Platform-reported vs reality.** View-through, modeled conversions, conversion windows.
|
||||
3. **Attribution model.** Pick one and read the others as sanity checks.
|
||||
4. **Multi-platform reconciliation.** Sum-of-platforms is always inflated.
|
||||
5. **ROAS vs LTV horizon.** Short-term metric, long-term impact.
|
||||
6. **Cohort vs daily.** Cohort tells the quality story; daily tells the volume story.
|
||||
7. **Statistical noise.** Weekly variance, day-of-week, seasonal, exogenous.
|
||||
8. **Incrementality.** What would have happened without the spend.
|
||||
9. **Geo and holdout testing.** The honest causal test.
|
||||
10. **Self-attribution bias.** Platforms claim credit they do not deserve.
|
||||
11. **Decision rule.** Pre-committed scale up, hold, or pull back.
|
||||
12. **Single source of truth.** Warehouse over platform reporting for board metrics.
|
||||
|
||||
The output of the framework is one of three answers. Scale (the campaign is incremental and unit economics work). Hold (data is ambiguous; gather more before deciding). Kill (the campaign is not incremental enough to justify the spend).
|
||||
|
||||
---
|
||||
|
||||
## Reference files
|
||||
|
||||
- [`references/metric-definitions-glossary.md`](references/metric-definitions-glossary.md) - CTR, CPC, CPM, CPA, ROAS, LTV, AOV, frequency, reach, impressions, conversion window, view-through, modeled conversion, blended CAC, MER.
|
||||
- [`references/attribution-model-comparison.md`](references/attribution-model-comparison.md) - Last-click, first-click, linear, time-decay, U-shaped, DDA, MMM. Decision matrix by business stage.
|
||||
- [`references/platform-reporting-quirks.md`](references/platform-reporting-quirks.md) - Google PMax black box, Meta iOS impact and Conversions API, LinkedIn 30-day click defaults, TikTok video-completion attribution, programmatic viewability gates.
|
||||
- [`references/incrementality-testing-playbook.md`](references/incrementality-testing-playbook.md) - Geo holdout, ghost bidding, conversion lift, PSA tests, switchback designs. Setup, duration, analysis pattern, expected incremental rates.
|
||||
- [`references/dashboard-reconciliation-patterns.md`](references/dashboard-reconciliation-patterns.md) - Warehouse as canonical, platform as in-flight signal, blended CAC formula, board-deck patterns, reconciliation cadence.
|
||||
- [`references/cohort-analysis-templates.md`](references/cohort-analysis-templates.md) - By acquisition month, channel, and campaign. Retention curves, when to act on cohort signals.
|
||||
- [`references/common-interpretation-failures.md`](references/common-interpretation-failures.md) - Twelve failure patterns with symptom, root cause, fix, prevention.
|
||||
|
||||
---
|
||||
|
||||
## Closing: the courage to call it incremental zero
|
||||
|
||||
Most paid media spend is not 100% incremental. Some channels are 70% incremental. Some are 30%. Some are zero, paying for conversions you would have gotten anyway.
|
||||
|
||||
The discipline of accepting that channels can be incremental zero, and pulling spend accordingly, is the single highest-impact skill in paid media analytics. Most accounts have at least one campaign that looks profitable in the platform but is incremental zero in the warehouse. Branded paid search at $4 CPC when the same users find you at position one organically. Retargeting at $0.30 CPC for users who already added items to cart. PMax cannibalizing free brand traffic.
|
||||
|
||||
The discipline of finding those campaigns and killing them is the work. The platform will not tell you. The platform's incentive is the opposite. The warehouse, paired with quarterly incrementality tests, is the only honest source.
|
||||
|
||||
When in doubt about whether a campaign is incremental, run a geo holdout. The two-week test is cheaper than a quarter of unincremental spend. The team that does not run incrementality tests is optimizing against numbers that are systematically wrong, and the size of the error is exactly the size of the budget waste.
|
||||
Vendored
+128
@@ -0,0 +1,128 @@
|
||||
# Attribution model comparison
|
||||
|
||||
For each major attribution model: definition, fit, bias direction, and a worked example showing how the same activity gets different attribution.
|
||||
|
||||
The principle. No model is right. They are all approximations. The discipline is to pick one as the primary view, read the others as sanity checks, and report against the warehouse rather than against any single platform's view.
|
||||
|
||||
---
|
||||
|
||||
## The models
|
||||
|
||||
### Last-click
|
||||
|
||||
**Definition.** Full credit to the last clickable touchpoint before conversion.
|
||||
|
||||
**When it fits.** Early-stage measurement where simplicity matters more than precision. Final-stage decisions where the closer matters more than the opener.
|
||||
|
||||
**When it does not fit.** Awareness-channel evaluation. Brands with multi-touch sales cycles. Anything upper-funnel.
|
||||
|
||||
**Bias direction.** Undercredits awareness channels (display, video, top-of-funnel social). Overcredits closing channels (branded search, retargeting).
|
||||
|
||||
### First-click
|
||||
|
||||
**Definition.** Full credit to the first touchpoint in the conversion path.
|
||||
|
||||
**When it fits.** Awareness-channel evaluation. Comparing top-of-funnel sources.
|
||||
|
||||
**When it does not fit.** Closing-channel evaluation. Performance optimization at the bid level.
|
||||
|
||||
**Bias direction.** Mirror image of last-click. Undercredits closing; overcredits opening.
|
||||
|
||||
### Linear
|
||||
|
||||
**Definition.** Equal credit across every touchpoint in the conversion path.
|
||||
|
||||
**When it fits.** Board-deck reporting where avoiding "Google gets 70% so we cut Meta" politics matters more than precision. Defensible-by-default.
|
||||
|
||||
**When it does not fit.** Decisions where the marginal contribution of each channel matters. Linear treats first-click and last-click the same; reality usually does not.
|
||||
|
||||
**Bias direction.** Diffuses credit. Channels that touched the path always get something; channels that drove the conversion do not get more.
|
||||
|
||||
### Time-decay
|
||||
|
||||
**Definition.** More credit to recent touchpoints. Older touchpoints get progressively less.
|
||||
|
||||
**When it fits.** When the intuition is that recent ads are more influential. Reasonable for short-cycle B2C.
|
||||
|
||||
**When it does not fit.** Long sales cycles where the first touchpoint may have been months before the close. Decay underweights the opener.
|
||||
|
||||
**Bias direction.** Skews toward the closer. Slightly less aggressive than last-click.
|
||||
|
||||
### U-shaped (position-based)
|
||||
|
||||
**Definition.** 40% credit to first touch. 40% credit to last touch. 20% distributed across middle touches.
|
||||
|
||||
**When it fits.** When you want to honor both opener and closer roles without flattening to linear. Reasonable default for most B2C.
|
||||
|
||||
**When it does not fit.** Single-touch paths (awards 80% to a single touchpoint, which is over-attributing). Long paths where the middle touchpoints matter as much as the ends.
|
||||
|
||||
**Bias direction.** Balances the last-click and first-click views into one number.
|
||||
|
||||
### Data-driven attribution (DDA, Google)
|
||||
|
||||
**Definition.** Machine-learning model that distributes credit based on observed conversion paths. Compares paths that did and did not convert; assigns credit to touchpoints that correlate with conversion.
|
||||
|
||||
**When it fits.** Mature accounts with sufficient conversion volume (Google requires 600+ conversions per month for DDA). Cross-channel optimization.
|
||||
|
||||
**When it does not fit.** Sub-scale accounts. Accounts that need explainability for regulators or boards. The black-box nature is hard to audit.
|
||||
|
||||
**Bias direction.** Best in class for digital channels where the data is clean. Still suffers from platform self-attribution bias because Google's DDA only sees Google touchpoints.
|
||||
|
||||
### Marketing mix modeling (MMM)
|
||||
|
||||
**Definition.** Regression-based, top-down. Models the relationship between spend across channels and revenue over time. Typically requires 2 to 3 years of data.
|
||||
|
||||
**When it fits.** Mature accounts with cross-channel spend at scale. Brands where offline channels (TV, OOH, podcast) contribute. Anywhere platform self-attribution bias is a real concern.
|
||||
|
||||
**When it does not fit.** Early-stage accounts without enough historical data. Fast-changing channel mixes where the historical data does not represent current reality.
|
||||
|
||||
**Bias direction.** The strongest defense against platform self-attribution because MMM does not rely on platform-reported conversions. Limitations are statistical: confidence intervals are wide; granularity is low (channel-level, not campaign-level).
|
||||
|
||||
---
|
||||
|
||||
## The same path under each model
|
||||
|
||||
A worked example. A B2C SaaS user converts after this path:
|
||||
|
||||
1. Sees a YouTube awareness ad (impression, not click).
|
||||
2. Clicks a Meta retargeting ad three days later.
|
||||
3. Searches for the brand on Google. Clicks a paid branded search ad.
|
||||
4. Returns directly the next day. Converts.
|
||||
|
||||
Attribution by model.
|
||||
|
||||
| Model | YouTube | Meta | Branded Search | Direct |
|
||||
|---|---|---|---|---|
|
||||
| Last-click | 0% | 0% | 0% (depending on direct vs paid) | 100% |
|
||||
| First-click | 0% (impressions excluded) | 100% | 0% | 0% |
|
||||
| Linear | 0% | 33% | 33% | 33% |
|
||||
| Time-decay | 0% | 15% | 35% | 50% |
|
||||
| U-shaped | 0% | 40% | 20% | 40% |
|
||||
| Google DDA | (only sees Google touchpoints) | (only sees Meta touchpoints if Conversions API integration) | varies | varies |
|
||||
| MMM | partial credit (spend in YouTube correlates with conversions) | partial credit | partial credit | (organic, not modeled) |
|
||||
|
||||
The takeaway. Same path. Five different attribution stories. None is right. Each tells you something different.
|
||||
|
||||
---
|
||||
|
||||
## Decision matrix by business stage
|
||||
|
||||
| Stage | Primary model | Secondary check | Why |
|
||||
|---|---|---|---|
|
||||
| Pre-PMF | Last-click + warehouse-attributed CAC | None; insufficient volume for sophisticated models | Sophisticated attribution needs volume you do not have |
|
||||
| Series A or early growth | Last-click + GA4 data-driven | First-click as sanity check on awareness | Volume insufficient for MMM; DDA requires more conversions than most early-stage accounts have |
|
||||
| Mid-stage (10K+ conversions per month) | Google DDA + GA4 path data | Last-click for channel decisions; first-click for awareness | DDA gets reliable here; cross-validate with simple models |
|
||||
| Mature (100K+ conversions per month, 2+ years data) | MMM as canonical | Last-click for in-flight; DDA for cross-channel | MMM is the strongest defense against self-attribution at scale |
|
||||
| Multi-channel including offline | MMM mandatory | DDA for digital | MMM is the only model that captures offline contribution |
|
||||
|
||||
The progression. As volume grows and channel mix expands, the model that fits changes. Locking in last-click forever is fine if the business stays simple; the moment offline or upper-funnel channels matter, the model has to advance.
|
||||
|
||||
---
|
||||
|
||||
## How to communicate which model produced which number
|
||||
|
||||
Three rules for honest reporting.
|
||||
|
||||
1. **Always label the model.** "Meta drove 800 conversions" is unreadable. "Meta drove 800 conversions on last-click attribution with a 7-day-click window" is honest.
|
||||
2. **Report the same number under at least two models when stakes are high.** Board decks should show the conservative view (last-click) and the generous view (linear or DDA). The range tells stakeholders what they are not learning.
|
||||
3. **Reconcile against the warehouse before reporting in dollars.** Dollar figures attached to platform-reported conversions inherit all the platform's attribution biases. Warehouse-attributed dollars are the only dollars that have been independently verified.
|
||||
+113
@@ -0,0 +1,113 @@
|
||||
# Cohort analysis templates
|
||||
|
||||
Three cohort cuts that matter for paid media. By acquisition month, by channel, by campaign. Plus retention curves and when to act.
|
||||
|
||||
The principle. Daily metrics tell you what happened today. Cohort analysis tells you whether today's customers are different from last month's. The difference is the leading indicator that a channel or campaign is degrading; daily metrics catch the same problem two to three months later when it shows up in revenue.
|
||||
|
||||
---
|
||||
|
||||
## Template 1: Cohort by acquisition month
|
||||
|
||||
The standard rolling 12-month view of LTV growth.
|
||||
|
||||
**Setup.** For each acquisition month over the last 12 months, compute the cumulative revenue per customer at month 1, month 3, month 6, and month 12 (where data is available).
|
||||
|
||||
**Output.**
|
||||
|
||||
| Acquisition month | M1 revenue/customer | M3 revenue/customer | M6 revenue/customer | M12 revenue/customer |
|
||||
|---|---|---|---|---|
|
||||
| 2025-05 | $42 | $86 | $128 | $185 |
|
||||
| 2025-06 | $44 | $89 | $135 | $192 |
|
||||
| 2025-07 | $40 | $82 | $122 | $178 |
|
||||
| 2025-08 | $43 | $85 | $130 | (incomplete) |
|
||||
| 2025-09 | $38 | $78 | (incomplete) | (incomplete) |
|
||||
| 2025-10 | $35 | $72 | (incomplete) | (incomplete) |
|
||||
| 2025-11 | $33 | $68 | (incomplete) | (incomplete) |
|
||||
| 2025-12 | $34 | (incomplete) | (incomplete) | (incomplete) |
|
||||
|
||||
**The signal.** The M3 revenue per customer dropped from $86 to $68 over six months. Recent acquisitions are lower-quality customers. The daily metrics will show this as ROAS deterioration in two to three months when the recent cohorts hit their declining LTV plateau.
|
||||
|
||||
**Action.** Investigate which channels or campaigns shifted in the last six months. The drop usually correlates with a specific channel scaling into lower-quality audiences.
|
||||
|
||||
---
|
||||
|
||||
## Template 2: Cohort by acquisition channel
|
||||
|
||||
The channel-level LTV story that ROAS hides.
|
||||
|
||||
**Setup.** For each channel, compute LTV at fixed time windows (30, 60, 90, 180, 365 days post-acquisition). Track the trend over multiple acquisition cohorts.
|
||||
|
||||
**Output (cohort: 2025-Q3 acquisitions, measured at 90 days post-acquisition).**
|
||||
|
||||
| Channel | New customers | CAC | 90-day revenue/customer | 90-day LTV/CAC | Verdict |
|
||||
|---|---|---|---|---|---|
|
||||
| Google brand search | 420 | $45 | $128 | 2.8x | Strong |
|
||||
| Google generic search | 280 | $95 | $112 | 1.2x | Marginal |
|
||||
| Meta prospecting | 540 | $72 | $84 | 1.2x | Marginal |
|
||||
| Meta retargeting | 320 | $48 | $156 | 3.3x | Strong |
|
||||
| LinkedIn Sponsored | 95 | $320 | $580 | 1.8x | Long payback; B2B-typical |
|
||||
| TikTok In-Feed | 180 | $58 | $61 | 1.1x | Marginal |
|
||||
| Direct (organic) | 1,200 | n/a | $145 | n/a | Reference baseline |
|
||||
|
||||
**The signal.** Meta retargeting and Google brand search are the strong performers on LTV-CAC. Meta prospecting and TikTok In-Feed are marginal; the customer quality is lower than the platform-reported ROAS suggests.
|
||||
|
||||
**Action.** The marginal channels need either CAC reduction or audience-quality improvement. Pulling back on the marginal channels and reallocating to the strong ones improves blended LTV-CAC.
|
||||
|
||||
---
|
||||
|
||||
## Template 3: Cohort by acquisition campaign
|
||||
|
||||
Campaign-level cohort signals. Use sparingly; sample sizes get small fast.
|
||||
|
||||
**Setup.** For each campaign with sufficient acquisition volume (typically 100+ customers per cohort), compute LTV at 30 and 60 days. Compare against the channel average.
|
||||
|
||||
**Output.**
|
||||
|
||||
| Campaign | New customers | CAC | 60-day revenue/customer | vs channel average |
|
||||
|---|---|---|---|---|
|
||||
| Meta-Lookalike-1pct | 320 | $58 | $112 | +30% |
|
||||
| Meta-Lookalike-5pct | 180 | $48 | $74 | -15% |
|
||||
| Meta-Interest-SaaS | 90 | $72 | $86 | -5% |
|
||||
| Meta-Retargeting-30day | 240 | $42 | $148 | +60% |
|
||||
|
||||
**The signal.** The 5% lookalike is finding lower-quality customers than the 1% lookalike, even at lower CAC. The ROAS view favors the 5% lookalike (lower CAC, decent revenue); the cohort view shows the customer quality dropped.
|
||||
|
||||
**Action.** Pull back the 5% lookalike. Concentrate spend on the 1% lookalike and the retargeting segments. Watch for next-cohort confirmation before a permanent reallocation.
|
||||
|
||||
---
|
||||
|
||||
## Retention curves
|
||||
|
||||
A retention curve plots customer activity over time. Three patterns to recognize.
|
||||
|
||||
**Plateau curve.** Activity drops in the first 30 days, then stabilizes at a level it sustains long-term. The plateau height is the long-run user value. Healthy SaaS, subscription consumer, marketplace.
|
||||
|
||||
**Smile curve.** Activity drops, plateaus, then trends upward (resurrection effect). Less common; characteristic of products with seasonal or lifecycle re-engagement.
|
||||
|
||||
**Decay curve.** Activity drops continuously without stabilizing. The product is not retaining; the unit economics will not work no matter what CAC the channel produces. Common in low-engagement consumer apps.
|
||||
|
||||
**The curve to watch by acquisition channel.** A channel whose retention curve plateaus higher than another is delivering higher-LTV customers, regardless of the CAC ratio. This is the data behind LTV-CAC channel comparisons.
|
||||
|
||||
---
|
||||
|
||||
## When to act on cohort signals
|
||||
|
||||
Three triggers.
|
||||
|
||||
1. **Two consecutive months of LTV decline at the same time horizon.** A single month is noise; two is signal. Investigate which channels shifted.
|
||||
2. **Channel-level LTV-CAC ratio falls below 2x for two consecutive cohorts.** Pause or reallocate the channel. The 2x threshold accounts for gross margin, payback period, and the variance in LTV measurement.
|
||||
3. **A campaign-level cohort underperforms the channel average by 20%+ for two consecutive cohorts.** The campaign is bringing in lower-quality audiences than the rest of the channel. Pause or reallocate.
|
||||
|
||||
The discipline. Watch cohort signals on a monthly cadence. Most teams over-index on weekly platform metrics and under-index on cohort signals; the cohort-watchers see the problems first.
|
||||
|
||||
---
|
||||
|
||||
## Common cohort mistakes
|
||||
|
||||
**Reading recent cohorts as final.** A 30-day cohort's "LTV" is actually 30-day revenue, not LTV. Naming matters. If the team treats 30-day revenue as LTV in spreadsheets, they will undercount channels with longer payback periods.
|
||||
|
||||
**Comparing cohorts at different ages.** A January cohort measured at 12 months vs a November cohort measured at 2 months is comparing different things. Always compare at matched ages.
|
||||
|
||||
**Ignoring seasonal cohorts.** Q4 cohorts often have higher first-purchase value but lower retention because Q4 acquisition includes one-time gifters. Account for the seasonal pattern; do not over-index on Q4 cohort numbers.
|
||||
|
||||
**Not segmenting by channel.** Aggregate LTV trends hide channel-level shifts. The channel-segmented cohort is where the action signal lives.
|
||||
Vendored
+155
@@ -0,0 +1,155 @@
|
||||
# Common interpretation failures
|
||||
|
||||
Twelve failure patterns that recur in paid media reporting work. For each: name, symptom, root cause, fix, prevention.
|
||||
|
||||
---
|
||||
|
||||
## 1. ROAS dropped 20% week-over-week, kill the campaign
|
||||
|
||||
**Symptom.** Weekly ROAS chart shows a drop. Team wants to pause the campaign.
|
||||
|
||||
**Root cause.** Could be noise. Day-of-week, holiday timing, conversion-window lag, exogenous variance. A 20% drop in a metric that varies 10 to 15% naturally is below the signal threshold.
|
||||
|
||||
**Fix.** Pre-commit a test window before acting on weekly variance. For most campaigns, two consecutive weeks of decline below the threshold is the signal. Single-week swings are usually noise.
|
||||
|
||||
**Prevention.** Establish baseline variance for each campaign before declaring "improvement" or "decline." Without the baseline, every weekly chart looks alarming.
|
||||
|
||||
---
|
||||
|
||||
## 2. Meta says 500 conversions, my warehouse says 200, who is right
|
||||
|
||||
**Symptom.** Platform-reported numbers do not match warehouse numbers. The team picks the more flattering one.
|
||||
|
||||
**Root cause.** Both are wrong; warehouse is closer to truth. Meta self-attributes (claims credit for conversions other channels also touched). View-through and modeled conversions inflate Meta's count.
|
||||
|
||||
**Fix.** Reconcile, do not pick a winner. Report the warehouse number as canonical for board metrics. Use Meta's number only for in-flight optimization within Meta.
|
||||
|
||||
**Prevention.** Make the reconciliation cadence explicit. Weekly check, monthly deep dive, quarterly attribution review. The team that runs the reconciliation never has to "pick a winner."
|
||||
|
||||
---
|
||||
|
||||
## 3. Turned off Google PMax, conversions did not drop
|
||||
|
||||
**Symptom.** Paused PMax. Total account conversions held steady.
|
||||
|
||||
**Root cause.** PMax was harvesting branded search conversions you would have gotten free from organic. The platform was claiming credit for traffic that was not incremental.
|
||||
|
||||
**Fix.** Audit branded queries inside PMax. Add account-level negative keywords for branded queries. Restart PMax with branded excluded; the incremental contribution from non-branded inventory is the real value.
|
||||
|
||||
**Prevention.** At PMax setup, exclude branded queries from the start. Audit PMax's spend distribution monthly to catch the cannibalization pattern early.
|
||||
|
||||
---
|
||||
|
||||
## 4. New campaign hit 5x ROAS in week 1
|
||||
|
||||
**Symptom.** A fresh campaign's first-week ROAS is 5x. Team wants to scale immediately.
|
||||
|
||||
**Root cause.** Likely retargeting hot leads or running on a small audience of warm prospects who would have converted anyway. The first week is unrepresentative.
|
||||
|
||||
**Fix.** Check the audience composition. If retargeting or warm-list, the 5x is not the steady-state. Wait two to four weeks before scaling.
|
||||
|
||||
**Prevention.** Define the success metric and the test window before launch. Do not let a strong first week change the plan; pre-commit to the four-week measurement.
|
||||
|
||||
---
|
||||
|
||||
## 5. A/B tested and one creative wins by 12%
|
||||
|
||||
**Symptom.** Two creatives tested. One wins by 12%. Team wants to ship the winner.
|
||||
|
||||
**Root cause.** 12% is within margin of platform noise for a typical creative test. Variants compete with each other inside the platform's optimization; the platform's own decisions confound the test.
|
||||
|
||||
**Fix.** Re-run the test with more volume, or accept that the difference is within noise and pick based on production cost or refresh ease.
|
||||
|
||||
**Prevention.** Set the minimum detectable effect (MDE) before testing. A 12% threshold requires a specific volume; if you cannot reach it, the test cannot detect that effect cleanly.
|
||||
|
||||
---
|
||||
|
||||
## 6. LTV calculation says this channel is profitable
|
||||
|
||||
**Symptom.** A team's LTV-CAC analysis shows a channel as profitable. Spend is increased.
|
||||
|
||||
**Root cause.** The "LTV" in the calculation may be a 60-day cumulative revenue projected forward, not actual lifetime value. Recent cohorts have not aged enough to confirm the LTV.
|
||||
|
||||
**Fix.** Confirm the cohort age. If projecting forward, document the assumption and stress-test (what happens if actual LTV is 80% of projected).
|
||||
|
||||
**Prevention.** Always pair LTV calculations with cohort age. A 30-day cohort has 30-day revenue, not LTV. Naming clearly prevents the substitution error.
|
||||
|
||||
---
|
||||
|
||||
## 7. High frequency is fine because conversions are still happening
|
||||
|
||||
**Symptom.** Frequency at 6 to 8 per week. Conversions on the platform are stable. Team concludes fatigue is not an issue.
|
||||
|
||||
**Root cause.** Fatigue masked by conversions that would have happened anyway from organic, retargeting overlap, or recurring customers. The platform is taking credit for traffic the high frequency did not actually drive.
|
||||
|
||||
**Fix.** Run an incrementality test on the high-frequency campaign. The likely finding is that incremental rate dropped substantially even as raw conversions held.
|
||||
|
||||
**Prevention.** Watch frequency as a leading indicator. Above 4 to 5 per week is the alarm regardless of conversion levels. Refresh creative.
|
||||
|
||||
---
|
||||
|
||||
## 8. Last-click attribution shows Meta at 60% credit
|
||||
|
||||
**Symptom.** Last-click view of paid media shows Meta dominant. Team allocates budget accordingly.
|
||||
|
||||
**Root cause.** Last-click bias. Meta may also be the closer because users who searched for the brand on Google clicked through, then later saw a Meta retargeting ad and converted. Last-click credits Meta; the conversion would have happened anyway.
|
||||
|
||||
**Fix.** Read the same data under first-click and a multi-touch model. The picture changes. Allocate based on a balanced view, not the last-click view alone.
|
||||
|
||||
**Prevention.** Always compare attribution under at least two models for budget decisions. The single-model view is reliable for in-flight only.
|
||||
|
||||
---
|
||||
|
||||
## 9. Scaled spend 5x, conversions only doubled
|
||||
|
||||
**Symptom.** Budget went from $20K to $100K per month. Conversions went from 800 to 1,600.
|
||||
|
||||
**Root cause.** Saturation. The channel found its ceiling; the marginal CAC at the new spend level is much higher than the average CAC the team was reporting.
|
||||
|
||||
**Fix.** Calculate the marginal CAC, not just average CAC. The marginal CAC at the higher spend tier tells you whether more spend will produce more conversions or just spend more for the same conversions.
|
||||
|
||||
**Prevention.** Project the saturation curve before scaling. If a 1.5x spend increase produced a 1.2x conversion increase, expect the next 1.5x to produce 1.0x or less.
|
||||
|
||||
---
|
||||
|
||||
## 10. Brand campaigns underperform on direct ROAS
|
||||
|
||||
**Symptom.** A brand campaign reports 0.8x ROAS. Team wants to cut it.
|
||||
|
||||
**Root cause.** Brand campaigns affect downstream channel efficiency, not direct conversion. The direct ROAS is the wrong measurement for brand impact.
|
||||
|
||||
**Fix.** Measure brand against brand-search lift, organic traffic growth, or direct-traffic growth. The brand campaign's effect shows up in cheaper performance acquisition over the next 60 to 90 days.
|
||||
|
||||
**Prevention.** At brand campaign setup, define the success metric explicitly (brand search lift target, organic traffic target, awareness lift). Do not let direct ROAS become the unintended grading metric.
|
||||
|
||||
---
|
||||
|
||||
## 11. ROAS held steady but profit dropped
|
||||
|
||||
**Symptom.** Channel-level ROAS at 3x, stable. Profit on the same channel dropped 20% over the quarter.
|
||||
|
||||
**Root cause.** The mix shifted toward lower-margin products. ROAS is a revenue metric; it does not see margin. The channel attracted bargain hunters at lower margin, holding ROAS but cutting profit.
|
||||
|
||||
**Fix.** Track contribution-margin ROAS, not gross-revenue ROAS. The contribution-margin view catches the mix shift the gross view hides.
|
||||
|
||||
**Prevention.** Build margin-aware reporting from the start. Most teams default to gross revenue; the move to contribution margin pays for itself within a quarter.
|
||||
|
||||
---
|
||||
|
||||
## 12. Agency reported a 4x ROAS month
|
||||
|
||||
**Symptom.** External agency claims a 4x ROAS for the month. Team accepts the number.
|
||||
|
||||
**Root cause.** Whose number? Platform-reported, warehouse-attributed, or model-adjusted? Agencies often report the most generous number (their incentive). Without specifying the attribution methodology, the 4x ROAS is unreadable.
|
||||
|
||||
**Fix.** Demand the attribution methodology in every agency report. Reconcile against the warehouse before presenting to leadership.
|
||||
|
||||
**Prevention.** Build attribution-methodology specification into the agency contract. Reports must include the model, the window, and the source of conversion data. The contract that does not specify produces reports that cannot be evaluated.
|
||||
|
||||
---
|
||||
|
||||
## The pattern across all twelve
|
||||
|
||||
Most paid media interpretation failures share one root cause: optimizing one number without checking what the optimization did to the system. Scale ROAS at the cost of LTV. Pause an underperformer at the cost of total volume. Trust platform-reported attribution at the cost of incremental truth.
|
||||
|
||||
The fix at the meta level. Decide on the success metric (warehouse-attributed CAC, LTV-CAC ratio, contribution-margin ROAS) and the guardrails (volume, frequency, customer-cohort quality, brand metrics) before reading any dashboard. Pull back the moment a guardrail breaks, even if the success metric still looks fine. The dashboard is a tool, not the truth; the warehouse plus quarterly incrementality testing is closer to truth.
|
||||
Vendored
+114
@@ -0,0 +1,114 @@
|
||||
# Dashboard reconciliation patterns
|
||||
|
||||
The single-source-of-truth pattern for paid media reporting. Warehouse as canonical; platforms as in-flight signals.
|
||||
|
||||
The principle. Sum-of-platform-reports is always greater than reality because every platform claims credit for conversions other platforms also touched. Reporting platform-summed numbers as fact in board decks is the most expensive error in paid media analytics.
|
||||
|
||||
---
|
||||
|
||||
## The three-layer reporting model
|
||||
|
||||
**Layer 1: platform metrics.** Use for in-flight optimization only. Ad-set-level CAC, creative-level CTR, audience-level frequency. The platform's view of its own performance is fine for optimizing the platform's own levers.
|
||||
|
||||
**Layer 2: warehouse multi-touch attribution.** Use for cross-platform comparison and channel-level decisions. Each conversion gets attributed across all platforms that touched the path. Pick one model (last-click, first-click, linear, U-shaped, DDA) and standardize across the team.
|
||||
|
||||
**Layer 3: marketing-mix modeling (MMM) at scale.** Use for budget allocation across channels. MMM treats spend as input and revenue as output; it does not rely on platform-reported attribution at all. The strongest defense against platform self-attribution bias.
|
||||
|
||||
The cadence. Layer 1 in real time. Layer 2 weekly. Layer 3 quarterly.
|
||||
|
||||
---
|
||||
|
||||
## Blended CAC
|
||||
|
||||
The board-deck number. Resistant to attribution debates because it does not require choosing an attribution model.
|
||||
|
||||
**Formula.**
|
||||
|
||||
```
|
||||
Blended CAC = (total ad spend across platforms) / (total new customers from warehouse)
|
||||
```
|
||||
|
||||
**Worked example.**
|
||||
|
||||
In Q4, the team spent $200K total: $80K on Google Ads, $70K on Meta, $30K on LinkedIn, $20K on TikTok. The warehouse shows 1,250 new customers in Q4 from all sources (paid, organic, direct, referral).
|
||||
|
||||
But the team needs to attribute the new customers to paid specifically. Two ways to do this:
|
||||
|
||||
1. **Approximate.** Assume the proportion of paid-attributed customers in the warehouse roughly equals the proportion that paid contributed to traffic. If 60% of traffic in Q4 was paid-attributed, then 60% of 1,250 equals 750 paid-acquired customers. Blended paid CAC: $200K / 750 = $267.
|
||||
2. **Precise.** Use the warehouse's multi-touch attribution to credit paid channels with a fraction of each conversion. Sum the paid-attributed share across all conversions; that becomes the denominator.
|
||||
|
||||
The precise version is better when available. The approximate version works when the warehouse data is incomplete. Both produce a number that does not double-count across platforms.
|
||||
|
||||
---
|
||||
|
||||
## The board-deck pattern
|
||||
|
||||
Three rules for reporting paid media numbers to leadership.
|
||||
|
||||
1. **Lead with blended CAC, not channel CAC.** Channel CAC depends on attribution model; blended CAC does not. Stakeholders not in the weeds on attribution find blended CAC easier to compare across quarters.
|
||||
2. **Show the range.** Report the conservative view (last-click) and the generous view (linear or DDA) for any high-stakes channel decision. The range tells stakeholders what they are not learning.
|
||||
3. **Always label the source.** "Meta drove 800 conversions" is unreadable. "Meta drove 800 conversions per Meta's 7-day-click attribution; warehouse-attributed: 540" is honest.
|
||||
|
||||
A worked example board slide.
|
||||
|
||||
```
|
||||
Q4 paid media performance
|
||||
|
||||
Total spend: $200K (vs $185K Q3, +8%)
|
||||
New customers from paid (warehouse-attributed): 750 (vs 680 Q3, +10%)
|
||||
Blended paid CAC: $267 (vs $272 Q3, -2%)
|
||||
|
||||
Channel CAC (warehouse-attributed, last-click):
|
||||
Google: $240 (40% of new customers)
|
||||
Meta: $290 (35% of new customers)
|
||||
LinkedIn: $480 (15% of new customers)
|
||||
TikTok: $180 (10% of new customers)
|
||||
|
||||
Platform-reported CAC (for in-flight context, not board decision):
|
||||
Google: $190 (Google reports 26% more attributed conversions than warehouse)
|
||||
Meta: $210 (Meta reports 38% more)
|
||||
LinkedIn: $475 (roughly aligned)
|
||||
TikTok: $135 (TikTok reports 33% more)
|
||||
|
||||
Quarterly incrementality test result (geo holdout, October):
|
||||
Brand search: 12% incremental (95% CI: 6-18%). Reduced spend 30%; CAC dropped.
|
||||
Meta retargeting: 31% incremental (95% CI: 22-40%). Maintained spend; CAC view adjusted.
|
||||
```
|
||||
|
||||
The slide tells the truth: the warehouse number is the canonical CAC, the platform numbers are inflated, the incrementality test confirms which channels are real.
|
||||
|
||||
---
|
||||
|
||||
## Reconciliation cadence
|
||||
|
||||
**Weekly.** Pull platform-reported numbers and warehouse numbers. Confirm the sum-of-platforms vs warehouse ratio is in the expected range. A sudden divergence means a tracking break, an attribution-model change, or a platform reporting bug. Investigate.
|
||||
|
||||
**Monthly.** Deeper reconciliation. Compare channel-level attribution across last-click, first-click, and the team's chosen model. Identify channels whose ranking changes by model.
|
||||
|
||||
**Quarterly.** Run an incrementality test on the highest-spend channel. Update the channel-level CAC adjustment factor based on the test result.
|
||||
|
||||
---
|
||||
|
||||
## Common reconciliation mistakes
|
||||
|
||||
**Reporting platform-summed conversions to the board.** The most common error. The board sees "1,600 conversions across paid channels" when the warehouse says 950. The team gets caught when someone divides revenue by 1,600 and gets a CAC that does not match the P&L.
|
||||
|
||||
**Comparing platforms on platform-reported CAC.** Each platform's CAC is computed against a different attribution window and a different set of self-attribution biases. Compare on warehouse-attributed CAC instead.
|
||||
|
||||
**Treating "lift" as incrementality without a controlled test.** A campaign that ran during a period of overall conversion growth gets credit for "lift" that was actually seasonality or organic momentum. Lift requires a control group; otherwise it is correlation reported as causation.
|
||||
|
||||
**Updating attribution models mid-quarter.** Switching from last-click to DDA mid-quarter makes the quarter's data uninterpretable. Pick a model for the quarter; switch only at quarter boundaries with a documented changelog.
|
||||
|
||||
**Reporting blended CAC without naming the time window.** "$267 blended CAC" depends on whether you measured over 30, 60, or 90 days. Pin the window.
|
||||
|
||||
---
|
||||
|
||||
## When the platforms agree more than usual
|
||||
|
||||
A useful diagnostic. If platform-reported sums match warehouse total within 10%, something has changed. Possibilities:
|
||||
|
||||
- The team set up Conversions API on Meta or server-side tagging on Google, which improved tracking precision.
|
||||
- The mix shifted toward branded search, where attribution overlap is lower.
|
||||
- One platform's conversion volume dropped significantly (saturation, fatigue, or campaign issue).
|
||||
|
||||
Investigate any sudden alignment. The platforms diverging is the normal state; alignment usually has a cause worth understanding.
|
||||
Vendored
+139
@@ -0,0 +1,139 @@
|
||||
# Incrementality testing playbook
|
||||
|
||||
The honest test in paid media analytics. If we had not run this ad, would we still have gotten the conversion? The answer above zero is the incremental contribution.
|
||||
|
||||
The principle. Most paid media is not 100% incremental. Branded search bidding is often 5 to 20% incremental. Retargeting is often 20 to 40% incremental. Prospecting is often 50 to 90% incremental. The number that matters for spend decisions is the incremental rate, not the platform-reported attribution rate.
|
||||
|
||||
---
|
||||
|
||||
## Method 1: Geo holdout
|
||||
|
||||
The cleanest causal test for paid media at scale.
|
||||
|
||||
**Setup.** Pick two regions with similar baseline conversion rates and demographic profiles (matched markets). Run the campaign in one region (test); turn it off in the other (holdout).
|
||||
|
||||
**Duration.** Two to four weeks minimum. Statistical power calculation upfront determines the right length given the spend scale and expected lift.
|
||||
|
||||
**Analysis.** Compare conversions in test vs holdout, normalized by population. The difference is the incremental contribution.
|
||||
|
||||
**Expected incremental rate ranges.**
|
||||
|
||||
| Channel | Typical incremental rate |
|
||||
|---|---|
|
||||
| Branded search | 5 to 20% |
|
||||
| Retargeting | 20 to 40% |
|
||||
| Lookalike audiences | 40 to 70% |
|
||||
| Cold prospecting | 50 to 90% |
|
||||
| Awareness video | 30 to 60% |
|
||||
|
||||
**Common pitfalls.**
|
||||
|
||||
- Picking holdout regions with confounding factors (different competitive presence, weather event, retail launch). Confounded results are worse than no test.
|
||||
- Stopping the test early when the data looks good. Pre-commit the duration and stick to it.
|
||||
- Holding out for too long. A 6-week holdout in a small region is expensive in lost conversions; 2 to 4 weeks is usually enough at scale.
|
||||
|
||||
---
|
||||
|
||||
## Method 2: Ghost bidding (Google)
|
||||
|
||||
Google's own incrementality tool. The platform bids on a holdout share of impressions but does not actually serve the ad. The reported delta between served and ghost is incremental.
|
||||
|
||||
**Setup.** Configure within Google Ads. Choose the campaigns and the holdout share (typically 5 to 20%).
|
||||
|
||||
**Duration.** Two to four weeks.
|
||||
|
||||
**Analysis.** Google reports incremental conversions directly. Cross-validate against your own warehouse measurement.
|
||||
|
||||
**Pitfalls.**
|
||||
|
||||
- The math is opaque to many teams. The output is a single incremental number; the underlying methodology is Google's. Trust but verify with a manual geo test on the same campaign.
|
||||
- Only available within Google Ads, not cross-channel.
|
||||
|
||||
---
|
||||
|
||||
## Method 3: Conversion lift studies (Meta)
|
||||
|
||||
Meta's incrementality tool. Splits audiences into test (sees the ad) and control (does not). Measures lift.
|
||||
|
||||
**Setup.** Configure within Meta Ads Manager. Specify the campaign and the test-control split.
|
||||
|
||||
**Duration.** Three to four weeks. Meta requires a minimum spend per study.
|
||||
|
||||
**Analysis.** Meta reports incremental lift. The reporting includes statistical significance bands.
|
||||
|
||||
**Pitfalls.**
|
||||
|
||||
- The minimum spend requirement makes it expensive for small accounts.
|
||||
- Only available within Meta, not cross-channel.
|
||||
- Meta's interpretation tilts toward generous (their incentive). Cross-validate with geo holdout when possible.
|
||||
|
||||
---
|
||||
|
||||
## Method 4: PSA tests
|
||||
|
||||
Serve some users a public service announcement instead of your ad. Compare conversion rates.
|
||||
|
||||
**Setup.** Run two parallel campaigns: one with your ad, one with a PSA (typically a charity or public-interest message). Match audiences.
|
||||
|
||||
**Duration.** Three to six weeks.
|
||||
|
||||
**Analysis.** Compare conversion rate of the PSA-exposed audience against the ad-exposed audience. The difference is incremental.
|
||||
|
||||
**Pitfalls.**
|
||||
|
||||
- Ethically and brand-wise, choose PSAs that align with brand values.
|
||||
- Setup overhead is high. Reserved for legacy brands with deep budgets and serious incrementality questions.
|
||||
|
||||
---
|
||||
|
||||
## Method 5: Switchback designs
|
||||
|
||||
Alternate weeks of campaign on and off. Compare on-weeks to off-weeks.
|
||||
|
||||
**Setup.** Run for at least 8 weeks. Alternate weekly: on, off, on, off. Or alternate by audience segment.
|
||||
|
||||
**Duration.** Eight to twelve weeks. Shorter switchbacks have low statistical power.
|
||||
|
||||
**Analysis.** Difference in conversions between on-weeks and off-weeks, normalized for week-of-year and external variance.
|
||||
|
||||
**Pitfalls.**
|
||||
|
||||
- Confounded by exogenous factors (news, competitor activity, seasonality). Best for steady-state campaigns where the external context is stable.
|
||||
- Audience contamination: users who saw the ad in week 1 may convert in week 2 even when the campaign is off. The contamination dilutes the measured incremental rate.
|
||||
|
||||
---
|
||||
|
||||
## Choosing the right method
|
||||
|
||||
| Constraint | Recommended method |
|
||||
|---|---|
|
||||
| Single platform, want quick answer | Platform-native (ghost bidding for Google, conversion lift for Meta) |
|
||||
| Cross-platform incremental test | Geo holdout |
|
||||
| Small account, limited budget | Geo holdout in two small matched markets |
|
||||
| Long campaign cycle, steady-state | Switchback |
|
||||
| Brand or awareness channel | PSA test or geo holdout |
|
||||
| Regulated industry, ethics concern | Geo holdout (no PSA) |
|
||||
|
||||
The default. Geo holdout. It is the most honest causal test, works cross-channel, and produces results that are interpretable without trusting the platform's methodology.
|
||||
|
||||
---
|
||||
|
||||
## How to run a geo holdout step by step
|
||||
|
||||
1. **Pick matched markets.** Use designated market areas (DMAs) or postal-code-level regions with similar baseline conversion rates and demographic profiles. Aim for at least three test and three holdout regions for statistical power.
|
||||
2. **Calculate statistical power.** Given the expected lift and the regional conversion volume, can the test detect the effect? If the regions are too small, the test is underpowered and inconclusive results are likely.
|
||||
3. **Pre-commit the analysis window.** Define the start date and end date before the test begins. Do not adjust based on early results.
|
||||
4. **Run the test.** Campaign on in test regions; off in holdout. No mid-test changes.
|
||||
5. **Wait for the full window.** Analyzing early produces noise.
|
||||
6. **Compute the delta.** Conversions in test minus conversions in holdout, normalized by population. The delta divided by spend is the incremental CPA. Compare against the platform-reported CPA; the gap is the over-attribution.
|
||||
7. **Report incremental contribution.** Do not report platform-reported CAC alongside warehouse CAC and incremental CAC without labeling. The unit of measurement matters as much as the number.
|
||||
|
||||
---
|
||||
|
||||
## Cadence
|
||||
|
||||
For accounts spending $25K+ per month, run incrementality tests at least quarterly on the highest-spend channels. The cost of the test is small relative to the cost of running un-incremental spend at scale.
|
||||
|
||||
For accounts under $25K per month, annual or semi-annual tests are typically enough. The test cost vs the spend savings does not pencil out as often.
|
||||
|
||||
The discipline. Schedule the tests. Do not wait for a "we should test this" moment; the moment never comes voluntarily.
|
||||
+83
@@ -0,0 +1,83 @@
|
||||
# Metric definitions glossary
|
||||
|
||||
The paid media metrics that show up on every dashboard, with explicit definitions, formulas, and the common pitfalls in usage.
|
||||
|
||||
The point of an explicit glossary. Two teams using the same metric name often compute different numbers. "Conversion rate" might mean clicks-to-conversion or impressions-to-conversion or unique-users-to-conversion. The team that does not pin definitions ends up arguing about numbers that are not the same number.
|
||||
|
||||
---
|
||||
|
||||
## Volume metrics
|
||||
|
||||
**Impressions.** Count of times an ad was displayed. Includes the same user seeing the ad multiple times.
|
||||
|
||||
**Reach.** Count of unique users who saw the ad. Always less than or equal to impressions.
|
||||
|
||||
**Frequency.** Impressions divided by reach. The average number of times a unique user saw the ad. Above 4 to 5 per week is the fatigue alarm.
|
||||
|
||||
**Clicks.** Count of clicks on the ad. Some platforms count "outbound clicks" (which leave the platform) separately from "all clicks" (which include in-platform interactions like saves and shares). Use outbound for direct response.
|
||||
|
||||
---
|
||||
|
||||
## Cost metrics
|
||||
|
||||
**CPC (cost per click).** Spend divided by clicks. Formula: `spend / clicks`. The cost of one click; not the cost of one conversion. Conflating them is the most common reporting error.
|
||||
|
||||
**CPM (cost per thousand impressions).** Spend divided by (impressions / 1000). Formula: `spend / (impressions / 1000)`. The cost of reach. Useful for comparing platforms on awareness efficiency.
|
||||
|
||||
**CPA (cost per acquisition).** Spend divided by conversions. Formula: `spend / conversions`. The variant where "conversion" is defined matters; the same campaign reports different CPAs depending on whether the conversion is a click, a lead form submission, a purchase, or a paid customer.
|
||||
|
||||
**ROAS (return on ad spend).** Revenue from ad-attributed conversions divided by spend. Formula: `attributed revenue / spend`. NOT profit-divided-by-spend. ROAS is a revenue metric, not a profit metric. A 3x ROAS at 30% margin is a 0.9x return on cost; the ROAS reading on its own is misleading.
|
||||
|
||||
**MER (marketing efficiency ratio).** Total revenue divided by total marketing spend, across all channels. Formula: `total revenue / total marketing spend`. The most honest top-line number; resistant to per-channel attribution debates.
|
||||
|
||||
**Blended CAC.** Total ad spend divided by total new customers from warehouse. Formula: `total ad spend / new customers from warehouse`. The board-deck number. Channel-level CAC depends on attribution; blended CAC does not.
|
||||
|
||||
---
|
||||
|
||||
## Conversion metrics
|
||||
|
||||
**Conversion.** The event the campaign optimizes for. Definition varies. Always document: which event, what window, which attribution model. Without these three, "conversions = 800" is unreadable.
|
||||
|
||||
**Conversion rate.** Conversions divided by something. The denominator changes the meaning. Click-through conversion rate (`conversions / clicks`) is different from impression conversion rate (`conversions / impressions`) which is different from unique-user conversion rate (`conversions / reach`). Pin the denominator at every report.
|
||||
|
||||
**Conversion window.** The maximum time between the ad event (click or view) and the conversion for which the platform takes credit. Meta default: 7-day click plus 1-day view. Google default: 30-day click plus 1-day view. Different windows mean different reported counts from the same activity.
|
||||
|
||||
**View-through conversion.** A conversion attributed to an ad the user saw but did not click. Counted by Meta and Google. Often half the platform-reported conversions are view-through. Treat as a soft signal of awareness contribution, not as direct response measurement.
|
||||
|
||||
**Modeled conversion.** A statistically estimated conversion when actual tracking is blocked (most commonly iOS users on Meta after ATT). The platform models what the conversion would have been based on aggregated data. Modeled is an estimate, not a measurement; precision is low.
|
||||
|
||||
---
|
||||
|
||||
## Customer-value metrics
|
||||
|
||||
**LTV (lifetime value).** Total revenue from a customer over their relationship with the brand. Many definitions; the right one for paid media analytics is gross revenue or contribution margin, not unit count. Pair with CAC for the LTV:CAC ratio.
|
||||
|
||||
**LTV:CAC ratio.** LTV divided by CAC. Formula: `LTV / CAC`. The unit-economics test. 3:1 is the venture-capital benchmark; the right number for any specific business depends on payback period and gross margin.
|
||||
|
||||
**Payback period.** Months until cumulative revenue from a customer equals the CAC to acquire them. The cash-flow companion to LTV:CAC. Investors care about payback; operators care about both.
|
||||
|
||||
**AOV (average order value).** Revenue divided by order count. Formula: `revenue / orders`. Useful for e-commerce; less for subscription. The number that turns "increased conversion rate" into "increased revenue."
|
||||
|
||||
---
|
||||
|
||||
## Engagement metrics (less direct)
|
||||
|
||||
**CTR (click-through rate).** Clicks divided by impressions. Formula: `clicks / impressions`. Useful for hook quality. Less useful for conversion quality; high CTR with low conversion rate means the hook is too aggressive for the offer.
|
||||
|
||||
**Hide ratio (negative feedback).** Count of users who explicitly hid or marked the ad as not-interested, divided by impressions. Above 1.5% is the alarm; the platform algorithm will throttle delivery to that audience.
|
||||
|
||||
**Engagement rate.** Likes plus comments plus shares plus saves divided by impressions. Useful for organic-style content; less directly tied to performance for paid.
|
||||
|
||||
---
|
||||
|
||||
## Common pitfalls
|
||||
|
||||
**Treating ROAS as profit.** ROAS is revenue-divided-by-spend. Profit-divided-by-spend is "return on ad investment" or "ROI." Confusing the two leads to greenlit campaigns that lose money on every conversion.
|
||||
|
||||
**Ignoring conversion window in cross-platform comparisons.** Meta's 7-day-click count is not comparable to Google's 30-day-click count without normalization.
|
||||
|
||||
**Treating frequency as a vanity number.** Frequency above 4 to 5 per week is a fatigue signal. Many teams celebrate high frequency as proof of "audience saturation"; it is the inverse.
|
||||
|
||||
**Using CPA when conversion definitions differ across campaigns.** A search campaign with a "lead-form-submission" conversion has a CPA in different units from a display campaign with a "purchase" conversion. Compare campaign-level CPA only when the conversion event matches.
|
||||
|
||||
**Confusing modeled conversions with measured conversions.** Modeled is an estimate; measured is a count. Treating the two as interchangeable produces false confidence in the size of the effect.
|
||||
+108
@@ -0,0 +1,108 @@
|
||||
# Platform reporting quirks
|
||||
|
||||
Per-platform reporting behaviors that affect how to read the numbers. The platforms do not agree on what counts as a conversion or how to credit it; reading their dashboards as truth is the most expensive error in paid media analytics.
|
||||
|
||||
---
|
||||
|
||||
## Google Ads
|
||||
|
||||
**Default attribution model.** Data-driven attribution (DDA) is the default. DDA distributes credit across multiple touchpoints based on machine learning. Single-touch attribution (last-click) is available but no longer the default.
|
||||
|
||||
**Conversion windows.** Default 30-day click attribution and 1-day view-through. Both adjustable. The 30-day click window is wider than what GA4 reports by default; this produces the typical 1.3 to 1.5x conversion overcount versus GA4 for the "Google Ads" channel.
|
||||
|
||||
**Modeled conversions.** Google models conversions for users with consent restrictions or cross-device gaps. Modeled volume can be material in iOS-heavy traffic. Modeled is an estimate; do not treat with the precision you would treat directly observed conversions.
|
||||
|
||||
**Performance Max black box.** PMax does not expose keyword-level, placement-level, or audience-level performance directly. The platform manages allocation across Search, Shopping, Display, YouTube, Discover, and Gmail. Levers you have: budget, asset groups (creative quality), audience signals (Customer Match seeds), and exclusions (account-level negatives).
|
||||
|
||||
**Branded search cannibalization in PMax.** PMax includes Search by default. It will harvest branded queries you would have ranked for organically. Add account-level negative keywords for branded queries to prevent paid cannibalization.
|
||||
|
||||
**Lost Impression Share metrics.** Search exposes "Lost IS (rank)" and "Lost IS (budget)" to indicate why your ad did not show. Lost IS rising is the leading indicator that competition increased or budget became constrained.
|
||||
|
||||
**Search-term reports.** The list of actual queries that triggered your ad, vs your keyword targeting. Underused. Audit monthly to find irrelevant queries (negative keyword candidates) and high-performing queries you might want to add as exact-match keywords.
|
||||
|
||||
---
|
||||
|
||||
## Meta (Facebook and Instagram)
|
||||
|
||||
**Default attribution.** 7-day click and 1-day view-through. Adjustable to 7-day click only or 1-day click only.
|
||||
|
||||
**iOS 14.5+ impact.** App Tracking Transparency (ATT) reduced Meta's ability to track iOS conversions. Meta filled the gap with modeled conversions (statistically estimated) and Conversions API (CAPI, server-side event tracking). Both help, neither fully restores pre-ATT visibility.
|
||||
|
||||
**Conversions API necessity.** CAPI sends server-side events directly from your backend to Meta, bypassing the browser-pixel restrictions. Setting up CAPI is one of the highest-impact technical investments for a Meta-heavy account. Without CAPI, the platform's optimization signal degrades significantly on iOS-heavy audiences.
|
||||
|
||||
**View-through attribution overcount.** View-through counts impressions even when the user did not click. Often half the reported conversions on Meta are view-through. Useful as awareness signal; misleading for performance optimization.
|
||||
|
||||
**Modeled conversions in iOS reports.** Meta reports modeled conversions inline with directly observed ones unless you filter explicitly. Use the breakdown view to disaggregate by attribution type (1-day click, 7-day click, 1-day view, modeled).
|
||||
|
||||
**Frequency reporting at the ad set level.** Meta exposes frequency in the Ads Manager. Use it as the primary fatigue signal; CTR decay is downstream of frequency rising.
|
||||
|
||||
**Negative feedback rate.** Meta exposes "negative feedback rate" as a customizable column. Above 1.5% is the alarm; the algorithm penalizes high-feedback creatives by reducing reach.
|
||||
|
||||
---
|
||||
|
||||
## LinkedIn
|
||||
|
||||
**Default attribution.** 30-day click and 7-day view-through.
|
||||
|
||||
**Why the longer windows.** B2B buying cycles are longer than B2C. The 30-day-click window matches the typical B2B consideration cycle. Comparing LinkedIn's reported numbers against Meta's 7-day-click numbers without normalizing is comparing different definitions.
|
||||
|
||||
**Cross-device gaps.** LinkedIn reporting tends to under-credit cross-device journeys (work computer click, personal phone visit). Pair LinkedIn paid reports with self-reported attribution surveys when the offer is high-consideration B2B.
|
||||
|
||||
**Lead Gen Forms reporting.** Form submissions count as conversions regardless of downstream lead qualification. Filter at CRM ingestion before treating LinkedIn-reported lead counts as the truth. Many leads are accidental or low-quality.
|
||||
|
||||
**Demographic insights.** LinkedIn's demographic reporting (industry, job seniority, company size, function) is unique to the platform. Use it for audience refinement; the data is not available cleanly on other platforms.
|
||||
|
||||
**Cost insights.** LinkedIn's CPM tends to be 3 to 10x higher than B2C platforms because of the audience precision premium. The justification is B2B LTV; lower-LTV offers cannot make LinkedIn math work.
|
||||
|
||||
---
|
||||
|
||||
## TikTok
|
||||
|
||||
**Default attribution.** 7-day click and 1-day view-through, similar to Meta.
|
||||
|
||||
**Video-completion-based attribution.** TikTok counts conversions even when the user did not click but watched the full video. This is unique among the platforms covered here. The signal is real for awareness; it inflates direct-response numbers.
|
||||
|
||||
**iOS impact, less mature modeling.** TikTok faces similar ATT-driven tracking gaps as Meta. The modeling is less mature, which means iOS-heavy audiences see more under-reporting on TikTok than on Meta.
|
||||
|
||||
**Spark Ads attribution overlap.** Spark Ads boost organic posts. Engagement on the boosted version shows up in both organic and paid surfaces. Be careful not to double-count when reconciling against organic engagement reports.
|
||||
|
||||
**Spark Ads vs paid creative differential.** Spark Ads consistently outperform pure paid creative on TikTok because they retain organic engagement signals. A team comparing CPMs of Spark vs paid will see Spark consistently lower; the difference is real, not a reporting artifact.
|
||||
|
||||
**Trend-based volatility.** TikTok performance is more sensitive to trending sounds and formats than other platforms. Reporting comparisons across long time periods are less reliable because the platform itself shifted.
|
||||
|
||||
---
|
||||
|
||||
## Programmatic and Display
|
||||
|
||||
**Viewability gates.** Programmatic display sells impressions, but only "viewable" impressions count toward billed performance. The Media Rating Council (MRC) standard is 50% of pixels in view for 1 second (display) or 2 seconds (video). Below this threshold, the impression should not be billed.
|
||||
|
||||
**Fraud filters.** Programmatic exposes fraud-detection metrics. Without fraud filtering, 10 to 30% of programmatic impressions are bot or fraudulent traffic. Use vendors like DoubleVerify or IAS for filtering.
|
||||
|
||||
**Attribution decay.** Programmatic display's incremental rate is usually 5 to 20%. Most clicks come from users who would have converted from other channels anyway. Treat programmatic as awareness; do not optimize for direct response unless the incrementality test confirms it.
|
||||
|
||||
---
|
||||
|
||||
## Cross-platform interference
|
||||
|
||||
A specific quirk worth a dedicated callout.
|
||||
|
||||
**The mechanism.** Two platforms claim the same conversion. A user sees a Meta ad, then later searches for the brand on Google, clicks a brand keyword, and converts. Meta claims the conversion (view-through). Google Ads claims the conversion (last-click on the brand search). The same revenue event shows up twice in the platform totals.
|
||||
|
||||
**The detection.** Sum-of-platforms exceeds total conversions in the warehouse. If platform-reported sum is 1.5 to 3x the warehouse total, you have heavy cross-platform double-counting.
|
||||
|
||||
**The defense.** Warehouse as canonical for board reporting. Platform reports for in-flight tuning of the platform's own levers. MMM at scale to estimate true cross-channel contribution.
|
||||
|
||||
---
|
||||
|
||||
## Reporting differences in numbers
|
||||
|
||||
A typical mid-stage account has the following attribution gap pattern across platforms.
|
||||
|
||||
- Google Ads reports: 1.3 to 1.5x what GA4 reports for the "Google Ads" channel.
|
||||
- Meta reports: 1.5 to 2.5x what GA4 reports for the "Facebook" channel (more on iOS-heavy audiences).
|
||||
- LinkedIn reports: roughly equal to GA4 for click-based conversions.
|
||||
- TikTok reports: 1.5 to 3.0x what GA4 reports (high view-through component).
|
||||
|
||||
If you sum all platforms' reported conversions and compare to actual revenue, the sum is typically 2 to 4x actual. The "extra" conversions are attribution overlap, view-through credit, and platform self-attribution.
|
||||
|
||||
The discipline. Trust the warehouse number for incrementality decisions. Use platform numbers for in-flight tuning. Do not optimize one platform's CAC against another platform's CAC; you are comparing different definitions of the same word.
|
||||
+282
@@ -0,0 +1,282 @@
|
||||
---
|
||||
name: after-action-report
|
||||
description: "Run a structured after-action review (postmortem, retrospective) on a launch, incident, or completed project to capture timeline, root cause analysis, contributing factors, and actionable lessons. Use this skill whenever the user wants to run a postmortem, retrospective, AAR, or after-action review on any past event. Triggers on after-action report, AAR, postmortem, retrospective, retro, post-incident review, what went well what didn't, lessons learned, blameless postmortem, root cause analysis, RCA, five whys. Also triggers when the user has just shipped something or just resolved an incident and wants to capture learnings."
|
||||
category: operations
|
||||
catalog_summary: "Post-mortems, retros, learnings documentation"
|
||||
display_order: 3
|
||||
---
|
||||
|
||||
# After-Action Report
|
||||
|
||||
Run a structured retrospective on a launch, incident, or completed project. Produce actionable lessons, not just a document.
|
||||
|
||||
This skill is for after-the-fact analysis. For active incident response, use `incident-response`. For planning launches, use `launch-runbook`.
|
||||
|
||||
---
|
||||
|
||||
## When to use
|
||||
|
||||
- After any incident (any severity)
|
||||
- After every major launch
|
||||
- At the end of a project (sprint retro, quarterly retro, project closeout)
|
||||
- When a recurring issue has happened enough times to demand investigation
|
||||
- When a decision didn't work out and the team wants to learn
|
||||
|
||||
## When NOT to use
|
||||
|
||||
- During an active incident (use `incident-response`)
|
||||
- For pre-launch planning (use `launch-runbook`)
|
||||
- For one-off bug fixes that don't merit broad analysis
|
||||
|
||||
---
|
||||
|
||||
## Required inputs
|
||||
|
||||
- The event being analyzed (incident, launch, project)
|
||||
- A timeline reconstructed from logs, chat, tickets
|
||||
- Participant accounts of what they observed and did
|
||||
- Outcomes and impact (what actually happened to users, the business)
|
||||
|
||||
---
|
||||
|
||||
## The framework: blameless analysis
|
||||
|
||||
The most important principle: blameless. Without it, retrospectives produce hidden information and theatrical lessons rather than real ones.
|
||||
|
||||
### What blameless means
|
||||
|
||||
- Focus on systems, not individuals
|
||||
- Assume everyone made reasonable decisions given what they knew at the time
|
||||
- The question is "why was this decision reasonable to make?" not "who screwed up?"
|
||||
- Fixing the system means the next person in that situation succeeds where this person didn't
|
||||
|
||||
### What blameless does not mean
|
||||
|
||||
- No accountability (action items still have owners)
|
||||
- No hard truths (sometimes the system is broken in obvious ways)
|
||||
- No standards (some patterns of failure are individual, not systemic)
|
||||
- No discomfort (real reflection is uncomfortable)
|
||||
|
||||
---
|
||||
|
||||
## The framework: 6 sections
|
||||
|
||||
A complete AAR covers six sections.
|
||||
|
||||
### 1. Summary
|
||||
|
||||
A 2 to 3 paragraph overview. Captures:
|
||||
|
||||
- What happened
|
||||
- Impact (users, business, time)
|
||||
- Root cause (in plain language)
|
||||
- Top action items
|
||||
|
||||
This is what executives read. Anyone who reads only this section should leave with the most important information.
|
||||
|
||||
### 2. Timeline
|
||||
|
||||
A reconstructed timeline of events.
|
||||
|
||||
For incidents:
|
||||
- T-0: Detection
|
||||
- T+X: Acknowledgment
|
||||
- T+Y: Severity assessed, IC assigned
|
||||
- T+Z: Investigation began
|
||||
- ... mitigation, communication, resolution events
|
||||
- T+N: Resolution declared
|
||||
|
||||
For launches:
|
||||
- Pre-launch decisions and milestones
|
||||
- Launch day events
|
||||
- Post-launch monitoring observations
|
||||
|
||||
For projects:
|
||||
- Major milestones, decisions, pivots
|
||||
- Both planned and emergent
|
||||
|
||||
The timeline is the source of truth. Disagreements about what happened get resolved here.
|
||||
|
||||
### 3. Root cause analysis
|
||||
|
||||
What caused this, in plain language.
|
||||
|
||||
Use one or both of:
|
||||
|
||||
**Five whys.** Start with the surface symptom. Ask "why?" Repeat 5 times (or until you reach a true root). Each "why" should yield a substantive answer, not a tautology.
|
||||
|
||||
Example:
|
||||
- Why did the site go down? Database connection pool exhausted.
|
||||
- Why was the pool exhausted? Background job opened too many connections.
|
||||
- Why did the background job open too many connections? Connection cleanup code didn't run on errors.
|
||||
- Why didn't cleanup run on errors? Original code review didn't cover error paths.
|
||||
- Why didn't the review cover error paths? No checklist for error handling in our review process.
|
||||
|
||||
The fifth why often reveals the system fix. In this case: improve the review process.
|
||||
|
||||
**Causal chain.** Multiple contributing factors that combined.
|
||||
|
||||
- Factor 1: Background job opened too many connections (technical)
|
||||
- Factor 2: Connection limit was set too low for actual traffic (configuration)
|
||||
- Factor 3: No alert on connection pool saturation (monitoring)
|
||||
- Factor 4: Recent traffic doubled without infra capacity review (process)
|
||||
|
||||
No single fix addresses the incident. Multiple gaps need attention.
|
||||
|
||||
### 4. Contributing factors
|
||||
|
||||
Factors that didn't cause the event but made it worse, or removed safety nets that would have caught it.
|
||||
|
||||
- Monitoring gaps
|
||||
- Documentation gaps
|
||||
- Process gaps
|
||||
- Tooling gaps
|
||||
- Knowledge gaps
|
||||
|
||||
A "would have been caught earlier if..." factor.
|
||||
|
||||
### 5. What went well
|
||||
|
||||
Real lessons require capturing successes, not just failures.
|
||||
|
||||
- What detection worked?
|
||||
- What response worked?
|
||||
- What decisions were good?
|
||||
- What tools or processes performed as expected?
|
||||
|
||||
This is not consolation. It's calibration. Things that worked here should be reinforced and replicated.
|
||||
|
||||
### 6. Action items
|
||||
|
||||
Specific, owned, dated.
|
||||
|
||||
| Action | Owner | Due | Type |
|
||||
|---|---|---|---|
|
||||
| Add alert on connection pool saturation | [name] | [date] | Monitoring |
|
||||
| Add error handling checklist to PR template | [name] | [date] | Process |
|
||||
| Audit other background jobs for similar issue | [name] | [date] | Code |
|
||||
|
||||
**Action item criteria:**
|
||||
|
||||
- **Specific.** "Improve monitoring" is not actionable. "Add alert on connection pool saturation, threshold 80%, page on-call" is.
|
||||
- **Owned.** A name. Not "the team."
|
||||
- **Dated.** A real date. Not "soon."
|
||||
- **Sized.** Roughly hours, days, or weeks of effort.
|
||||
- **Closeable.** Definition of done is clear.
|
||||
|
||||
Action items that don't close in their committed timeframe should re-surface in the next AAR. Patterns of unclosed actions point to deeper organizational issues.
|
||||
|
||||
---
|
||||
|
||||
## Workflow
|
||||
|
||||
### 1. Schedule the AAR
|
||||
|
||||
Within 1 to 2 weeks of the event. Long enough that emotions cooled and facts gathered. Short enough that memories are fresh.
|
||||
|
||||
For incidents: pre-decided in the response procedure.
|
||||
For launches: schedule on the runbook.
|
||||
For projects: schedule at project closeout.
|
||||
|
||||
### 2. Gather inputs
|
||||
|
||||
Before the meeting:
|
||||
|
||||
- Reconstructed timeline (often the scribe's notes if there was one)
|
||||
- Logs, chat transcripts, tickets, incident updates
|
||||
- Individual accounts from each participant (written, before the meeting)
|
||||
- Impact data (users affected, duration, revenue impact, etc.)
|
||||
|
||||
### 3. Run the meeting
|
||||
|
||||
Typical agenda (60 to 90 minutes):
|
||||
|
||||
- Read the summary as drafted (5 min)
|
||||
- Walk the timeline together. Add corrections. Resolve disagreements. (20 to 30 min)
|
||||
- Discuss root cause. Use five whys or causal chain. (15 to 20 min)
|
||||
- Discuss contributing factors. (10 min)
|
||||
- Discuss what went well. (10 min)
|
||||
- Identify action items. Owners and dates. (10 min)
|
||||
|
||||
A facilitator runs the meeting. Often the IC for an incident, or a project lead for a project. The facilitator is not the scribe.
|
||||
|
||||
### 4. Write the document
|
||||
|
||||
Within a few days of the meeting. The full AAR includes all 6 sections.
|
||||
|
||||
### 5. Distribute
|
||||
|
||||
Internal: post in a known location. Make searchable. Reference in onboarding.
|
||||
|
||||
For high-severity incidents: external summary may be appropriate (status page, customer email, public blog).
|
||||
|
||||
### 6. Track action items
|
||||
|
||||
Every action item should be tracked to closure. The next AAR re-surfaces unclosed ones.
|
||||
|
||||
---
|
||||
|
||||
## Failure patterns
|
||||
|
||||
- **Skipping the AAR for "small" incidents.** Patterns get missed.
|
||||
- **Naming and shaming.** Real lessons get hidden when people fear blame.
|
||||
- **Generic action items.** "Improve testing" instead of specific testing change.
|
||||
- **Action items that never close.** Filed, forgotten. Same incident recurs.
|
||||
- **Theater retrospectives.** Going through the motions without genuine reflection.
|
||||
- **Skipping "what went well."** Misses calibration on what's working.
|
||||
- **Blame externalized.** "Our vendor failed." OK, what's our system for vendor risk?
|
||||
- **Single-person AAR.** One person writes the whole thing. Misses other perspectives.
|
||||
- **AAR only for failures.** Successful launches deserve AARs too. Lessons from success are valuable.
|
||||
- **Long delays.** Memories fade. Conversations cool. Get it done within 2 weeks.
|
||||
|
||||
---
|
||||
|
||||
## Output format
|
||||
|
||||
A markdown document at `aar-[date]-[event-name].md`.
|
||||
|
||||
Structure:
|
||||
|
||||
```markdown
|
||||
# AAR: [Event name]
|
||||
|
||||
**Date of event:** [YYYY-MM-DD]
|
||||
**AAR date:** [YYYY-MM-DD]
|
||||
**Severity / scope:** [SEV-1 / Major launch / Project closeout]
|
||||
**Facilitator:** [Name]
|
||||
**Participants:** [Names]
|
||||
|
||||
## Summary
|
||||
[2 to 3 paragraphs]
|
||||
|
||||
## Impact
|
||||
- Users affected: [number, segment]
|
||||
- Duration: [time]
|
||||
- Revenue / business impact: [if applicable]
|
||||
|
||||
## Timeline
|
||||
[Timestamped events]
|
||||
|
||||
## Root cause analysis
|
||||
[Five whys or causal chain]
|
||||
|
||||
## Contributing factors
|
||||
[List]
|
||||
|
||||
## What went well
|
||||
[List]
|
||||
|
||||
## Action items
|
||||
| Action | Owner | Due | Type | Status |
|
||||
|---|---|---|---|---|
|
||||
| | | | | |
|
||||
|
||||
## Lessons
|
||||
[Reflections that don't fit elsewhere. Often the most quotable section.]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Reference files
|
||||
|
||||
- [`references/aar-template.md`](references/aar-template.md) - Fillable AAR template covering incidents, launches, and projects.
|
||||
@@ -0,0 +1,296 @@
|
||||
# AAR Template
|
||||
|
||||
Fillable after-action report template. Three variations: incident AAR, launch AAR, project closeout AAR. The structure is similar; the inputs and emphasis differ.
|
||||
|
||||
---
|
||||
|
||||
## Universal sections (used in all three variations)
|
||||
|
||||
### Header
|
||||
|
||||
```markdown
|
||||
# AAR: [Event name]
|
||||
|
||||
**Type:** [Incident / Launch / Project]
|
||||
**Date of event:** [YYYY-MM-DD or range]
|
||||
**AAR date:** [YYYY-MM-DD]
|
||||
**Severity / scope:** [SEV-1 / Major launch / Project closeout]
|
||||
**Facilitator:** [Name]
|
||||
**Participants:** [Names]
|
||||
**Distribution:** [Internal only / Internal + customers / Public]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Variation 1: Incident AAR
|
||||
|
||||
### Summary
|
||||
|
||||
> [2 to 3 paragraphs. What happened, what was the impact, what was the root cause, what are the top action items. Should stand alone for executives who read only this section.]
|
||||
|
||||
### Impact
|
||||
|
||||
- **Users affected:** [Number and segment. "All US users" or "Approximately 12% of paid customers in EU."]
|
||||
- **Duration:** [Detection to resolution]
|
||||
- **Severity:** [SEV-1 / 2 / 3 / 4]
|
||||
- **Revenue impact:** [If quantifiable]
|
||||
- **Customer-facing communication:** [What was said, when]
|
||||
- **Regulatory implications:** [If any]
|
||||
|
||||
### Timeline
|
||||
|
||||
| Time | Event | Notes |
|
||||
|---|---|---|
|
||||
| T-X | [Pre-incident state, recent deploy, etc.] | |
|
||||
| T-0 | [Detection event] | |
|
||||
| T+5min | [Acknowledgment] | |
|
||||
| T+10min | [Severity assessed, IC assigned] | |
|
||||
| T+Xmin | [Investigation milestone] | |
|
||||
| T+Ymin | [Mitigation applied] | |
|
||||
| T+Zmin | [Verification] | |
|
||||
| T+Nmin | [Resolution declared] | |
|
||||
| T+Hours | [Customer comms, post-incident] | |
|
||||
|
||||
Timeline source: [Logs, chat, monitoring, IC notes]
|
||||
|
||||
### Detection
|
||||
|
||||
- **How was it detected?** [Alert / customer report / internal observation]
|
||||
- **Time to detection:** [From event start to detection]
|
||||
- **Was detection adequate?** [Should we have detected this faster? How?]
|
||||
|
||||
### Response
|
||||
|
||||
- **Time to acknowledgment:** [Detection to acknowledgment]
|
||||
- **Time to mitigation:** [Detection to mitigation]
|
||||
- **Time to resolution:** [Detection to resolution]
|
||||
- **Were the right people involved?** [Yes / No, why]
|
||||
- **Did the response procedure work?** [Yes / No, what gaps]
|
||||
|
||||
### Root cause analysis
|
||||
|
||||
**Surface symptom:** [What users experienced]
|
||||
|
||||
**Five whys:**
|
||||
|
||||
1. Why did [symptom] happen? [Answer]
|
||||
2. Why did [Answer 1] happen? [Answer]
|
||||
3. Why did [Answer 2] happen? [Answer]
|
||||
4. Why did [Answer 3] happen? [Answer]
|
||||
5. Why did [Answer 4] happen? [Answer - often the system fix]
|
||||
|
||||
**Or, causal chain (multiple contributing factors):**
|
||||
|
||||
- Factor 1 (technical): [Description]
|
||||
- Factor 2 (configuration): [Description]
|
||||
- Factor 3 (process): [Description]
|
||||
- Factor 4 (monitoring): [Description]
|
||||
|
||||
### Contributing factors
|
||||
|
||||
What didn't cause this but made it worse, or removed safety nets:
|
||||
|
||||
- [Factor]
|
||||
- [Factor]
|
||||
- [Factor]
|
||||
|
||||
### What went well
|
||||
|
||||
- [Detection mechanism that worked]
|
||||
- [Decision that was correct]
|
||||
- [Tool that performed as designed]
|
||||
- [Communication that was effective]
|
||||
|
||||
### Action items
|
||||
|
||||
| Action | Owner | Due | Type | Status |
|
||||
|---|---|---|---|---|
|
||||
| [Specific action] | [Name] | [Date] | Monitoring | Open |
|
||||
| [Specific action] | [Name] | [Date] | Code | Open |
|
||||
| [Specific action] | [Name] | [Date] | Process | Open |
|
||||
| [Specific action] | [Name] | [Date] | Documentation | Open |
|
||||
| [Specific action] | [Name] | [Date] | Training | Open |
|
||||
|
||||
### Lessons
|
||||
|
||||
[Reflections beyond the action items. Often the most-quoted section in the long term.]
|
||||
|
||||
---
|
||||
|
||||
## Variation 2: Launch AAR
|
||||
|
||||
### Summary
|
||||
|
||||
> [2 to 3 paragraphs. What launched, did it go well, what surprised us, what should we do differently next time.]
|
||||
|
||||
### Outcomes
|
||||
|
||||
- **What launched:** [Specific scope]
|
||||
- **Launch window:** [Planned vs actual]
|
||||
- **Maintenance time:** [If applicable]
|
||||
- **Issues during launch:** [Count and severity]
|
||||
- **Rollback?:** [Yes / No]
|
||||
- **Post-launch incidents:** [In the first 7 days]
|
||||
- **Business outcomes:** [If measurable, e.g., conversion impact]
|
||||
|
||||
### Timeline
|
||||
|
||||
| Time | Event | Notes |
|
||||
|---|---|---|
|
||||
| Pre-launch | [Major decisions, milestones] | |
|
||||
| Launch start | | |
|
||||
| Cutover steps | [Each step with timing] | |
|
||||
| Verification | | |
|
||||
| Public announcement | | |
|
||||
| First 24 hours | [Notable observations] | |
|
||||
| First week | [Notable observations] | |
|
||||
|
||||
### What went according to plan
|
||||
|
||||
- [Step that worked exactly as runbook described]
|
||||
- [Communication that was clear]
|
||||
- [Decision that proved correct]
|
||||
|
||||
### What deviated from plan
|
||||
|
||||
- [Deviation, why, what we did]
|
||||
- [Deviation, why, what we did]
|
||||
|
||||
### What surprised us
|
||||
|
||||
- [Unexpected observation]
|
||||
- [Unexpected user behavior]
|
||||
- [Unexpected technical behavior]
|
||||
|
||||
### What we'd do differently
|
||||
|
||||
- [Change to runbook for next launch]
|
||||
- [Change to pre-launch QA]
|
||||
- [Change to communication plan]
|
||||
|
||||
### What we'd repeat
|
||||
|
||||
- [Practice that worked, want to keep]
|
||||
|
||||
### Action items
|
||||
|
||||
| Action | Owner | Due | Type | Status |
|
||||
|---|---|---|---|---|
|
||||
| [Specific action] | | | | |
|
||||
|
||||
### Lessons
|
||||
|
||||
[Reflections.]
|
||||
|
||||
---
|
||||
|
||||
## Variation 3: Project closeout AAR
|
||||
|
||||
### Summary
|
||||
|
||||
> [2 to 3 paragraphs. What we set out to do, what we delivered, what we learned, what comes next.]
|
||||
|
||||
### Goals vs outcomes
|
||||
|
||||
| Goal | Outcome | Notes |
|
||||
|---|---|---|
|
||||
| [Original goal 1] | [Met / Partially met / Not met] | [Notes] |
|
||||
| [Original goal 2] | [Met / Partially met / Not met] | [Notes] |
|
||||
| [Original goal 3] | [Met / Partially met / Not met] | [Notes] |
|
||||
|
||||
### Timeline
|
||||
|
||||
| Phase | Planned | Actual | Variance |
|
||||
|---|---|---|---|
|
||||
| Discovery | | | |
|
||||
| Design | | | |
|
||||
| Build | | | |
|
||||
| QA | | | |
|
||||
| Launch | | | |
|
||||
|
||||
### What went well
|
||||
|
||||
- [Practice / decision / process that worked]
|
||||
- [Practice / decision / process that worked]
|
||||
- [Practice / decision / process that worked]
|
||||
|
||||
### What didn't go well
|
||||
|
||||
- [Pain point with system-level explanation]
|
||||
- [Pain point with system-level explanation]
|
||||
|
||||
### What surprised us
|
||||
|
||||
- [Surprising input from users / market / internal]
|
||||
- [Surprising scale / complexity / opportunity]
|
||||
|
||||
### What we'd do differently
|
||||
|
||||
For people working on similar projects in the future:
|
||||
|
||||
- [Specific change]
|
||||
- [Specific change]
|
||||
- [Specific change]
|
||||
|
||||
### Decisions in retrospect
|
||||
|
||||
| Decision | Was it right? | Why or why not |
|
||||
|---|---|---|
|
||||
| [Major decision 1] | | |
|
||||
| [Major decision 2] | | |
|
||||
| [Major decision 3] | | |
|
||||
|
||||
### Action items
|
||||
|
||||
| Action | Owner | Due | Type | Status |
|
||||
|---|---|---|---|---|
|
||||
| [Specific action] | | | | |
|
||||
|
||||
### Lessons
|
||||
|
||||
[Reflections.]
|
||||
|
||||
### Recommendations for next phase
|
||||
|
||||
[If the project continues. Otherwise, recommendations for what builds on this work.]
|
||||
|
||||
---
|
||||
|
||||
## Universal facilitator guide
|
||||
|
||||
### Before the meeting (pre-work)
|
||||
|
||||
- Send the timeline draft to all participants
|
||||
- Ask each participant to write their personal account of what they observed and did (1 to 2 paragraphs each)
|
||||
- Compile contributing data: logs, metrics, ticket counts, customer feedback
|
||||
- Send participants the agenda 24 hours in advance
|
||||
|
||||
### During the meeting
|
||||
|
||||
- Set the tone in the first 60 seconds: "This is blameless. Focus on systems, not individuals."
|
||||
- Walk the timeline. Add corrections from participants.
|
||||
- For root cause: ask "why" until the answers stop being substantive. Note when it shifts from technical to process.
|
||||
- For action items: insist on specificity, owner, date.
|
||||
- Don't let the meeting become a debugging session. Investigation happened before; this is for analysis.
|
||||
- Capture the document live where possible. Edits in real time prevent recall errors.
|
||||
|
||||
### After the meeting
|
||||
|
||||
- Polish the document within 48 hours
|
||||
- Distribute to broader audience
|
||||
- File action items into a tracking system
|
||||
- Schedule follow-up to verify action items closed (typically 30 days out)
|
||||
|
||||
---
|
||||
|
||||
## Common AAR anti-patterns
|
||||
|
||||
| Anti-pattern | What it looks like | Better |
|
||||
|---|---|---|
|
||||
| Naming and shaming | "Sarah deployed the bug" | "Our review process didn't catch the issue. Why? What checklist or test would have?" |
|
||||
| Generic actions | "Improve testing" | "Add a test for X scenario to the existing test suite by [date]" |
|
||||
| No follow-through | Action items filed, never tracked | Action item review at next AAR; pattern of unclosed items surfaces |
|
||||
| Skipping success | Only failures discussed | Equal time to what went well |
|
||||
| Sole authorship | One person writes the AAR | Group discussion + sole author for polish |
|
||||
| Long delay | AAR happens 2 months later | AAR within 2 weeks of event |
|
||||
| Skipping minor incidents | "Not worth the time" | Patterns hide in the minors |
|
||||
@@ -0,0 +1,281 @@
|
||||
---
|
||||
name: ai-content-collaboration
|
||||
description: "How humans and AI compose in content workflows. Where AI legitimately participates, where humans must own, hybrid workflow patterns, voice ownership preservation, the AI slop problem, disclosure and transparency, team calibration, and the ethics of intellectually honest AI-assisted content production. Triggers on AI content workflow, AI-assisted writing, hybrid content production, AI in editorial, AI slop, AI disclosure, AI usage policy, AI content ethics, voice preservation with AI, team AI calibration. Also triggers when content feels generic despite quality tools, when team AI usage has drifted into inconsistency, or when a regulated or trust-sensitive context requires explicit AI policy."
|
||||
category: content
|
||||
catalog_summary: "How humans and AI compose in content workflows: participation boundaries, hybrid patterns, voice ownership, the AI slop problem, disclosure and transparency, team calibration, and the ethics of honest AI-assisted production"
|
||||
display_order: 8
|
||||
---
|
||||
|
||||
# AI Content Collaboration
|
||||
|
||||
A senior editorial leader's playbook for how humans and AI compose in content workflows. Pragmatic, tool-agnostic, honest about both what AI in the loop enables and what it threatens.
|
||||
|
||||
Most content programs in 2026 use AI somewhere in the workflow. Pretending otherwise is dishonest; treating AI as a magic content factory is the failure mode this skill exists to prevent. The discipline is in between: knowing where AI legitimately accelerates, where humans must own, what hybrid patterns produce work that earns reader trust, and what crosses the line into AI slop or intellectual dishonesty.
|
||||
|
||||
This skill is the WORKFLOW layer that composes with every other content skill. Briefs can be AI-assisted; hub architectures can be AI-assisted; programmatic SEO is almost always AI-involved; editorial QA now includes AI-content audit by necessity. The collaboration discipline applies to all production stages, not to a single artifact type.
|
||||
|
||||
The voice is pragmatic and tool-agnostic deliberately. The methodology applies whether the AI in your loop is one of the major commercial models, an open-source model, or whatever ships next quarter. What stays constant is the workflow shape, the participation boundaries, the voice ownership question, and the ethical frame. What changes is which specific tool you reach for, which is implementation work that varies by team and budget.
|
||||
|
||||
When to use this skill: building or refining an AI-content workflow, calibrating a team on consistent AI usage, addressing the "we use AI but our work feels generic" problem, designing disclosure policies, or working through the ethics of AI-assisted content production for a regulated or trust-sensitive context.
|
||||
|
||||
---
|
||||
|
||||
## What this skill is for
|
||||
|
||||
This skill spans the workflow layer of AI-assisted content production. It composes with all six other content-suite skills as the cross-cutting discipline.
|
||||
|
||||
- `content-strategy` is program scope: what to produce. Strategy decisions can be AI-assisted; the program-level judgment stays human.
|
||||
- `pillar-content-architecture` is hub scope: how the topical hub fits together. Hub architecture can be AI-suggested; the architectural commitment stays human.
|
||||
- `content-brief-authoring` is per-piece scope: briefs each piece. Briefs can be AI-drafted from research; the contract decisions stay human.
|
||||
- `content-and-copy` is execution scope: writes each piece. Drafts can be AI-produced; voice and editorial judgment stay human.
|
||||
- `programmatic-seo` is scaled scope: generates pages from data. AI generation is the dominant production model; sampling QA is the human gate.
|
||||
- `editorial-qa` is gate scope: verifies before publish. AI-content audit is now a load-bearing gate; the audit's judgment stays human.
|
||||
- This skill is workflow scope: how the human and AI layers compose across all six stages above.
|
||||
|
||||
The audience: editorial leaders, content directors, content ops managers, agencies running AI-assisted production, in-house teams calibrating AI usage across writers. The voice is senior editorial leader to junior editor or content marketer. Pragmatic, honest, tool-agnostic.
|
||||
|
||||
What is not in scope: specific prompts (those are implementation; teams develop their own), specific tool endorsements (the methodology applies regardless of which tool is in the loop), specific integration code (varies by stack and team). Tool categories appear when they earn methodology relevance; specific tools appear only as illustrations of categories, never as recommendations.
|
||||
|
||||
---
|
||||
|
||||
## Humans own, AI accelerates
|
||||
|
||||
The keystone framing.
|
||||
|
||||
The pathology to avoid is treating AI as either a magic content factory (cheap, fast, scaled, output quality optional) OR as a forbidden intruder (purity gospel that does not survive contact with deadlines). Both readings produce bad work.
|
||||
|
||||
The discipline that produces durable work: humans own the content; AI accelerates the work. Specifically:
|
||||
|
||||
**Humans own.** Editorial judgment, voice, distinctive POV, fact accuracy, ethical decisions, what to publish versus what to kill, brand voice, narrative arc, tone calibration, reader empathy, claim verification.
|
||||
|
||||
**AI accelerates.** Research synthesis, draft generation against a brief, copy edit suggestions, alternative phrasings, summary, transcription, quality-control automation at scale.
|
||||
|
||||
The line. AI does work that the human directs and verifies. AI does NOT make decisions about what publishes, who is quoted, what is true, or what voice the brand uses.
|
||||
|
||||
The litmus test. If your AI-assisted piece publishes without a human being able to defend every claim, every position, and every word, you have crossed the line. The piece is AI's work, dressed in your byline. Readers eventually notice.
|
||||
|
||||
---
|
||||
|
||||
## Where AI legitimately participates
|
||||
|
||||
A non-exhaustive list of stages where AI in the loop is fine and often improves the work.
|
||||
|
||||
- **Research synthesis.** AI condenses long-form sources into briefs the writer reads. Saves hours; the writer still reads and verifies.
|
||||
- **Outline generation against a brief.** AI proposes an H2 / H3 structure from a brief; the editor approves or restructures.
|
||||
- **First-draft generation.** AI produces a draft against an explicit brief; the human edits substantially.
|
||||
- **Alternative phrasings.** AI offers 3 versions of a sentence; the human picks one or rewrites.
|
||||
- **Copy edit suggestions.** AI catches typos, awkward phrasings, repetition.
|
||||
- **Summary and abstraction.** AI condenses long pieces into TL;DRs.
|
||||
- **Transcription.** AI transcribes interview audio; the human verifies.
|
||||
- **Translation drafts.** AI produces a translation draft; a native speaker reviews and corrects.
|
||||
- **Quality-control automation at scale.** AI flags pages in a programmatic SEO set that need human review.
|
||||
- **Idea generation.** AI proposes 30 angles; the human picks 3.
|
||||
|
||||
In each case, AI accelerates work the human still owns. The acceleration is real; the ownership stays unchanged.
|
||||
|
||||
Detail in [`references/ai-participation-boundaries.md`](references/ai-participation-boundaries.md).
|
||||
|
||||
---
|
||||
|
||||
## Where humans must own
|
||||
|
||||
The boundary list.
|
||||
|
||||
- **Editorial judgment.** What to publish, what to kill, what is worth saying. AI cannot decide whether a piece is good enough to ship.
|
||||
- **Voice.** Brand voice, distinctive POV, the way THIS publication sounds different from the next one. AI default voice is generic by construction; voice is a human contribution.
|
||||
- **Fact verification.** Every claim, every statistic, every quote, every named person. AI hallucinates; humans verify.
|
||||
- **Ethical decisions.** What is appropriate to publish, what is harmful, what crosses lines, what disclosure is required.
|
||||
- **Reader empathy.** What the reader actually needs from this piece, not what the algorithm scores well.
|
||||
- **Quote attribution.** Real people who actually said the thing, with consent where relevant.
|
||||
- **Tone calibration on hard topics.** Grief, illness, sensitive history, contested politics. AI defaults to anodyne; humans calibrate to context.
|
||||
- **Narrative arc.** How the piece unfolds, where the reader's attention goes. AI produces shapes; humans choose them.
|
||||
- **Final approval.** The human who signs off is accountable for what shipped.
|
||||
|
||||
The "human in the loop" framing is necessary but insufficient. A human briefly reviewing AI-generated content before publish is not ownership; it is rubber-stamping. Ownership requires the human to have made the actual decisions the piece embodies.
|
||||
|
||||
---
|
||||
|
||||
## Hybrid workflow patterns
|
||||
|
||||
Five patterns that work, with tradeoffs.
|
||||
|
||||
**1. AI-first draft, human-edit-heavy.** AI produces a 90% draft; the human spends 60% of the time editing. Output: efficient for high-volume editorial; risks generic voice if editing is light.
|
||||
|
||||
**2. Human-first outline + research, AI-draft, human-rewrite.** Human builds the outline and gathers research; AI drafts within that scaffold; human rewrites in voice. Output: preserves voice better; slower than AI-first.
|
||||
|
||||
**3. AI-as-research-assistant, human-writes.** AI condenses sources into a brief; human writes the entire piece from the brief. Output: highest voice fidelity; slowest.
|
||||
|
||||
**4. Human-writes, AI-as-editor.** Human drafts; AI suggests edits, alternative phrasings, copy edits; human accepts or rejects. Output: writer voice preserved; AI catches details.
|
||||
|
||||
**5. AI-generates-at-scale, human-samples.** For programmatic SEO. AI generates thousands of pages; human samples 50 to 200 with editorial-qa discipline. Output: scaled production; depends entirely on template quality and sampling discipline.
|
||||
|
||||
The pattern that fits depends on volume, voice sensitivity, team skill, and time budget. No pattern is "the right one"; pattern selection is a real decision that should match the production context.
|
||||
|
||||
Detail in [`references/hybrid-workflow-patterns.md`](references/hybrid-workflow-patterns.md).
|
||||
|
||||
---
|
||||
|
||||
## Voice ownership preservation
|
||||
|
||||
Voice is the dominant casualty of careless AI workflows. The patterns that preserve voice.
|
||||
|
||||
- **Voice guidelines as prompt input.** Every AI generation includes the brand voice guidelines as context. Generic AI defaults regress without this.
|
||||
- **Sample text as voice anchor.** Feed the AI 2 to 3 paragraphs of canonical brand voice as part of the prompt. AI mimics what it sees more than what it is told.
|
||||
- **Mid-draft voice check.** At the halfway mark of a long piece, have a human or a separate AI pass read for voice drift. Long AI generations regress halfway through almost always.
|
||||
- **Final pass in human voice.** The human edits the closing sections in their own voice; this is where the piece's emotional register often lands.
|
||||
- **Reject the bland.** Any sentence that could appear in any other piece on the topic gets rewritten. Voice lives in the specific.
|
||||
|
||||
The honest framing. Voice is the hardest thing to preserve in AI-assisted work and the easiest thing to lose. Programs that do not actively preserve voice end up with content that is technically correct, semantically generic, and indistinguishable from competitors using the same tools.
|
||||
|
||||
Detail in [`references/voice-ownership-preservation.md`](references/voice-ownership-preservation.md).
|
||||
|
||||
---
|
||||
|
||||
## The AI slop problem
|
||||
|
||||
AI slop is the term of art for AI-generated content that is technically functional but reads as generic, derivative, and signal-less. Cross-reference `editorial-qa`'s ai-content-audit-patterns reference for the detection patterns; this section addresses prevention.
|
||||
|
||||
**Patterns that produce slop.**
|
||||
|
||||
- AI does too much of the work (no real human direction or rewriting)
|
||||
- Generic prompts (no brand voice context, no audience specificity, no anti-pattern guidance)
|
||||
- No editorial judgment in the loop (AI generates, human glances, ship)
|
||||
- Volume prioritized over quality (10x more pages can mean 10x more slop, not 10x more value)
|
||||
- No iteration (first draft ships; no rewrite for voice)
|
||||
|
||||
**Patterns that prevent slop.**
|
||||
|
||||
- Strong briefs (per `content-brief-authoring`)
|
||||
- Voice guidelines as prompt context
|
||||
- Heavy human editing pass
|
||||
- Iteration: AI draft, then human rewrite, then AI suggestions, then human final
|
||||
- Editorial judgment at every gate
|
||||
|
||||
The reader-detection problem. Readers can often sense AI-flavored content even when they cannot articulate why. Generic openings, predictable structures, "perfect" grammar that is emotionally flat. Slop loses reader trust over time even when individual pieces are not penalized.
|
||||
|
||||
Detail in [`references/ai-slop-detection-and-avoidance.md`](references/ai-slop-detection-and-avoidance.md) and cross-reference editorial-qa's audit patterns.
|
||||
|
||||
---
|
||||
|
||||
## Disclosure and transparency
|
||||
|
||||
When should AI usage be disclosed to readers?
|
||||
|
||||
The tiered framework.
|
||||
|
||||
- **Always disclose.** Journalism, news reporting, attributed expert opinion, content where AI tools are the subject.
|
||||
- **Default disclosure (consider context).** Thought leadership where the byline is doing trust work, regulated industries, content that influences purchase decisions.
|
||||
- **Generally not necessary.** Marketing copy, descriptive product content, programmatic data pages, copy edit assistance only.
|
||||
- **Clearly fine without disclosure.** AI as research assistant only; AI for transcription; AI for spelling and grammar suggestions.
|
||||
|
||||
The principle. Disclose when the reader's understanding of the content's origin would change their trust in it. A bylined opinion piece purportedly by a named expert that is substantially AI-drafted is a trust violation; a product description on an ecommerce site that was AI-drafted is not.
|
||||
|
||||
**Disclosure language patterns (when used).**
|
||||
|
||||
- "AI tools assisted in research and drafting; the author edited and verified all claims."
|
||||
- "This piece was generated programmatically from [data source]; reviewed by [team] before publish."
|
||||
- Avoid hedging language like "may have used AI" or "could have been AI-assisted"; be specific or omit.
|
||||
|
||||
Industry-specific norms vary. Major journalism organizations have published explicit AI usage standards. Content marketing has weaker norms but is moving toward disclosure for high-trust pieces.
|
||||
|
||||
Detail in [`references/disclosure-and-transparency-patterns.md`](references/disclosure-and-transparency-patterns.md).
|
||||
|
||||
---
|
||||
|
||||
## Team training and calibration
|
||||
|
||||
Inconsistent AI usage across a team produces inconsistent output. The discipline.
|
||||
|
||||
- **Documented AI policy.** Which uses are approved, which require explicit permission, which are prohibited.
|
||||
- **Calibration sessions.** Editors review AI-assisted pieces from multiple writers, surface differences, agree on standards.
|
||||
- **Voice library updates.** As voice evolves, the prompts and sample text fed to AI evolve with it.
|
||||
- **Quality benchmarks.** What does "AI-assisted but on-voice" look like for your brand? Document it with examples.
|
||||
- **Tool standardization or intentional pluralism.** Team uses one tool consistently OR documents which tools fit which tasks.
|
||||
- **Forbidden patterns list.** This team does not use AI for X (whatever X is for your context).
|
||||
- **Onboarding.** New writers learn the AI policy and calibration in their first 2 weeks.
|
||||
|
||||
The pathology. AI usage emerges informally, every writer develops their own patterns, output drifts, editors cannot pinpoint why pieces feel off. The discipline is making AI usage explicit, calibrated, and documented.
|
||||
|
||||
Detail in [`references/team-training-and-calibration.md`](references/team-training-and-calibration.md).
|
||||
|
||||
---
|
||||
|
||||
## Ethics: training data, attribution, intellectual honesty
|
||||
|
||||
AI tools were trained on copyrighted material. That is the simple ethical reality of every major LLM in 2026. The catalog's position on this question is not "AI use is unethical" (that would render the catalog itself hypocritical) but "intellectual honesty about AI involvement is non-negotiable."
|
||||
|
||||
The principles.
|
||||
|
||||
- **Do not pass AI work as fully human-written.** Bylined content where the byline implies human craft requires substantial human craft.
|
||||
- **Do not claim AI did not help when it did.** False denials are worse than disclosure.
|
||||
- **Do not generate content that closely mirrors copyrighted source material.** AI tools can produce near-replicas of training data when prompted carelessly; humans verify originality.
|
||||
- **Attribute when borrowing.** Ideas, frameworks, statistics that came from specific sources get cited.
|
||||
- **Do not fabricate quotes or expertise.** Hallucinated quotes attributed to real people are dishonest regardless of whether AI generated them.
|
||||
- **Be honest about AI capabilities and limits.** Do not oversell AI as more capable than it is.
|
||||
|
||||
The intellectual-honesty frame supersedes any specific policy debate. Teams that treat AI usage with intellectual honesty produce content readers can trust over time. Teams that hide, deny, or rationalize lose trust eventually.
|
||||
|
||||
Detail in [`references/ethics-and-intellectual-honesty.md`](references/ethics-and-intellectual-honesty.md).
|
||||
|
||||
---
|
||||
|
||||
## Common failure modes
|
||||
|
||||
Rapid-fire. Diagnoses in [`references/common-collaboration-failures.md`](references/common-collaboration-failures.md).
|
||||
|
||||
- "We used AI and the content feels generic." Voice not preserved; not enough human rewriting.
|
||||
- "Hallucinated facts made it to publish." Fact-verification gate skipped or rushed.
|
||||
- "Different writers produce wildly different AI-assisted output." No team calibration.
|
||||
- "Our AI-assisted SEO content got penalized." Slop volume plus thin templates plus no QA discipline.
|
||||
- "We cannot tell what was AI versus human." No AI usage tracking; teams should document at the workflow level.
|
||||
- "Readers complained about AI-flavored content." Slop reaching audience; intensify human craft pass.
|
||||
- "We disclosed AI usage and lost credibility." Depends on context; disclosure is sometimes a trust gain, sometimes a loss; calibrate to audience norms.
|
||||
- "Our AI tools changed and our content shifted." Over-coupled to one tool's specific behavior; methodology should be tool-agnostic.
|
||||
- "We are producing 10x more content but the same audience growth." Volume was not the constraint that was binding; quality was.
|
||||
- "The team is using AI inconsistently." Calibration sessions overdue.
|
||||
- "An expert byline turned out to be substantially AI-drafted." Ethics breach; correct, disclose, recalibrate.
|
||||
|
||||
---
|
||||
|
||||
## The framework: 12 considerations for AI content collaboration
|
||||
|
||||
When designing or auditing an AI-assisted content workflow, walk these 12 considerations.
|
||||
|
||||
1. **Humans own; AI accelerates.** Make this explicit in your workflow, not implicit.
|
||||
2. **Participation boundaries.** Document where AI legitimately helps, where humans must own.
|
||||
3. **Hybrid pattern selection.** Match the pattern to volume, voice sensitivity, time budget.
|
||||
4. **Voice guidelines as prompt input.** Every AI generation includes brand voice context.
|
||||
5. **Voice drift sampling.** Long pieces drift mid-way; sample throughout.
|
||||
6. **Fact verification gate.** Every claim, every quote, every stat verified before publish.
|
||||
7. **AI slop prevention.** Heavy human editing, strong briefs, iteration.
|
||||
8. **Disclosure tiering.** Disclose when origin would change reader trust; calibrate to audience.
|
||||
9. **Team calibration.** Documented policy, calibration sessions, voice library.
|
||||
10. **Tool-agnostic methodology.** Workflow shape stays constant as tools change.
|
||||
11. **Ethical floor.** Intellectual honesty, no fabrication, no hidden AI in trust-sensitive work.
|
||||
12. **Final accountability.** The human who signs off is accountable; AI does not sign off.
|
||||
|
||||
The output of the framework is a workflow document the team can reference: AI participation rules named, hybrid pattern selected, voice preservation patterns specified, disclosure tier set, calibration cadence committed, ethical floor articulated, accountable signer named for each piece.
|
||||
|
||||
---
|
||||
|
||||
## Reference files
|
||||
|
||||
- [`references/ai-participation-boundaries.md`](references/ai-participation-boundaries.md) - Where AI legitimately helps, where humans must own. The boundary list and the "human-in-the-loop is not ownership" distinction.
|
||||
- [`references/hybrid-workflow-patterns.md`](references/hybrid-workflow-patterns.md) - Five workflow patterns with tradeoffs and selection criteria. When each pattern fits production context.
|
||||
- [`references/voice-ownership-preservation.md`](references/voice-ownership-preservation.md) - Voice guidelines as prompt input, sample text as voice anchor, mid-draft voice check, final pass in human voice, reject-the-bland discipline.
|
||||
- [`references/ai-slop-detection-and-avoidance.md`](references/ai-slop-detection-and-avoidance.md) - What produces slop, what prevents it. Cross-references editorial-qa's audit patterns.
|
||||
- [`references/disclosure-and-transparency-patterns.md`](references/disclosure-and-transparency-patterns.md) - Tiered disclosure framework, language patterns, industry norms.
|
||||
- [`references/team-training-and-calibration.md`](references/team-training-and-calibration.md) - Documented policy, calibration sessions, voice library, quality benchmarks, onboarding.
|
||||
- [`references/quality-calibration-with-ai-in-loop.md`](references/quality-calibration-with-ai-in-loop.md) - How editorial standards shift when AI is in the workflow. Same standards, different failure modes.
|
||||
- [`references/ethics-and-intellectual-honesty.md`](references/ethics-and-intellectual-honesty.md) - Training data, attribution, fabrication boundaries, intellectual honesty as the supervening frame.
|
||||
- [`references/common-collaboration-failures.md`](references/common-collaboration-failures.md) - 11+ failure patterns with diagnoses and fixes.
|
||||
|
||||
---
|
||||
|
||||
## Closing: collaboration, not replacement
|
||||
|
||||
AI in content workflows is neither magic nor menace. It is a category of tooling that, like every tooling category before it, rewards disciplined use and punishes careless use. The teams producing memorable AI-assisted content are the ones holding the line on human ownership, voice, fact accuracy, and intellectual honesty. The teams producing AI slop are the ones treating AI as a content factory.
|
||||
|
||||
The discipline is not anti-AI; it is pro-craft. Craft was always what made content worth reading; AI does not change that, it just raises the cost of skipping it.
|
||||
|
||||
When in doubt about whether an AI-assisted workflow is ready, ask: is human ownership specified, are participation boundaries documented, is voice preservation built into the prompt and review patterns, is fact verification a halt-condition, is disclosure tiered to audience trust, is the team calibrated, and is the ethical floor explicit? If yes to all of those, the workflow is ready. If no to any, the gap is where the program will produce slop and lose reader trust.
|
||||
+131
@@ -0,0 +1,131 @@
|
||||
# AI participation boundaries
|
||||
|
||||
Where AI legitimately helps, where humans must own. The boundary list and the "human-in-the-loop is not ownership" distinction.
|
||||
|
||||
The boundary list below is the operational expression of the keystone framing: humans own the content, AI accelerates the work. The list is not exhaustive; the principle is: AI does work the human directs and verifies, AI does not make decisions about what publishes, who is quoted, what is true, or what voice the brand uses.
|
||||
|
||||
---
|
||||
|
||||
## Where AI legitimately participates
|
||||
|
||||
### Research synthesis
|
||||
|
||||
AI condenses long-form sources (papers, interviews, prior reports, internal docs) into a research brief. The writer reads the brief, follows up on the citations the brief surfaced, and verifies anything that will become a load-bearing claim in the piece.
|
||||
|
||||
The acceleration: hours of reading become minutes of reviewing. The retained ownership: the writer judges what is worth using, where the source is questionable, what additional research is needed.
|
||||
|
||||
### Outline generation against a brief
|
||||
|
||||
AI proposes an H2 / H3 structure based on the content brief and SERP analysis. The editor approves the outline, restructures it, or rejects it.
|
||||
|
||||
The acceleration: the writer starts from a structure that fits the brief instead of from a blank page. The retained ownership: the editor decides whether the structure fits the audience and the publication.
|
||||
|
||||
### First-draft generation
|
||||
|
||||
AI produces a draft against an explicit brief. The human edits substantially.
|
||||
|
||||
The acceleration: a 1,500-word draft in minutes that the human revises rather than composing from scratch. The retained ownership: the human chooses what to keep, what to rewrite, what to cut, what to add. A draft that ships unchanged is not collaboration; it is rubber-stamping.
|
||||
|
||||
### Alternative phrasings
|
||||
|
||||
AI offers 3 versions of a sentence, paragraph, or headline. The human picks one or rewrites.
|
||||
|
||||
The acceleration: faster surfacing of options the writer might not have considered. The retained ownership: the writer chooses the option that fits the voice and the context.
|
||||
|
||||
### Copy edit suggestions
|
||||
|
||||
AI catches typos, awkward phrasings, repetition, weak connections between paragraphs.
|
||||
|
||||
The acceleration: faster than a manual copy edit pass. The retained ownership: the editor decides which suggestions to accept; some of what AI flags as awkward is actually deliberate stylistic choice.
|
||||
|
||||
### Summary and abstraction
|
||||
|
||||
AI condenses long pieces into TL;DR summaries, executive summaries, or social media captions.
|
||||
|
||||
The acceleration: faster TL;DR generation; useful for content systems that produce summaries at scale. The retained ownership: the human verifies the summary captures what matters and does not flatten the piece's distinctive points.
|
||||
|
||||
### Transcription
|
||||
|
||||
AI transcribes interview audio. The human verifies the transcription against the audio for accuracy, especially on names, technical terms, and quoted positions.
|
||||
|
||||
The acceleration: hours of transcription become minutes of verification. The retained ownership: the human is responsible for what gets attributed; transcription errors that misquote sources are the human's accountability to catch.
|
||||
|
||||
### Translation drafts
|
||||
|
||||
AI produces a translation draft. A native speaker reviews and corrects.
|
||||
|
||||
The acceleration: a translation starting point in seconds. The retained ownership: the native speaker is the source of truth on idiomatic correctness, cultural context, and brand-voice translation.
|
||||
|
||||
### Quality-control automation at scale
|
||||
|
||||
AI flags pages in a programmatic SEO set that need human review (per `editorial-qa`'s sampling discipline).
|
||||
|
||||
The acceleration: automated check on every page; manual review focused on the flagged subset. The retained ownership: the editor decides what counts as a fail; the AI flags candidates, the human judges.
|
||||
|
||||
### Idea generation
|
||||
|
||||
AI proposes 30 angles on a topic; the human picks 3.
|
||||
|
||||
The acceleration: faster brainstorm. The retained ownership: the human chooses which angles fit the brand and the audience.
|
||||
|
||||
---
|
||||
|
||||
## Where humans must own
|
||||
|
||||
### Editorial judgment
|
||||
|
||||
What to publish, what to kill, what is worth saying. AI cannot decide whether a piece is good enough to ship. The judgment requires audience knowledge, brand context, and quality standards the AI does not have.
|
||||
|
||||
### Voice
|
||||
|
||||
Brand voice, distinctive POV, the way THIS publication sounds different from the next one. AI default voice is generic by construction; voice is a human contribution that the AI can mimic if shown samples but cannot originate.
|
||||
|
||||
### Fact verification
|
||||
|
||||
Every claim, every statistic, every quote, every named person. AI hallucinates plausible-but-fake claims; humans verify against authoritative sources. Fact verification is a halt-condition gate; pieces with unverified claims do not ship.
|
||||
|
||||
### Ethical decisions
|
||||
|
||||
What is appropriate to publish, what is harmful, what crosses lines, what disclosure is required. Ethics requires context, audience awareness, and accountability that the AI does not carry.
|
||||
|
||||
### Reader empathy
|
||||
|
||||
What the reader actually needs from this piece, not what the algorithm scores well. The reader's situation, knowledge, and emotional context shape the piece's job; the AI cannot model the specific reader the way a writer who has spent time with the audience can.
|
||||
|
||||
### Quote attribution
|
||||
|
||||
Real people who actually said the thing, with consent where relevant. AI hallucinates quotes; humans verify against the source.
|
||||
|
||||
### Tone calibration on hard topics
|
||||
|
||||
Grief, illness, sensitive history, contested politics. AI defaults to anodyne; humans calibrate to context. A piece on bereavement should not read as if a chatbot wrote it.
|
||||
|
||||
### Narrative arc
|
||||
|
||||
How the piece unfolds, where the reader's attention goes, what the climax is, what the resolution is. AI produces shapes; humans choose them.
|
||||
|
||||
### Final approval
|
||||
|
||||
The human who signs off is accountable for what shipped. Accountability cannot be delegated to AI; the byline and the editorial chain stop at humans.
|
||||
|
||||
---
|
||||
|
||||
## "Human in the loop" is not ownership
|
||||
|
||||
The phrase "human in the loop" appears in many AI workflows. It is necessary but insufficient.
|
||||
|
||||
A human briefly reviewing AI-generated content before publish is not ownership; it is rubber-stamping. The piece's substance, voice, and judgment are still AI-produced; the human's role is signature only.
|
||||
|
||||
Ownership requires the human to have made the actual decisions the piece embodies. Specifically: the human chose the angle, the human verified the facts, the human enforced the voice, the human made the editorial judgment calls that distinguish this piece from the AI's default output.
|
||||
|
||||
The test. Could the human defend every claim, every position, and every word in the piece? If yes, the human owns it. If no, the human is rubber-stamping.
|
||||
|
||||
---
|
||||
|
||||
## Methodology-level choices that stay in the public skill
|
||||
|
||||
The list of where AI legitimately participates, the list of where humans must own, the "human-in-the-loop versus ownership" distinction, the verification-and-defense litmus test.
|
||||
|
||||
## Implementation choices that stay internal
|
||||
|
||||
The specific AI tools the team uses for each participation category (research synthesis tool, drafting tool, copy edit tool, transcription tool, translation tool, QC automation tool). The specific prompts the team has developed for each task category. The specific tracking system that records which AI participated in which piece. The specific review workflows that gate publish. These vary by team and stack.
|
||||
Vendored
+134
@@ -0,0 +1,134 @@
|
||||
# AI slop detection and avoidance
|
||||
|
||||
What produces slop, what prevents it. Cross-references editorial-qa's audit patterns.
|
||||
|
||||
AI slop is the term of art for AI-generated content that is technically functional but reads as generic, derivative, and signal-less. The detection patterns live in `editorial-qa/references/ai-content-audit-patterns.md`. This reference addresses prevention: what production patterns produce slop, what production patterns prevent it.
|
||||
|
||||
---
|
||||
|
||||
## Patterns that produce slop
|
||||
|
||||
### AI does too much of the work
|
||||
|
||||
The pattern. The AI generates the entire piece; the human glances at it and ships. The piece reads as model-default because no human substantively rewrote it.
|
||||
|
||||
The signal. Pieces ship in less time than they would take a human to write from scratch. Speed is not the problem; the problem is that the speed comes from skipped craft.
|
||||
|
||||
### Generic prompts
|
||||
|
||||
The pattern. The prompt is "write a 1,500-word blog post about X." No brand voice, no audience specificity, no anti-pattern guidance. The AI generates the most common kind of post about X, which is by definition generic.
|
||||
|
||||
The signal. Prompts can fit in one sentence. Prompts that produce on-voice output are typically multi-paragraph, with voice guidelines, sample text, audience description, and anti-pattern lists.
|
||||
|
||||
### No editorial judgment in the loop
|
||||
|
||||
The pattern. The workflow is "AI generates, human reviews quickly, ship." The reviewer is not making editorial decisions; they are spell-checking. Whether the piece is good enough to publish, whether it answers the user's actual question, whether it reflects brand POV are not asked.
|
||||
|
||||
The signal. The team cannot articulate the editorial judgments made on a piece because those judgments did not happen. Pieces ship with no halt-decisions, no rewrites, no "this piece does not work, kill it" calls.
|
||||
|
||||
### Volume prioritized over quality
|
||||
|
||||
The pattern. The team commits to publishing 50 pieces a month with the same headcount that previously produced 10. AI is the multiplier. Quality drops because the production line cannot sustain craft at the new volume.
|
||||
|
||||
The signal. Publish targets defined in pieces-per-week or pages-per-month. Quality-controlled publish targets are defined differently: traffic earned, citations earned, leads converted, audience grown. Volume targets without quality targets produce slop volume.
|
||||
|
||||
### No iteration
|
||||
|
||||
The pattern. First draft (AI-generated) ships. No revision pass. No second draft. No "let us read this aloud and rewrite the bland sections."
|
||||
|
||||
The signal. The workflow document does not include a rewrite step. Production is generation-then-publish, not generation-then-iteration-then-publish.
|
||||
|
||||
---
|
||||
|
||||
## Patterns that prevent slop
|
||||
|
||||
### Strong briefs
|
||||
|
||||
Per `content-brief-authoring`. A brief that fills all 12 fields gives the AI enough context to produce a draft that respects audience, voice, structure, entity coverage, and success criteria. Vague briefs produce slop output regardless of how the AI is prompted.
|
||||
|
||||
The discipline. Brief-adherence is the first QA gate per `editorial-qa`. AI drafts that fail brief-adherence get returned, not rubber-stamped.
|
||||
|
||||
### Voice guidelines as prompt context
|
||||
|
||||
Per `voice-ownership-preservation.md`. Every AI generation includes the brand voice guidelines and sample anchor text as prompt input. Without active voice prompting, AI defaults dominate.
|
||||
|
||||
### Heavy human editing pass
|
||||
|
||||
The discipline. The human spends substantial time editing AI drafts: rewriting flat sentences, replacing abstractions with specifics, restoring brand voice in mid-piece sections, replacing generic openings and closings with specific ones.
|
||||
|
||||
The time investment. 50 to 60% of the piece's production time goes to human editing in Pattern 1 (AI-first draft, human-edit-heavy). Lower than that and the editing is light; the piece ships with AI defaults preserved.
|
||||
|
||||
### Iteration
|
||||
|
||||
The discipline. The workflow includes multiple revision passes: AI draft, then human rewrite, then AI suggestions for the rewrite, then human final pass. Each pass catches a different layer.
|
||||
|
||||
- AI draft: structure, completeness, basic prose.
|
||||
- Human rewrite: voice, specificity, claim verification, distinctive POV.
|
||||
- AI suggestions: copy edit catches, alternative phrasings, repetition flagging.
|
||||
- Human final: closing voice, emotional register, final polish.
|
||||
|
||||
The pattern produces work that reads as human-crafted with AI assistance. Skip any pass and the piece moves toward AI default.
|
||||
|
||||
### Editorial judgment at every gate
|
||||
|
||||
The discipline. Each QA gate is a judgment moment, not a rubber stamp. Brief-adherence asks "did this piece execute the brief?" Voice consistency asks "does this sound like our brand?" Fact accuracy asks "is every claim verified?" Each question requires a human's actual judgment.
|
||||
|
||||
The signal of editorial judgment in action. Halts happen. Pieces get sent back for revision. Some pieces get killed because they cannot be made to work. Programs that publish 100% of what they draft are not exercising editorial judgment; they are producing whatever the workflow ships.
|
||||
|
||||
---
|
||||
|
||||
## The reader-detection problem
|
||||
|
||||
Readers can often sense AI-flavored content even when they cannot articulate why. The signals.
|
||||
|
||||
- Generic openings that could be the opening of any article on the topic
|
||||
- Predictable structure (intro, three points, conclusion)
|
||||
- Bullet-list overuse where prose would serve
|
||||
- "Perfect" grammar that reads as emotionally flat
|
||||
- Specific-but-fake details (named decimals, named sources that turn out to be fake)
|
||||
- Hedge stacking that avoids commitment
|
||||
|
||||
Slop loses reader trust over time even when individual pieces are not penalized by algorithm updates. Readers stop returning. Email open rates drop. Citation quality declines. The traffic numbers may hold for a year before the trust loss compounds visibly.
|
||||
|
||||
The implication. Slop is not a search-engine problem; it is a reader-trust problem. Programs that optimize away from slop because of algorithm fear are missing the bigger reason: readers stop trusting the brand.
|
||||
|
||||
---
|
||||
|
||||
## The slop avoidance audit
|
||||
|
||||
For each AI-assisted piece, ask the following before publish.
|
||||
|
||||
1. Could this piece have been published by any competitor using the same tools? If yes, the voice is not preserved.
|
||||
2. Are the claims in this piece specific enough to verify? If no, the piece is hedging.
|
||||
3. Does the piece take a position the reader will remember? If no, the piece is forgettable.
|
||||
4. Did the human substantially rewrite, or is the AI draft mostly intact? If mostly intact, the piece is at slop risk.
|
||||
5. Does the closing read as the writer's own voice? If no, the final pass was skipped.
|
||||
6. Did the brief adhere to the 12-field discipline? If no, the failure is upstream.
|
||||
|
||||
A piece that fails 3+ of these is slop-shaped. Halt and revise.
|
||||
|
||||
---
|
||||
|
||||
## The "we are producing 10x more content but the same audience growth" pattern
|
||||
|
||||
A common signal that slop has set in. The volume increased; the audience metric did not. The team often interprets this as "we need even more content"; the diagnosis is usually the opposite.
|
||||
|
||||
The actual diagnosis. Volume was not the constraint. Quality was. The 10x content production has produced 10x slop, which earns less per piece and sometimes hurts the brand's overall trust signal.
|
||||
|
||||
The fix. Reduce volume; increase per-piece quality. Counter-intuitive but empirically the pattern that recovers audience growth. The reduced-volume program with higher craft per piece outperforms the high-volume slop program in audience metrics within 6 to 12 months.
|
||||
|
||||
---
|
||||
|
||||
## Cross-reference
|
||||
|
||||
The detection patterns (AI tells, hallucination patterns, voice drift) live in `editorial-qa/references/ai-content-audit-patterns.md`. The avoidance patterns (production discipline) live here. The two skills compose: editorial-qa catches what reaches the gate; this skill prevents production patterns that produce slop in the first place.
|
||||
|
||||
---
|
||||
|
||||
## Methodology-level choices that stay in the public skill
|
||||
|
||||
The patterns that produce slop, the patterns that prevent slop, the reader-detection observation, the 6-question slop avoidance audit, the volume-vs-quality counter-intuition, the cross-reference to editorial-qa.
|
||||
|
||||
## Implementation choices that stay internal
|
||||
|
||||
The specific iteration loop the team runs (AI draft to human rewrite to AI suggestions to human final, or variations). The specific time-tracking that captures the editing-time-to-generation-time ratio. The specific prompt patterns that include voice guidelines and sample text. The specific reader-feedback channels that surface slop perception. These vary by team and tooling.
|
||||
Vendored
+165
@@ -0,0 +1,165 @@
|
||||
# Common collaboration failures
|
||||
|
||||
11+ failure patterns with diagnoses and fixes. Cross-references to other reference files where applicable.
|
||||
|
||||
The pattern across most failures: the team treated AI as either a magic content factory (producing slop at scale) or as a pure-replacement-or-nothing question (producing inconsistent output as writers privately negotiated their own AI usage). The discipline is in between: humans own, AI accelerates, the workflow is documented, the team is calibrated.
|
||||
|
||||
---
|
||||
|
||||
## "We used AI and the content feels generic"
|
||||
|
||||
**Symptom.** Pieces ship technically clean but feel indistinguishable from competitors using the same tools. Audience growth flat despite consistent publishing.
|
||||
|
||||
**Diagnosis.** Voice not preserved. Editing was light; AI defaults reached publish. The pattern that produces this: AI-first drafts with a quick review pass that catches typos but does not rewrite for voice.
|
||||
|
||||
**Fix.** Apply the voice ownership preservation patterns (`voice-ownership-preservation.md`): voice guidelines as prompt input, sample text as voice anchor, mid-draft voice check, final pass in human voice, reject-the-bland audit. Increase editing intensity to 50-60% of production time.
|
||||
|
||||
---
|
||||
|
||||
## "Hallucinated facts made it to publish"
|
||||
|
||||
**Symptom.** A statistic, quote, citation, or product claim in a published piece turns out to be invented.
|
||||
|
||||
**Diagnosis.** Fact-verification gate skipped or rushed. The team trusted AI output that read as authoritative.
|
||||
|
||||
**Fix.** Fact-accuracy as halt-condition gate per `editorial-qa/references/fact-accuracy-and-citation-discipline.md`. Verification methodology that traces every claim to a primary source. Pattern recognition for the 6 hallucination patterns.
|
||||
|
||||
---
|
||||
|
||||
## "Different writers produce wildly different AI-assisted output"
|
||||
|
||||
**Symptom.** Two writers given the same brief and the same AI tools produce pieces that read as if they came from two different programs.
|
||||
|
||||
**Diagnosis.** No team calibration. Each writer developed their own AI patterns; the program drifted as different patterns produced different output shapes.
|
||||
|
||||
**Fix.** Documented AI policy, calibration sessions, voice library, quality benchmarks per `team-training-and-calibration.md`. Onboarding for new writers includes calibration.
|
||||
|
||||
---
|
||||
|
||||
## "Our AI-assisted SEO content got penalized"
|
||||
|
||||
**Symptom.** A programmatic SEO set or a high-volume editorial program loses 60-90% of traffic in an algorithm update.
|
||||
|
||||
**Diagnosis.** Slop volume plus thin templates plus no QA discipline. The set was generating filler pages with limited human direction; the algorithm update detected the scale-without-substance pattern.
|
||||
|
||||
**Fix.** Halt new generation. Apply QA at scale per `editorial-qa/references/qa-at-scale-patterns.md`. Sampling discipline with 5% failure threshold. Noindex pages that fail the data-depth threshold. Possibly remove the entire pSEO surface and rebuild from a stronger data source.
|
||||
|
||||
---
|
||||
|
||||
## "We can't tell what was AI vs human"
|
||||
|
||||
**Symptom.** Asked to characterize AI usage on a specific piece, the team cannot answer. Workflow logs, CMS metadata, and writer recall all yield uncertain answers.
|
||||
|
||||
**Diagnosis.** No AI usage tracking. The workflow does not capture which AI participated in which stage.
|
||||
|
||||
**Fix.** Add AI involvement tracking to the production workflow. The metadata captures: which workflow pattern was used, which AI tools were involved, which stages, which prompts (or prompt template versions), which human made which decisions. The tracking is the input to retrospective audits and to disclosure decisions.
|
||||
|
||||
---
|
||||
|
||||
## "Readers complained about AI-flavored content"
|
||||
|
||||
**Symptom.** Direct audience feedback (comments, support tickets, social mentions) flags content as feeling AI-generated.
|
||||
|
||||
**Diagnosis.** Slop reaching the audience. Reader detection is real even when the team's QA does not catch it.
|
||||
|
||||
**Fix.** Intensify the human craft pass. Audit recent pieces against the slop avoidance audit (`ai-slop-detection-and-avoidance.md`). If multiple pieces fail the audit, the production patterns need to shift: heavier human editing, more rejection-of-bland, possibly pattern shift from AI-first to AI-as-editor for higher-trust content.
|
||||
|
||||
---
|
||||
|
||||
## "We disclosed AI usage and lost credibility"
|
||||
|
||||
**Symptom.** Team added AI disclosure to a piece; audience response shifted negative.
|
||||
|
||||
**Diagnosis.** Could be either:
|
||||
|
||||
- The disclosure was for content where audience norms expect human authorship (Tier 1 or Tier 2 content per the disclosure framework); disclosure was correct but audience trust calibration is moving slowly
|
||||
- The disclosure language was hedging or defensive, signaling lower commitment than direct authorship would have
|
||||
- The disclosure was for content where it was unnecessary (Tier 4); the disclosure created an issue where there was none
|
||||
|
||||
**Fix.** Calibrate disclosure to audience norms per `disclosure-and-transparency-patterns.md`. Specific language matters; defensive language reads worse than no disclosure. Consider audience-research feedback to inform per-content-type disclosure tiering.
|
||||
|
||||
---
|
||||
|
||||
## "Our AI tools changed and our content shifted"
|
||||
|
||||
**Symptom.** Team updates the AI tool or model version. Output behavior changes. Content quality shifts before the team recalibrates.
|
||||
|
||||
**Diagnosis.** Over-coupled to one tool's specific behavior. The methodology should be tool-agnostic; the team's prompts and patterns should produce similar output across tools.
|
||||
|
||||
**Fix.** Methodology-first calibration. The voice library, prompt templates, and quality benchmarks should be portable across tools. After tool changes, run a calibration session against the new tool to verify the methodology still produces on-voice output. If the methodology no longer works, that is a signal the methodology was over-coupled to tool-specific behavior.
|
||||
|
||||
---
|
||||
|
||||
## "We're producing 10x more content but the same audience growth"
|
||||
|
||||
**Symptom.** Team committed to a 10x content target enabled by AI. Volume hit the target. Audience growth flat or declining.
|
||||
|
||||
**Diagnosis.** Volume was not the constraint that was binding. Quality was. The 10x volume produced 10x slop, which earns less per piece.
|
||||
|
||||
**Fix.** Reduce volume; increase per-piece quality. Counter-intuitive but empirically the pattern that recovers audience growth. The reduced-volume program with higher craft per piece outperforms the high-volume slop program in audience metrics within 6 to 12 months.
|
||||
|
||||
---
|
||||
|
||||
## "The team is using AI inconsistently"
|
||||
|
||||
**Symptom.** Team members use different AI tools in different patterns for the same kind of work. Output varies by who picked up the assignment.
|
||||
|
||||
**Diagnosis.** Calibration sessions overdue. Either the policy is informal (no documented standards) or the documented policy has not been reinforced through calibration.
|
||||
|
||||
**Fix.** Quarterly calibration sessions. Tool standardization (or intentional pluralism with documented selection criteria). Onboarding refresh. The cadence is calendar-anchored.
|
||||
|
||||
---
|
||||
|
||||
## "An expert byline turned out to be substantially AI-drafted"
|
||||
|
||||
**Symptom.** A piece bylined by a named expert is publicly identified as substantially AI-drafted (sometimes by AI-detection tools, sometimes by readers familiar with the expert's actual voice).
|
||||
|
||||
**Diagnosis.** Ethics breach. The byline implied human authorship; AI authorship was substantive; the gap between claim and reality reached the audience.
|
||||
|
||||
**Fix.** Two parts.
|
||||
|
||||
- **Immediate.** Correct the published piece (issue an editor's note clarifying the workflow, possibly retract and republish with appropriate disclosure). Apologize where appropriate. Recalibrate.
|
||||
- **Process.** Restore the ethical floor: bylined expert content requires substantial human authorship. Recalibrate the team. Update the AI policy to document the floor explicitly.
|
||||
|
||||
The fix is not "stop using AI." The fix is using AI consistently with the byline's implied authorship.
|
||||
|
||||
---
|
||||
|
||||
## "Our AI policy is 18 months stale and references tools we no longer use"
|
||||
|
||||
**Symptom.** Team consults the AI policy doc; the doc references tools the team migrated away from a year ago. The doc is treated as not authoritative because it is obviously dated.
|
||||
|
||||
**Diagnosis.** Policy review cadence has slipped. The doc has not been updated as tools, capabilities, and team practices have evolved.
|
||||
|
||||
**Fix.** Quarterly policy review. Each quarter the policy gets reviewed against current practice; updates ship; the team is briefed on the changes. The policy is a living document; staleness signals process failure.
|
||||
|
||||
---
|
||||
|
||||
## "The team feels guilty about AI use but uses it anyway"
|
||||
|
||||
**Symptom.** Team members use AI substantively but do not document, do not discuss in calibration sessions, do not include in retrospectives. AI usage is treated as something to hide.
|
||||
|
||||
**Diagnosis.** The team has not articulated its AI ethics. Without articulation, individual writers privately negotiate their own ethics; the team accumulates ethical debt.
|
||||
|
||||
**Fix.** Run an ethics conversation explicitly. Articulate the team's position on the six ethical floors per `ethics-and-intellectual-honesty.md`. Document where AI is used substantively. Make the workflow visible. Guilt is usually a signal of unresolved ethical questions; the resolution is articulation, not avoidance.
|
||||
|
||||
---
|
||||
|
||||
## The pattern across all failures
|
||||
|
||||
Most AI-collaboration failures reduce to two patterns.
|
||||
|
||||
1. **The team treated AI as a magic content factory.** Outcome: slop, hallucinations, voice loss, audience trust decline.
|
||||
2. **The team failed to articulate its AI workflow explicitly.** Outcome: drift, inconsistency, ethics debt, calibration failures.
|
||||
|
||||
The fix in both cases is the same: explicit articulation of where AI participates, where humans own, what the discipline looks like in practice, and what the team's ethical floors are. The articulation is the work; once the work is done, individual failures become per-piece corrections rather than program-level breakdowns.
|
||||
|
||||
---
|
||||
|
||||
## Methodology-level choices that stay in the public skill
|
||||
|
||||
The 12 failure patterns above, the diagnosis-and-fix structure, the cross-references to other reference files, the underlying-pattern observation about magic-factory thinking and unarticulated workflows.
|
||||
|
||||
## Implementation choices that stay internal
|
||||
|
||||
The specific tracking system the team uses for AI usage. The specific calibration session cadence. The specific ethics-policy doc and its review process. The specific tool selections and their rationale. These vary per team and brand.
|
||||
Vendored
+170
@@ -0,0 +1,170 @@
|
||||
# Disclosure and transparency patterns
|
||||
|
||||
Tiered disclosure framework, language patterns, industry norms.
|
||||
|
||||
When should AI usage be disclosed to readers? The answer is not "always" or "never"; it is "calibrate to context." The framework below tiers disclosure decisions by trust sensitivity.
|
||||
|
||||
---
|
||||
|
||||
## The tiered framework
|
||||
|
||||
Four tiers, ordered by disclosure obligation.
|
||||
|
||||
### Tier 1: Always disclose
|
||||
|
||||
AI usage is disclosed regardless of how light the involvement was.
|
||||
|
||||
**Categories.**
|
||||
|
||||
- Journalism and news reporting (any AI involvement, any extent)
|
||||
- Bylined expert opinion (where the byline implies human authorship of the argument)
|
||||
- Content where AI tools are themselves the subject (transparency about methodology is part of the topic)
|
||||
- Regulated industries with explicit AI disclosure requirements (financial advice, medical content, legal content in some jurisdictions)
|
||||
|
||||
**Reasoning.** In these categories, the reader's understanding of the content's origin is load-bearing for trust. A news story partially AI-drafted reads differently from a story fully reported and written by a journalist; readers have a right to that information.
|
||||
|
||||
### Tier 2: Default disclosure (consider context)
|
||||
|
||||
Disclosure is the default; opting out requires a specific reason.
|
||||
|
||||
**Categories.**
|
||||
|
||||
- Thought leadership pieces where the byline carries trust value
|
||||
- Content that influences purchase decisions (reviews, comparisons, recommendations)
|
||||
- Content for trust-sensitive audiences (academia, enterprise procurement, professional services)
|
||||
- Long-form pieces where the audience has reasonable expectation of human craft
|
||||
|
||||
**Reasoning.** Readers in these contexts often assume human authorship; AI involvement that is undisclosed becomes a trust violation if discovered. Disclosure is cheap; the trust hit from undisclosed-then-discovered AI involvement is expensive.
|
||||
|
||||
### Tier 3: Generally not necessary
|
||||
|
||||
Disclosure is allowed but not required by audience expectations.
|
||||
|
||||
**Categories.**
|
||||
|
||||
- Marketing copy (web pages, ad copy, email marketing copy)
|
||||
- Descriptive product content (product descriptions, spec listings)
|
||||
- Programmatic data pages (where the page is obviously data-generated)
|
||||
- Internal team content (memos, internal reports)
|
||||
- Copy edit assistance only (the human wrote the piece; AI suggested edits)
|
||||
|
||||
**Reasoning.** In these categories, audience expectations do not assume specific authorship. Readers recognize the genre as functional content; AI involvement does not violate trust the way it would in a thought leadership piece.
|
||||
|
||||
### Tier 4: Clearly fine without disclosure
|
||||
|
||||
Disclosure is unnecessary and would feel weird if present.
|
||||
|
||||
**Categories.**
|
||||
|
||||
- AI as research assistant (the AI condensed sources; the human wrote)
|
||||
- AI for transcription only (the human is the writer; the AI was a typist)
|
||||
- AI for spelling and grammar suggestions (copy edit role only)
|
||||
- AI as brainstorming partner where the human took the ideas and wrote independently
|
||||
|
||||
**Reasoning.** The AI's role was so light that disclosure would imply more involvement than there was. Readers would interpret a disclosure as misleading.
|
||||
|
||||
---
|
||||
|
||||
## Language patterns
|
||||
|
||||
When disclosure is used, the language matters.
|
||||
|
||||
### Patterns that work
|
||||
|
||||
> "AI tools assisted in research and drafting; the author edited and verified all claims."
|
||||
|
||||
> "This piece was generated programmatically from [data source]; reviewed by [team] before publish."
|
||||
|
||||
> "The author drafted this piece; AI tools were used for copy edit suggestions."
|
||||
|
||||
> "Research synthesis assisted by AI; all sources verified by the author."
|
||||
|
||||
The patterns share three features: they specify what AI did, they specify what humans did, they identify the accountability party.
|
||||
|
||||
### Patterns to avoid
|
||||
|
||||
- **Hedge language.** "May have used AI" or "could have been AI-assisted" reads as covering legal bases without committing to honesty. Be specific or omit.
|
||||
- **Disclosure that minimizes.** "AI was minimally involved" is hedging; either AI was substantively involved (disclose substantively) or it was not (no disclosure needed for Tier 4 use).
|
||||
- **Disclosure that overstates.** "Fully written by AI" when humans rewrote 50% is dishonest in the other direction. The disclosure should match the actual AI involvement.
|
||||
|
||||
### Where to place disclosure
|
||||
|
||||
- **Footer or byline area.** Standard placement; readers find disclosure where they expect it.
|
||||
- **Inline at relevant points.** When AI involvement varies across a piece, inline notes are clearer than a single footer note.
|
||||
- **Methodology section.** Long pieces with substantial AI involvement benefit from a "How this piece was produced" section that explains the workflow.
|
||||
|
||||
---
|
||||
|
||||
## Industry norms
|
||||
|
||||
Disclosure norms vary by industry. The principle of intellectual honesty is constant; the specific expectations differ.
|
||||
|
||||
**Journalism.** Major journalism organizations have published explicit AI usage standards. The norm is moving toward disclosure of AI involvement in any reported piece. Journalism trust depends on transparency; AI-related opacity is a fast trust violation in the audience.
|
||||
|
||||
**Content marketing.** Norms are weaker but moving toward disclosure for high-trust pieces. Branded thought leadership is increasingly expected to disclose AI involvement; routine marketing copy is not.
|
||||
|
||||
**Academic and research content.** AI involvement in research papers is a contested area; conferences and journals have varying policies. The conservative default is full disclosure, including which AI tools were used and at what stages.
|
||||
|
||||
**Regulated industries.** Financial, medical, and legal content increasingly carries explicit AI disclosure requirements. The defaults here are tighter than in unregulated marketing content; consult the specific regulatory environment.
|
||||
|
||||
**Ecommerce and product content.** Disclosure is generally not expected on product descriptions or spec listings. AI generation is genre-typical; readers do not interpret presence or absence of disclosure as meaningful.
|
||||
|
||||
---
|
||||
|
||||
## When disclosure helps and when it hurts
|
||||
|
||||
The honest framing. Disclosure is sometimes a trust gain, sometimes a trust loss; the calibration depends on audience norms.
|
||||
|
||||
**Disclosure as trust gain.**
|
||||
|
||||
- Audience expects human authorship; disclosure preempts trust loss from later discovery
|
||||
- Brand positions itself on transparency
|
||||
- Industry is moving toward disclosure as the new norm
|
||||
- The piece's value is in research and verification, which AI assisted but did not replace
|
||||
|
||||
**Disclosure as trust loss.**
|
||||
|
||||
- Audience interprets AI involvement as quality reduction (sometimes a misreading, sometimes accurate)
|
||||
- Disclosure language reads as defensive or hedging
|
||||
- Audience expects routine content (where AI is genre-typical)
|
||||
|
||||
The decision is not "always disclose" or "never disclose" but "calibrate." The calibration is best done by someone who knows the audience and the brand's positioning, not by a generic policy.
|
||||
|
||||
---
|
||||
|
||||
## Disclosure policy at the program level
|
||||
|
||||
The program-level discipline. Document the disclosure policy by content type. Editors and writers know which content types require disclosure; the disclosure language is templated; the policy is reviewed quarterly.
|
||||
|
||||
**Template policy structure.**
|
||||
|
||||
- Content type: [thought leadership]. Disclosure: [required]. Language template: [template].
|
||||
- Content type: [knowledge base article]. Disclosure: [optional]. Language template: [template if used].
|
||||
- Content type: [programmatic data page]. Disclosure: [not required].
|
||||
- Content type: [marketing landing page]. Disclosure: [not required].
|
||||
|
||||
The policy gets updated as norms evolve. AI disclosure norms in 2026 are looser than they will be in 2028; policy review keeps the program aligned with audience expectations.
|
||||
|
||||
---
|
||||
|
||||
## When the disclosure decision is hard
|
||||
|
||||
Edge cases.
|
||||
|
||||
**Long-running expert byline.** A column under a named expert's byline, where some pieces are pure expert authorship and others are substantively AI-assisted. Disclosure on the AI-assisted pieces is the right call; the byline's trust value depends on it.
|
||||
|
||||
**Pillar content with mixed authorship.** A pillar piece where the lede is human-written, the body is AI-drafted-then-rewritten, the closing is human-written. Disclosure language can specify the mix: "Research and core argument by the author; AI assisted in initial drafting of body sections; all claims verified."
|
||||
|
||||
**Internal-only content that becomes external.** An internal report that gets externalized requires retroactive disclosure if the internal version was AI-assisted. Sometimes the externalization should include rewriting to bring the disclosure inline.
|
||||
|
||||
The principle. When the disclosure decision is hard, default to disclosure. Trust is recoverable from over-disclosure; trust is not always recoverable from under-disclosure.
|
||||
|
||||
---
|
||||
|
||||
## Methodology-level choices that stay in the public skill
|
||||
|
||||
The four-tier framework, the disclosure language patterns, the industry norms summary, the trust-gain-vs-trust-loss calibration, the program-level policy structure, the edge-case handling.
|
||||
|
||||
## Implementation choices that stay internal
|
||||
|
||||
The specific disclosure language the team has developed for each content type. The specific tracking that records AI involvement per piece (workflow log, CMS metadata, byline annotation). The specific review cadence for the disclosure policy. The specific audience-research feedback that informs disclosure norms for the brand's specific audience. These vary by team, brand, and industry.
|
||||
Vendored
+154
@@ -0,0 +1,154 @@
|
||||
# Ethics and intellectual honesty
|
||||
|
||||
Training data, attribution, fabrication boundaries, intellectual honesty as the supervening frame.
|
||||
|
||||
This is the most ethically loaded reference in the catalog. The voice is honest, pragmatic, non-preachy. The catalog itself is produced with AI assistance; pretending otherwise would render any anti-AI position hypocritical. The position is not "AI use is unethical" but "intellectual honesty about AI involvement is non-negotiable."
|
||||
|
||||
---
|
||||
|
||||
## Training data realities
|
||||
|
||||
Every major LLM in 2026 was trained on copyrighted material. That is the simple ethical reality.
|
||||
|
||||
The legal status of training-data copyright is contested in multiple jurisdictions and is being litigated. The position the catalog takes is not "AI training is ethical" or "AI training is unethical"; the position is "the question is unresolved, the tools exist, teams use them, the way to use them ethically is the question this skill addresses."
|
||||
|
||||
What this skill does not relitigate. The training-data copyright question. The compute-intensity environmental question. The labor-displacement question. These are real ethical questions; this skill is not the place to resolve them. Teams reading this skill make their own choices about whether to use AI tools at all; the skill addresses how to use them with intellectual honesty when teams have made the use-AI choice.
|
||||
|
||||
---
|
||||
|
||||
## Don't pass AI work as fully human-written
|
||||
|
||||
The first ethical floor.
|
||||
|
||||
Bylined content where the byline implies human craft requires substantial human craft. A column under a named expert's byline that is substantially AI-drafted is a trust violation regardless of whether disclosure was technically present somewhere on the page. The byline's value depends on the audience's understanding that the named human authored the piece; AI authorship that the byline obscures is dishonest.
|
||||
|
||||
What "substantial human craft" requires.
|
||||
|
||||
- The argument is the human's
|
||||
- The voice is recognizable as the human's
|
||||
- The judgments about what to include, what to cut, what to emphasize are the human's
|
||||
- The fact verification is the human's
|
||||
- The final approval is the human's
|
||||
|
||||
What it does not require. Every word being typed by the human (research-assistant patterns are fine). Every sentence being unrewritten (copy edit assistance is fine). The human spending a specific time-on-task (the time matters less than the substance).
|
||||
|
||||
---
|
||||
|
||||
## Don't claim AI didn't help when it did
|
||||
|
||||
The second ethical floor.
|
||||
|
||||
False denials are worse than disclosure. A team that uses AI substantially and then claims the work is fully human is staking trust on a falsifiable claim. Discovery of the AI involvement (which becomes more reliable each year as detection tools improve) compounds the trust violation: the audience now distrusts both the work and the team's honesty about the work.
|
||||
|
||||
The honest pattern. If AI was used in any way that would matter to the audience, the team is honest about it. The disclosure tiering framework (per `disclosure-and-transparency-patterns.md`) addresses when disclosure is required; the no-false-denial floor is broader: even when disclosure is not required, false denial is not allowed.
|
||||
|
||||
In practice. Most teams do not face direct denial questions; the issue comes up in interview contexts ("how do you produce your content?"), retrospectives, or conversations with clients and partners. The honest answer in those contexts is the truthful one, even when no public disclosure was attached to specific pieces.
|
||||
|
||||
---
|
||||
|
||||
## Don't generate content that closely mirrors copyrighted source material
|
||||
|
||||
The third ethical floor.
|
||||
|
||||
AI tools can produce near-replicas of training data when prompted carelessly. The team's responsibility is to verify that AI-generated content is original work and not a paraphrase of a specific copyrighted source.
|
||||
|
||||
The check. For each substantive section of AI-generated content, search for the unique phrasing in quoted form. If results come back to a specific copyrighted source that the AI was likely trained on, the section is too close to source material. Revise.
|
||||
|
||||
The pattern. AI tools tend to mirror training data more closely on niche topics than on common topics. Common topics have many sources to blend; niche topics have fewer. Specialized content (academic topics, technical documentation, industry-specific niches) needs more careful mirroring checks.
|
||||
|
||||
---
|
||||
|
||||
## Attribute when borrowing
|
||||
|
||||
The fourth ethical floor.
|
||||
|
||||
Ideas, frameworks, statistics, and specific phrasings that came from identifiable sources get cited. The principle is not changed by whether AI surfaced the source or whether the human did; attribution belongs to the source, not to the discovery method.
|
||||
|
||||
The pattern.
|
||||
|
||||
- Statistics with sources: cite the source.
|
||||
- Frameworks attributed to specific thinkers: cite the thinker.
|
||||
- Specific arguments traceable to a specific publication: cite the publication.
|
||||
- Common knowledge: no citation needed, but verify it actually is common knowledge and not specialized knowledge that the AI surfaced from a specific source.
|
||||
|
||||
The honesty test. If the team would feel uncomfortable having the source's author read the piece and recognize their work uncited, citation is required.
|
||||
|
||||
---
|
||||
|
||||
## Don't fabricate quotes or expertise
|
||||
|
||||
The fifth ethical floor.
|
||||
|
||||
Hallucinated quotes attributed to real people are dishonest regardless of whether AI generated them. The team is accountable for what gets attributed; the AI is not the accountable party.
|
||||
|
||||
The pattern. AI generates plausible-but-fake quotes in 2026; that is a known limitation. The fact-accuracy gate per `editorial-qa` catches them before publish. The ethical position is broader than the QA position: even if a fabricated quote were never caught, generating it under attribution to a real person is dishonest.
|
||||
|
||||
The same applies to expertise claims. AI-drafted "expert content" attributed to a named expert who did not draft it is fabricated expertise. The expert's name carries trust value; the trust depends on the expert having actually drafted the piece.
|
||||
|
||||
---
|
||||
|
||||
## Be honest about AI capabilities and limits
|
||||
|
||||
The sixth ethical floor.
|
||||
|
||||
Do not oversell AI as more capable than it is. Do not undersell it as less capable than it is. Both produce decision-making errors in the team and in the audience.
|
||||
|
||||
The pattern. AI in 2026 is genuinely useful for research synthesis, drafting against briefs, copy edit suggestions, transcription, summary, and quality-control automation at scale. AI in 2026 is genuinely limited at editorial judgment, fact verification (it is what gets fact-checked, not what does fact-checking), voice origination, ethical decisions, and reader empathy.
|
||||
|
||||
Teams that get this right calibrate AI use to the limits. Teams that oversell AI ship work that exceeds AI's actual capabilities and produces hallucinations or voice failures. Teams that undersell AI miss productivity gains the technology offers.
|
||||
|
||||
---
|
||||
|
||||
## The intellectual honesty frame
|
||||
|
||||
The frame that supersedes specific policy debate.
|
||||
|
||||
The question is not "is AI use ethical?" The question is "can the team be intellectually honest about AI use?" If yes, the team's ethics hold. If no, the team is rationalizing.
|
||||
|
||||
What intellectual honesty looks like.
|
||||
|
||||
- The team can articulate its AI-usage policy without defensiveness
|
||||
- The team can name the specific patterns it does and does not use
|
||||
- The team can defend each pattern on the merits, not just by precedent
|
||||
- The team can engage with critiques of its policy without dismissing them
|
||||
- The team updates its policy when reality changes (new tools, new evidence, new audience norms, new regulatory requirements)
|
||||
|
||||
What intellectual dishonesty looks like.
|
||||
|
||||
- Defensiveness when AI involvement is questioned
|
||||
- Refusal to articulate the policy
|
||||
- Dismissing critiques without engaging
|
||||
- Hiding AI involvement that would be material to audiences
|
||||
- Claiming AI does what it does not, or hiding that AI does what it does
|
||||
|
||||
The honest team can withstand external scrutiny because its position holds up. The dishonest team eventually faces external scrutiny that surfaces the gap between claimed and actual practice.
|
||||
|
||||
---
|
||||
|
||||
## When the ethical question is hard
|
||||
|
||||
Edge cases.
|
||||
|
||||
**Ghostwritten content historically allowed.** Industries where ghostwriting has always been the norm (executive thought leadership, celebrity book authorship, political speechwriting). AI assistance in ghostwriting workflows raises questions: is the ghost an AI? does the byline still mean what it meant?
|
||||
|
||||
The conservative position. The byline implies human authorship; if the ghost is an AI rather than a human writer, that distinction is material to the audience and disclosure is appropriate. The aggressive position. Ghostwriting has always been a fiction the audience tolerates; AI ghostwriting is the same fiction with different tools.
|
||||
|
||||
The catalog's position. Default to the conservative reading. The byline's trust value depends on audience understanding of authorship; AI ghostwriting under a named expert byline is more honest with disclosure than without.
|
||||
|
||||
**Educational content with structured explanations.** Topics where the explanation has a canonical shape (math, basic programming, established science). AI-drafted explanations of canonical topics may closely mirror training data because the canonical shape is what the training data contains.
|
||||
|
||||
The conservative position. Cite the canonical sources where they exist; rephrase substantively where citation is impractical.
|
||||
|
||||
**Programmatic SEO at scale.** Hundreds of thousands of pages where individual disclosure is impractical and audience expectations differ from editorial content.
|
||||
|
||||
The position. Programmatic content is genre-typically machine-generated; specific disclosure per page is unnecessary; transparency about the program's overall production model is appropriate at the brand level.
|
||||
|
||||
---
|
||||
|
||||
## Methodology-level choices that stay in the public skill
|
||||
|
||||
The training-data realities framing, the six ethical floors, the intellectual honesty frame, the edge-case handling, the conservative-vs-aggressive position taking on contested cases.
|
||||
|
||||
## Implementation choices that stay internal
|
||||
|
||||
The specific ethics policy the team has documented. The specific review process when an ethics question surfaces. The specific escalation pathway for ethics decisions. The specific tracking that records ethics-related decisions for retrospective review. These vary per team and brand.
|
||||
+121
@@ -0,0 +1,121 @@
|
||||
# Hybrid workflow patterns
|
||||
|
||||
Five workflow patterns with tradeoffs and selection criteria. When each pattern fits production context.
|
||||
|
||||
No pattern is "the right one." Pattern selection is a real decision that should match volume, voice sensitivity, team skill, and time budget. The wrong pattern produces predictable failures: AI-first drafts on voice-sensitive pieces produce slop; human-writes patterns on programmatic-scale work produce throughput failures.
|
||||
|
||||
---
|
||||
|
||||
## Pattern 1: AI-first draft, human-edit-heavy
|
||||
|
||||
The shape. AI produces a 90% draft against a brief. The human spends 60% of the production time editing: rewriting flat sentences, restructuring sections that miss the brief, adding voice and specificity, verifying facts.
|
||||
|
||||
**Best for.** High-volume editorial where the brief is well-authored and the voice is moderately tolerant of AI defaults. SaaS blog posts, knowledge-base articles, secondary editorial pieces.
|
||||
|
||||
**Risks.** Generic voice if editing is light. The pattern fails quietly; pieces ship with AI defaults preserved because the editor was rushed.
|
||||
|
||||
**Time profile.** 30% AI generation, 60% human editing, 10% fact verification. Faster than human-writes for the same word count but slower than naive AI-only generation because editing time scales with the piece's length.
|
||||
|
||||
**When this fits.** The team has clear brand voice and disciplined editors. The volume requirement is real (multiple pieces per day). The audience is tolerant of AI-assisted-but-edited content (most B2B, most consumer marketing).
|
||||
|
||||
---
|
||||
|
||||
## Pattern 2: Human-first outline + research, AI-draft, human-rewrite
|
||||
|
||||
The shape. Human builds the outline (or extends the brief's outline). Human gathers and verifies the research. AI drafts within that scaffold. Human rewrites in voice.
|
||||
|
||||
**Best for.** Voice-sensitive editorial where the brand voice is distinctive enough that AI drafts need substantive rewriting anyway. The pattern formalizes the rewrite as the discipline rather than treating it as cleanup.
|
||||
|
||||
**Risks.** Slower than AI-first drafts. If the rewrite is light, output is similar to Pattern 1. The discipline is in the rewrite intensity.
|
||||
|
||||
**Time profile.** 20% human research and outline, 20% AI drafting, 50% human rewriting, 10% fact verification.
|
||||
|
||||
**When this fits.** Brand voice is distinctive (provocative, opinionated, or emotionally specific). The audience would notice generic drafts. Time budget allows substantive rewrites.
|
||||
|
||||
---
|
||||
|
||||
## Pattern 3: AI-as-research-assistant, human-writes
|
||||
|
||||
The shape. AI condenses sources into research briefs. Human writes the entire piece from the brief in their own voice.
|
||||
|
||||
**Best for.** Highest-trust editorial: thought leadership, contributed expert pieces, journalism, regulated content. Pieces where the byline is doing trust work and any AI involvement in drafting would compromise the byline's value.
|
||||
|
||||
**Risks.** Slowest pattern. AI's role is small enough that the team may question whether AI is helping at all; the answer is usually yes (research time savings are real) but the gain is in time-to-research, not time-to-publish.
|
||||
|
||||
**Time profile.** 40% human reading and outlining, 60% human writing, 10% fact verification (with AI sometimes assisting in flagging fact-check candidates).
|
||||
|
||||
**When this fits.** The byline is named and trusted (a CEO, an expert, a journalist). The publication's positioning depends on human craft. Disclosure norms in the audience expect human authorship.
|
||||
|
||||
---
|
||||
|
||||
## Pattern 4: Human-writes, AI-as-editor
|
||||
|
||||
The shape. Human drafts the piece. AI suggests copy edits, alternative phrasings, structural improvements. Human accepts or rejects each suggestion.
|
||||
|
||||
**Best for.** Senior writers whose voice is established and whose drafts are mostly clean. The AI's role is the second-pair-of-eyes that catches what fatigue or close reading missed.
|
||||
|
||||
**Risks.** AI suggestions can pull voice toward AI defaults if the writer accepts too many. The discipline is rejecting the suggestions that would homogenize voice even when they read as "cleaner."
|
||||
|
||||
**Time profile.** 80% human writing, 15% AI suggestion review, 5% fact verification.
|
||||
|
||||
**When this fits.** The writer is experienced, the brand voice is well-developed, the piece is high-stakes. Pattern is over-kill for routine editorial; right-sized for thought leadership and named-byline pieces.
|
||||
|
||||
---
|
||||
|
||||
## Pattern 5: AI-generates-at-scale, human-samples
|
||||
|
||||
The shape. For programmatic SEO. AI generates thousands of pages from structured data and templates. Human samples 50 to 200 pages per cycle with editorial-qa sampling discipline. Failures above the 5% threshold halt new generation until template or data fixes ship.
|
||||
|
||||
**Best for.** Programmatic SEO programs (per `programmatic-seo`). Volume scales the AI does not penalize the program because the underlying data is real and the template is strong; humans sample rather than fully review.
|
||||
|
||||
**Risks.** Without sampling discipline, the program produces slop at scale. Without threshold gating, slop compounds invisibly until algorithm updates expose it. Pattern requires the editorial-qa scaling pattern to work; without QA scaling, the pattern is just AI-content-factory thinking with extra steps.
|
||||
|
||||
**Time profile.** 5% template and data setup (one-time, deep), 0.5% per-page generation (mostly automated), 10% sampling QA (per cycle), 5% threshold response.
|
||||
|
||||
**When this fits.** Data depth is real, query intent is queryable, QC headcount is budgeted. All five criteria from `programmatic-seo`'s when-pseo-works-decision must be met.
|
||||
|
||||
---
|
||||
|
||||
## Selection criteria
|
||||
|
||||
How to pick the pattern.
|
||||
|
||||
**Voice sensitivity.** Distinctive voice → Pattern 2, 3, or 4. Generic-tolerant voice → Pattern 1 or 5.
|
||||
|
||||
**Volume.** Single-piece-at-a-time editorial → Pattern 2, 3, or 4. High-volume editorial → Pattern 1. Programmatic scale → Pattern 5.
|
||||
|
||||
**Trust requirement.** Named-byline trust work → Pattern 3 or 4. Standard branded content → Pattern 1, 2, or 5.
|
||||
|
||||
**Time budget.** Tight (hours not days) → Pattern 1. Generous (days available) → Pattern 2, 3, or 4. One-time-deep then automated → Pattern 5.
|
||||
|
||||
**Team skill.** Junior writers → Pattern 1 or 2 (more AI scaffolding). Senior writers → Pattern 3 or 4 (less AI, more craft).
|
||||
|
||||
---
|
||||
|
||||
## Combining patterns within one program
|
||||
|
||||
Most content programs run multiple patterns simultaneously. Common combinations.
|
||||
|
||||
- **Editorial pillar + cluster**: Pattern 3 (AI as research assistant) for the pillar piece; Pattern 1 (AI-first draft, human-edit-heavy) for the cluster pieces. The pillar carries the trust; the cluster scales.
|
||||
- **Editorial + programmatic**: Pattern 2 or 4 for editorial; Pattern 5 for programmatic. Same brand, different production model per content type.
|
||||
- **Marketing copy + thought leadership**: Pattern 1 for marketing; Pattern 3 for thought leadership. Different trust requirements; different patterns.
|
||||
|
||||
The discipline. Document which pattern the team uses for which content type. Without explicit documentation, the patterns drift; one writer uses Pattern 1 on a piece that should have been Pattern 3, and the trust value of the byline is compromised.
|
||||
|
||||
---
|
||||
|
||||
## Anti-pattern: pattern drift mid-piece
|
||||
|
||||
Sometimes a piece starts in Pattern 4 (human-writes, AI-as-editor) and drifts into Pattern 1 (AI-first, human-edits) when the writer falls behind on deadline. The piece publishes with AI default voice in sections the writer was supposed to draft.
|
||||
|
||||
The fix. Recognize the drift as a process failure, not a writing failure. The writer was over-committed; the fix is workload management, not blame. Future pieces of this type either get more time (preserving Pattern 4) or get reassigned to Pattern 1 with the editing intensity that Pattern 1 requires.
|
||||
|
||||
---
|
||||
|
||||
## Methodology-level choices that stay in the public skill
|
||||
|
||||
The five patterns, the tradeoffs per pattern, the selection criteria framework, the multi-pattern combinations within a program, the pattern-drift anti-pattern.
|
||||
|
||||
## Implementation choices that stay internal
|
||||
|
||||
The specific AI tools used in each pattern (drafting model, editing model, research model). The specific prompts each pattern uses for the AI handoff. The specific time-tracking that captures pattern adherence per piece. The specific deadline-management workflow that prevents pattern drift mid-piece. These vary by team and tooling.
|
||||
Vendored
+143
@@ -0,0 +1,143 @@
|
||||
# Quality calibration with AI in the loop
|
||||
|
||||
How editorial standards shift when AI is in the workflow. Same standards apply; the failure modes shift.
|
||||
|
||||
The editorial standards from `editorial-qa` apply identically to AI-assisted work: brief adherence, voice consistency, fact accuracy, structure and clarity, AEO/SEO compliance, internal linking and schema validation. What shifts is the failure-mode profile. Programs that ship AI-assisted content with the same QA discipline as human-written content but without recognizing the new failure modes produce slop while believing they are calibrated.
|
||||
|
||||
This reference connects the QA discipline to the AI workflow discipline. It surfaces the shifts.
|
||||
|
||||
---
|
||||
|
||||
## Same standards, different failure modes
|
||||
|
||||
For each editorial standard, the failure mode that dominates in AI-assisted production differs from the failure mode that dominated in human-only production.
|
||||
|
||||
### Brief adherence
|
||||
|
||||
**Human-only failure.** Writer skips a brief field because they think they know better, or misreads the brief.
|
||||
|
||||
**AI-assisted failure.** AI ignores brief fields that were not in the prompt context. The brief is in one document; the AI prompt is in another. Brief fields that did not get pasted into the prompt do not get executed.
|
||||
|
||||
**The fix.** Prompt templates that explicitly include all 12 brief fields. Brief-adherence QA gate runs against the brief, not against the prompt.
|
||||
|
||||
### Voice consistency
|
||||
|
||||
**Human-only failure.** Writer fatigue causes voice drift in section 4 of long pieces. Editorial style drift over months as writers absorb each other's tics.
|
||||
|
||||
**AI-assisted failure.** AI default voice reasserts mid-piece. Long AI generations regress toward generic by section 4 reliably. The drift is faster than human drift and more consistent across pieces.
|
||||
|
||||
**The fix.** Mid-piece voice sampling per `voice-ownership-preservation.md`. Voice anchor text in every prompt. Final pass in human voice on every long piece.
|
||||
|
||||
### Fact accuracy
|
||||
|
||||
**Human-only failure.** Lazy fact-checking. The writer "remembers reading" something but does not verify. Citations to publications without specific dates or page references.
|
||||
|
||||
**AI-assisted failure.** AI hallucinations. Plausible-but-fake statistics with named sources that do not exist. Quotes attributed to real people who did not say them. Citations to URLs that 404.
|
||||
|
||||
**The fix.** Fact-accuracy as halt-condition gate per `editorial-qa`. Verification methodology that traces every claim to a primary source. Pattern recognition for the 6 hallucination patterns.
|
||||
|
||||
### Structure and clarity
|
||||
|
||||
**Human-only failure.** Buried lede, vague opening, history dump in section 1. Mismatched section lengths.
|
||||
|
||||
**AI-assisted failure.** Generic opening that could open any article on the topic. Repetitive paragraph structure (every paragraph 2 to 3 sentences). Bullet-list overuse where prose would serve. Forced bilateral framing throughout. Wrap-up filler endings.
|
||||
|
||||
**The fix.** AI-content audit per `editorial-qa/references/ai-content-audit-patterns.md`. Read-aloud audit catches what line-review misses.
|
||||
|
||||
### AEO and SEO compliance
|
||||
|
||||
**Human-only failure.** Writer forgets to include the target keyword in title and headings. Schema markup absent or invalid.
|
||||
|
||||
**AI-assisted failure.** AI over-optimizes the surface (keyword in every heading, schema markup over-claimed) but under-optimizes the substance (the answer paragraph is generic, the entity coverage is thin, the POV is absent).
|
||||
|
||||
**The fix.** AEO/SEO checks that go beyond surface compliance into substance: is the top-200-word answer self-contained, is the entity coverage what the brief specified, is the POV distinctive.
|
||||
|
||||
### Internal linking and schema validation
|
||||
|
||||
**Human-only failure.** Writer skips internal-link discipline because it feels mechanical. Anchor text uses "click here" or generic phrases.
|
||||
|
||||
**AI-assisted failure.** AI-generated links to URLs that do not exist (hallucinated link targets). Anchor text repeats the same exact-match keyword across multiple links because the AI defaults to that pattern.
|
||||
|
||||
**The fix.** Link-target liveness check on every published piece. Anchor text variation as a explicit QA item.
|
||||
|
||||
---
|
||||
|
||||
## The "QA standards must be tighter" claim is wrong
|
||||
|
||||
A common misreading. Teams shipping AI-assisted work decide their QA needs to be tighter, more checks, more thresholds. The misreading produces checkbox theater.
|
||||
|
||||
The accurate reading. QA needs to be calibrated to the new failure modes, not tightened indiscriminately. The standards stay the same; the patterns to look for shift.
|
||||
|
||||
The discipline. When a team starts AI-assisted production, the QA process gets reviewed against the new failure-mode profile. Some checks become more important (fact accuracy, voice consistency, AI-content audit). Some checks become less important (the writer's preferred typo patterns, since the AI does not have the same typo patterns). The QA shape adjusts.
|
||||
|
||||
---
|
||||
|
||||
## Calibration sessions specific to AI-assisted work
|
||||
|
||||
The calibration session methodology from `team-training-and-calibration.md` adapts for AI-assisted work specifically.
|
||||
|
||||
**The AI-specific calibration session.**
|
||||
|
||||
1. Three editors independently review the same 3 to 5 AI-assisted pieces.
|
||||
2. Each editor's assessment includes the AI-content audit dimensions: AI tells, hallucination patterns, voice drift, slop signals.
|
||||
3. The team reads all assessments together.
|
||||
4. Differences in interpretation surface; reconcile.
|
||||
5. Output: addendum to the AI policy doc capturing the calibration consensus on AI-specific QA dimensions.
|
||||
|
||||
The cadence. Quarterly minimum. More frequent during program build or after AI tool changes that affect output behavior.
|
||||
|
||||
---
|
||||
|
||||
## When the team is calibrated but the output still feels off
|
||||
|
||||
Symptoms.
|
||||
|
||||
- QA gates pass, individual pieces look fine, the program's overall feel is generic
|
||||
- Readers complain about AI-flavored content despite QA passing
|
||||
- Audience growth flat despite shipped quality being technically high
|
||||
|
||||
Diagnosis. The QA discipline catches per-piece failures. It does not catch program-level patterns: every piece passing voice review individually but the cumulative output reading as homogenized.
|
||||
|
||||
The fix. Add a program-level review to the calibration cadence. Read 10 published pieces in sequence. Do they sound like one publication with a distinctive voice, or do they sound like 10 separate AI-assisted pieces from different generic publications? The latter signals voice has been preserved at the per-piece level but lost at the program level.
|
||||
|
||||
The intervention. Tighter voice library, more aggressive reject-the-bland discipline, possibly a return to a heavier human-writes pattern for trust-anchor pieces (pillars, thought leadership, named-author content) while keeping AI-assisted patterns for cluster work.
|
||||
|
||||
---
|
||||
|
||||
## The "ship vs hold" calibration
|
||||
|
||||
In AI-assisted production, the ship-vs-hold decision shifts. More pieces marginally pass QA; the question becomes whether marginal-pass pieces should ship.
|
||||
|
||||
**Human-only mode.** Marginal pieces usually have specific fixes. The editor flags them; the writer fixes them; the piece ships.
|
||||
|
||||
**AI-assisted mode.** Marginal pieces often have systemic AI-tells throughout that fixing one-by-one will not address. The editor's choice is between substantial rewrite (back to Pattern 2 or 3) or kill.
|
||||
|
||||
The discipline. Some AI-assisted pieces are kill candidates, not revise candidates. The team should have explicit kill criteria: pieces that fail AI-content audit on 4+ dimensions, pieces where voice was lost beyond paragraph-level recovery, pieces where the underlying brief was thin enough that the AI draft has nothing to anchor to.
|
||||
|
||||
Killing pieces is part of the discipline. Programs that publish 100% of what they draft are not exercising editorial judgment.
|
||||
|
||||
---
|
||||
|
||||
## The calibration-with-AI checklist
|
||||
|
||||
For each AI-assisted piece, beyond the standard QA gates.
|
||||
|
||||
1. AI-content audit run per `editorial-qa/references/ai-content-audit-patterns.md`?
|
||||
2. Voice anchor text was used in the prompt?
|
||||
3. Mid-piece voice sample taken on long pieces?
|
||||
4. Final pass in human voice for the closing?
|
||||
5. Fact-accuracy gate ran with AI-hallucination patterns specifically in mind?
|
||||
6. Disclosure decision made per the disclosure tier framework?
|
||||
7. The piece passes the "could a competitor have shipped this with the same tools" test?
|
||||
|
||||
If 2+ items fail, the piece is at slop risk. Halt and revise.
|
||||
|
||||
---
|
||||
|
||||
## Methodology-level choices that stay in the public skill
|
||||
|
||||
The same-standards-different-failure-modes mapping, the "QA standards must be tighter" misreading correction, the AI-specific calibration session adaptation, the program-level review pattern, the kill-criteria discipline, the calibration-with-AI checklist.
|
||||
|
||||
## Implementation choices that stay internal
|
||||
|
||||
The specific QA tooling that surfaces AI-specific failure patterns. The specific automation that flags potential AI tells before manual review. The specific calibration session cadence and team composition. The specific kill-criteria thresholds the team has settled on. These vary by team scale and content sensitivity.
|
||||
Vendored
+149
@@ -0,0 +1,149 @@
|
||||
# Team training and calibration
|
||||
|
||||
Documented policy, calibration sessions, voice library, quality benchmarks, onboarding.
|
||||
|
||||
Inconsistent AI usage across a team produces inconsistent output. The discipline below makes AI usage explicit, calibrated, and documented at the team level so the program ships consistent work regardless of which writer is assigned which piece.
|
||||
|
||||
---
|
||||
|
||||
## Documented AI policy
|
||||
|
||||
The starting point. Every team running AI-assisted content has a policy document, even if currently informal.
|
||||
|
||||
**What the policy specifies.**
|
||||
|
||||
- **Approved uses.** AI in research synthesis, AI in copy edit suggestions, AI in transcription, AI in alternative phrasings. The team uses these without per-piece approval.
|
||||
- **Conditional uses.** AI in first-draft generation, AI in outline generation, AI in long-form drafting. Approved per content type (e.g., approved for cluster pieces, requires editor approval for pillar pieces).
|
||||
- **Prohibited uses.** AI as the sole author of bylined expert content, AI for fact verification (the AI is what gets fact-checked, not what does fact-checking), AI for ethical decisions, AI for final approval.
|
||||
- **Tool standards.** Either "the team uses [specific tool] for [specific task]" or "the team selects from this list of tools per task type." Documented either way.
|
||||
- **Disclosure requirements.** By content type, per the disclosure framework.
|
||||
- **Voice library reference.** Where the team's voice anchor texts and prompt templates live.
|
||||
|
||||
**The discipline.** The policy is a document, not an oral tradition. Writers, editors, and contributors know where to find it; it is referenced in onboarding; it is updated quarterly.
|
||||
|
||||
---
|
||||
|
||||
## Calibration sessions
|
||||
|
||||
The discipline. Quarterly editor sessions where editors review the same AI-assisted pieces and surface differences in their judgment.
|
||||
|
||||
**Session structure.**
|
||||
|
||||
1. Three editors independently review the same 3 to 5 recently-published pieces.
|
||||
2. Each editor writes a one-paragraph assessment per piece: voice, brief adherence, AI tells, fact accuracy, overall quality.
|
||||
3. The team reads all assessments together.
|
||||
4. Differences in interpretation surface; the team reconciles to a shared standard.
|
||||
5. The session output is an addendum to the policy doc capturing the calibration consensus.
|
||||
|
||||
**Why this matters.** Without calibration, individual editors apply individual taste. Some editors flag AI-tells aggressively; others ship the same piece without flagging. The inconsistency confuses writers and produces drift in published quality.
|
||||
|
||||
**Cadence.** Quarterly minimum. More frequent during onboarding waves or after policy updates.
|
||||
|
||||
---
|
||||
|
||||
## Voice library
|
||||
|
||||
The team's collection of canonical brand-voice samples used as anchor text in AI prompts.
|
||||
|
||||
**What goes in the library.**
|
||||
|
||||
- 2 to 3 paragraphs of canonical brand voice per content type (blog, whitepaper, help doc, marketing copy, thought leadership)
|
||||
- 2 to 3 paragraphs per writer voice (where the brand has multiple distinct contributor voices)
|
||||
- 5 to 10 examples of AI-generated content that the team rewrote successfully (showing the before-and-after as a calibration aid)
|
||||
- The vocabulary list: preferred terms, forbidden terms, term-specific usage rules
|
||||
|
||||
**Update cadence.** Monthly during program build; quarterly once stable.
|
||||
|
||||
**Why this matters.** The voice library is the operational expression of brand voice. Without a library, every AI prompt reinvents the voice context; the team produces inconsistent output. With a library, the prompt is templated and the voice context stays consistent.
|
||||
|
||||
---
|
||||
|
||||
## Quality benchmarks
|
||||
|
||||
The team's documented examples of "AI-assisted but on-voice" pieces.
|
||||
|
||||
**What the benchmarks show.**
|
||||
|
||||
- 5 to 10 published pieces where AI assistance was substantial but the output reads as on-voice
|
||||
- For each benchmark: the pattern used (which workflow pattern), the editing intensity, the time profile, the quality outcome
|
||||
- The benchmarks are calibration aids: writers and editors look at them when calibrating their own AI-assisted work
|
||||
|
||||
**Why this matters.** "On-voice AI-assisted content" is an abstraction. Concrete examples make it tangible. New writers calibrate to the benchmarks; experienced writers reference them when their work feels off.
|
||||
|
||||
**Anti-pattern.** Benchmarks that are aspirational rather than achieved. The benchmark library should be real published work, not "what we wish we shipped." Aspirational benchmarks set unrealistic expectations.
|
||||
|
||||
---
|
||||
|
||||
## Tool standardization vs intentional pluralism
|
||||
|
||||
Two valid models for AI tool selection at the team level.
|
||||
|
||||
### Standardization
|
||||
|
||||
The team uses one tool consistently for each task type. Drafting on tool A, editing on tool B, transcription on tool C. New writers learn the standard tools; the prompt templates and voice library are tool-specific.
|
||||
|
||||
**When this fits.** Smaller teams. Predictable content types. Time-budget for tool learning is limited. Consistency matters more than per-task optimization.
|
||||
|
||||
### Intentional pluralism
|
||||
|
||||
The team documents which tools fit which tasks; writers select per-task. Tool A for tasks of type X, tool B for tasks of type Y, contributors choose between them as appropriate.
|
||||
|
||||
**When this fits.** Larger teams. Diverse content types. Writers have time to learn multiple tools. Per-task optimization matters more than absolute consistency.
|
||||
|
||||
The discipline either way. The choice is documented; tool selection is not arbitrary or per-writer.
|
||||
|
||||
---
|
||||
|
||||
## Forbidden patterns list
|
||||
|
||||
The patterns the team explicitly does not use AI for, even when AI could technically do them.
|
||||
|
||||
**Common forbidden patterns.**
|
||||
|
||||
- AI fabricating quotes (always; this is fabrication)
|
||||
- AI generating content that names specific real people (consent and verification issues)
|
||||
- AI as the sole author of bylined opinion (ethics)
|
||||
- AI for content involving regulated topics where the team lacks AI-policy guidance (medical advice, legal advice, financial advice)
|
||||
- AI for content the team would be ashamed to publish under their byline (slop test)
|
||||
|
||||
**Why this matters.** The forbidden list is shorter than the approved list but more important. The forbidden list is what keeps the program out of ethics violations and trust failures.
|
||||
|
||||
---
|
||||
|
||||
## Onboarding
|
||||
|
||||
New writers learn the AI policy and calibration in their first 2 weeks.
|
||||
|
||||
**Onboarding components.**
|
||||
|
||||
- **Policy read.** The new writer reads the AI policy doc.
|
||||
- **Voice library walkthrough.** The new writer reviews the voice samples and prompt templates.
|
||||
- **Calibration session participation.** The new writer participates in the next calibration session as observer.
|
||||
- **Shadow assignment.** The new writer's first piece is reviewed jointly with an experienced editor; the editor narrates the calibration in real-time.
|
||||
- **Quality benchmark walkthrough.** The new writer reviews the quality benchmarks and identifies what makes each "on-voice."
|
||||
|
||||
**Why this matters.** New writers without onboarding develop their own AI patterns. The program drifts as new writers join. Onboarding makes the team's discipline transferable.
|
||||
|
||||
---
|
||||
|
||||
## When team calibration breaks
|
||||
|
||||
Symptoms.
|
||||
|
||||
- Different writers produce wildly different AI-assisted output (calibration overdue)
|
||||
- Editors disagree on whether a piece is "AI-flavored" (calibration session needed)
|
||||
- The AI policy doc is 6 months stale and references tools the team no longer uses (policy update overdue)
|
||||
- New writers are using AI in ways that experienced writers do not (onboarding gap)
|
||||
- Voice library has not been updated since the program launched (library refresh overdue)
|
||||
|
||||
The fix. Quarterly calibration sessions, quarterly policy review, quarterly voice library updates, structured onboarding for every new writer. The cadences are calendar-anchored; skipping them is the failure mode.
|
||||
|
||||
---
|
||||
|
||||
## Methodology-level choices that stay in the public skill
|
||||
|
||||
The documented-policy structure, the calibration session methodology, the voice library practice, the quality-benchmark library, the standardization-vs-pluralism choice, the forbidden-patterns discipline, the onboarding components, the calibration-breakdown signals.
|
||||
|
||||
## Implementation choices that stay internal
|
||||
|
||||
The specific format of the policy doc (Notion page, Markdown file, internal wiki). The specific tooling that hosts the voice library (database, Notion, Git repo of sample text). The specific calibration session cadence and team composition. The specific onboarding tracking system. The specific tool selections the team has standardized on. These vary by team and tooling.
|
||||
+133
@@ -0,0 +1,133 @@
|
||||
# Voice ownership preservation
|
||||
|
||||
Voice guidelines as prompt input, sample text as voice anchor, mid-draft voice check, final pass in human voice, reject-the-bland discipline.
|
||||
|
||||
Voice is the dominant casualty of careless AI workflows. The patterns below are what programs do to keep voice through AI-assisted production. Programs that skip these patterns produce content that is technically correct, semantically generic, and indistinguishable from competitors using the same tools.
|
||||
|
||||
---
|
||||
|
||||
## Voice guidelines as prompt input
|
||||
|
||||
The principle. Every AI generation includes the brand voice guidelines as part of the prompt context. Without explicit voice context, AI defaults to a generic register that flattens distinctive brands into industry-standard prose.
|
||||
|
||||
**What goes into the prompt.**
|
||||
|
||||
- Voice attributes (3 to 5 attributes; e.g., "direct, confident, slightly skeptical")
|
||||
- Sentence rhythm preference (short and punchy, measured and layered, conversational with asides)
|
||||
- Stance pattern (opinionated, diplomatic, coach-style, peer-style)
|
||||
- Register (formal, casual, register that matches the surface)
|
||||
- Vocabulary preferences (preferred terms, forbidden terms list)
|
||||
- Anti-patterns (specific phrases or structures to avoid)
|
||||
|
||||
**The discipline.** The voice guidelines are an input to every AI run, not a one-time setup. Teams that paste the voice guidelines into a saved prompt template ensure consistency; teams that re-type them per session produce drift.
|
||||
|
||||
**Why this works.** Generic AI defaults are stronger than the AI's training-era voice memory. Without active voice prompting, the AI regresses to the most common patterns in its training data, which are the most common patterns in published content, which are by definition not distinctive.
|
||||
|
||||
---
|
||||
|
||||
## Sample text as voice anchor
|
||||
|
||||
The principle. Feed the AI 2 to 3 paragraphs of canonical brand voice as part of the prompt. AI mimics what it sees more than what it is told.
|
||||
|
||||
**What to use as anchor.**
|
||||
|
||||
- The brand's strongest published piece in the relevant register
|
||||
- A canonical opening from the brand's editorial doc
|
||||
- A published piece from a writer whose voice the brand wants to maintain consistency with
|
||||
|
||||
**The discipline.** Anchor text is updated as the brand voice evolves. Stale anchors produce stale-feeling content; the program treats anchors as living documents.
|
||||
|
||||
**Why this works.** Description prompts ("write in a direct, skeptical voice") are abstract. AI mimics them generically. Sample text is concrete; AI mimics specific patterns: word choices, sentence shapes, transitional phrases, opening patterns. The mimicry is not perfect but it is closer to the brand voice than the abstract description.
|
||||
|
||||
**The combination.** The strongest voice prompt combines voice guidelines (description) with sample text (concrete examples). Either alone produces drift; together they hold the line.
|
||||
|
||||
---
|
||||
|
||||
## Mid-draft voice check
|
||||
|
||||
The principle. Long pieces drift. At the halfway mark of a 3,000-word piece, AI generations regress toward generic. The check catches the drift before publish.
|
||||
|
||||
**The check.**
|
||||
|
||||
1. Sample paragraphs from the start (first 300 words), middle (1,200 to 1,800 words), and end (last 300 words).
|
||||
2. Compare each sample to the brand voice doc.
|
||||
3. If start and end match brand voice while middle samples regress to generic, the piece has voice drift. Send back for revision.
|
||||
|
||||
**Detection patterns.**
|
||||
|
||||
- Vocabulary regresses (words from the do-not-use list reappear; brand-specific terms drop out)
|
||||
- Sentence rhythm uniforms (every paragraph 2 to 3 sentences, similar lengths)
|
||||
- Stance softens (specific positions become "there are good arguments on all sides")
|
||||
- Register drifts toward "professional neutral" regardless of the surface's intended register
|
||||
|
||||
**Cross-reference.** This check is also covered in `editorial-qa/references/voice-consistency-patterns.md`. The two skills are aligned; the QA gate enforces what this skill prescribes.
|
||||
|
||||
---
|
||||
|
||||
## Final pass in human voice
|
||||
|
||||
The principle. The human edits the closing sections in their own voice. The closing is where the piece's emotional register often lands; AI defaults there reduce the piece to flat informational tone.
|
||||
|
||||
**Why the closing matters.**
|
||||
|
||||
- The reader's last impression
|
||||
- The conversion or memory moment for the piece
|
||||
- The signature moment where the brand voice is most recognizable
|
||||
|
||||
**The discipline.** Even in Pattern 1 (AI-first draft, human-edit-heavy), the closing 100 to 300 words should be substantially or fully human-written. The opening can be AI-drafted with heavy editing; the closing benefits from being composed in the writer's own register.
|
||||
|
||||
**Anti-pattern.** AI-drafted closing paragraphs that announce the piece is ending ("In summary," "By following these steps," "Now you have a comprehensive understanding"). These are AI tells; the human pass should replace them with specific endings: a question, an action, an observation, a direct call to action with concrete language.
|
||||
|
||||
---
|
||||
|
||||
## Reject the bland
|
||||
|
||||
The principle. Any sentence that could appear in any other piece on the topic gets rewritten. Voice lives in the specific.
|
||||
|
||||
**The audit.** Read the piece. For each sentence, ask: is this distinctively from this brand, or could it have come from any competitor? The interchangeable sentences are the bland ones.
|
||||
|
||||
**The fix.**
|
||||
|
||||
- **Replace abstractions with specifics.** "Many companies struggle with X" becomes "73% of B2B SaaS companies surveyed by [source] report struggling with X." If the specific version requires research, do the research; if not, cut the claim.
|
||||
- **Replace hedges with stances.** "It depends on your situation" becomes "for teams under 50 employees, [specific recommendation]; for teams over 200, [different specific recommendation]."
|
||||
- **Replace generic openings with brand-specific openings.** Throat-clearing intros become specific entry-points tied to the piece's argument.
|
||||
|
||||
**The discipline.** Bland sentences are not just "less interesting" sentences; they are voice-killers. A piece with 20% bland sentences reads as 80% diluted; the brand voice is present but watered down past distinction.
|
||||
|
||||
---
|
||||
|
||||
## The voice library
|
||||
|
||||
A program-level practice. The team maintains a library of canonical brand-voice samples that get used as anchor text in AI prompts. The library evolves as the brand voice evolves.
|
||||
|
||||
**Library structure.**
|
||||
|
||||
- Voice samples by register (formal whitepaper, casual blog post, conversational email, professional help doc)
|
||||
- Voice samples by content type (pillar editorial, cluster piece, thought leadership, listicle)
|
||||
- Voice samples by writer (where the brand has multiple distinct contributor voices)
|
||||
|
||||
**Update cadence.** Quarterly. As new pieces ship that exemplify the voice, they go into the library. As old pieces feel stale, they come out.
|
||||
|
||||
**Why this matters.** Teams without a voice library re-paste the same 3 paragraphs as anchor text for years. The voice ages; the AI mimicry ages with it; the content starts feeling dated. Library updates keep the anchor fresh.
|
||||
|
||||
---
|
||||
|
||||
## When voice cannot be preserved
|
||||
|
||||
Sometimes the voice is genuinely incompatible with AI assistance at the volume the program requires. Signals.
|
||||
|
||||
- Brand voice is so distinctive that AI drafts always need 80% rewriting (Pattern 2 might fit; if even Pattern 2 fails, Pattern 3 or 4 are the only options)
|
||||
- Audience is so trust-sensitive that any AI involvement compromises the byline (Pattern 3 only)
|
||||
- Volume target requires AI involvement that voice cannot tolerate
|
||||
|
||||
The honest answer in these cases. Reduce volume to match what voice tolerates, or accept voice trade-off as a strategic choice. The trade-off must be deliberate; "we did not realize voice was suffering" is the failure mode.
|
||||
|
||||
---
|
||||
|
||||
## Methodology-level choices that stay in the public skill
|
||||
|
||||
Voice guidelines as prompt input, sample text as voice anchor, the mid-draft sampling discipline, the final-pass-in-human-voice discipline, the reject-the-bland audit, the voice library practice, the "when voice cannot be preserved" honest framing.
|
||||
|
||||
## Implementation choices that stay internal
|
||||
|
||||
The specific format of the brand voice doc (Notion page, Markdown file, internal wiki). The specific AI tool prompt templates that include voice guidelines and sample text. The specific voice library storage and access pattern. The specific calibration session cadence and team composition. These vary by brand and team.
|
||||
+230
@@ -0,0 +1,230 @@
|
||||
---
|
||||
name: analytics-strategy
|
||||
description: "Design measurement frameworks including event taxonomy, KPI hierarchy, dashboard architecture, attribution models, and analytics implementation strategy. Use this skill whenever the user wants to plan analytics, design dashboards, build event taxonomies, define KPIs, set up tracking, or audit existing measurement. Triggers on analytics strategy, measurement plan, event taxonomy, tracking plan, KPI framework, dashboard design, north star metric, attribution model, conversion tracking, GA4 setup, Mixpanel setup, analytics audit. Also triggers when the user has data but no clear way to use it, or wants to make decisions but doesn't know what to track."
|
||||
category: growth
|
||||
catalog_summary: "Measurement frameworks, dashboard design, event taxonomy"
|
||||
display_order: 1
|
||||
---
|
||||
|
||||
# Analytics Strategy
|
||||
|
||||
Design measurement frameworks that produce decisions, not just dashboards. Stack-agnostic. Tool-agnostic.
|
||||
|
||||
This skill is for measurement planning. For conversion optimization, use `cro-optimization`. For SEO measurement specifically, use `seo-onpage` and adjacent SEO skills.
|
||||
|
||||
---
|
||||
|
||||
## When to use
|
||||
|
||||
- Setting up analytics on a new product or site
|
||||
- Auditing existing analytics setup
|
||||
- Designing dashboards for a team or business
|
||||
- Defining KPIs and a north star metric
|
||||
- Building event taxonomies for product analytics
|
||||
- Designing attribution models for marketing
|
||||
- Translating business questions into measurement plans
|
||||
|
||||
## When NOT to use
|
||||
|
||||
- Conversion testing or optimization (use `cro-optimization`)
|
||||
- SEO performance measurement (use SEO skills)
|
||||
- Pure data infrastructure decisions (different domain)
|
||||
|
||||
---
|
||||
|
||||
## Required inputs
|
||||
|
||||
- The business or product context (what does success look like)
|
||||
- The audience for the analytics (who needs to make what decisions)
|
||||
- The current measurement state (existing tools, tracking, gaps)
|
||||
- The questions the team needs to answer
|
||||
|
||||
---
|
||||
|
||||
## The framework: 4 layers
|
||||
|
||||
A complete measurement strategy covers all four. Each layer feeds the next.
|
||||
|
||||
### 1. North star and KPI hierarchy
|
||||
|
||||
The single metric that captures the most important outcome, plus the supporting metrics.
|
||||
|
||||
**North star metric:**
|
||||
|
||||
- One metric. Singular.
|
||||
- Captures customer-perceived value.
|
||||
- Leads to revenue, but isn't revenue itself (revenue is too far downstream).
|
||||
- Examples: weekly active users, completed jobs, revenue-generating sessions, hours of value delivered.
|
||||
|
||||
**Underneath the north star, the KPI hierarchy:**
|
||||
|
||||
```
|
||||
North star metric
|
||||
├── Acquisition KPI (how new users enter)
|
||||
├── Activation KPI (when new users get value)
|
||||
├── Engagement KPI (how often users return)
|
||||
├── Retention KPI (how many stick over time)
|
||||
└── Monetization KPI (how value translates to revenue)
|
||||
```
|
||||
|
||||
This is the "AARRR" or "pirate metrics" framework. It works because it covers the full lifecycle.
|
||||
|
||||
### 2. Event taxonomy
|
||||
|
||||
The vocabulary the product uses to describe what users do.
|
||||
|
||||
**Event design principles:**
|
||||
|
||||
- **Verb + noun.** `signed_up`, `created_project`, `completed_checkout`. Past tense, snake_case.
|
||||
- **One event per discrete action.** Not "interacted_with_modal" - too vague. Specifically `opened_modal_X`, `closed_modal_X`, `confirmed_in_modal_X`.
|
||||
- **Properties capture context.** Each event has properties (key-value pairs) for context. `signed_up` has properties like `signup_method`, `referrer`, `plan`.
|
||||
- **Standardize property names.** `user_id` everywhere, not `userId` here and `id` there.
|
||||
- **Document everything.** A tracking plan that lives nowhere is a tracking plan no one follows.
|
||||
|
||||
**Event coverage:**
|
||||
|
||||
- All key user actions tracked
|
||||
- All conversion points tracked
|
||||
- All errors tracked
|
||||
- All page views tracked (with consistent properties)
|
||||
- All button clicks that matter (not all button clicks - that's noise)
|
||||
|
||||
**Anti-patterns:**
|
||||
|
||||
- 500+ events with no documentation
|
||||
- Inconsistent naming (`buttonClicked`, `Button Clicked`, `clicked_button`)
|
||||
- Property keys that vary across events
|
||||
- Events fired client-side that should be server-side (and vice versa)
|
||||
- PII in event properties (privacy issue and tooling issue)
|
||||
|
||||
### 3. Dashboards and reports
|
||||
|
||||
The interface between data and decisions.
|
||||
|
||||
**Dashboard design principles:**
|
||||
|
||||
- **One audience per dashboard.** Executive dashboard != product team dashboard. Different metrics, different cadence.
|
||||
- **One question per chart.** A chart should answer one question, not three.
|
||||
- **Annotations matter.** Note launches, experiments, holidays, outages. A spike means nothing without context.
|
||||
- **Context comparisons.** "10,000 signups this month" - compared to what? Last month, last year, target?
|
||||
- **Lead with the action.** What does this dashboard help someone decide?
|
||||
|
||||
**Common dashboard types:**
|
||||
|
||||
| Dashboard | Audience | Metrics | Cadence |
|
||||
|---|---|---|---|
|
||||
| Executive | Leadership | North star, top 3 KPIs, big-picture trends | Weekly review |
|
||||
| Product | Product team | Funnel metrics, feature adoption, retention | Daily / weekly |
|
||||
| Marketing | Marketing team | Acquisition by channel, CAC, attribution | Daily / weekly |
|
||||
| Operations | Ops / on-call | Performance, errors, capacity | Real-time |
|
||||
| Custom (per team) | Specific team | Their specific KPIs | Their cadence |
|
||||
|
||||
### 4. Attribution and segmentation
|
||||
|
||||
How to connect cause and effect.
|
||||
|
||||
**Attribution models:**
|
||||
|
||||
- **First-touch.** Credit the first interaction. Useful for awareness understanding.
|
||||
- **Last-touch.** Credit the final interaction before conversion. Default in many tools, often misleading.
|
||||
- **Linear.** Spread credit equally across touches. Avoids over-crediting any single channel.
|
||||
- **Time-decay.** Recent touches get more credit. Reasonable middle ground.
|
||||
- **Position-based.** First and last get more credit, middle touches less.
|
||||
- **Data-driven (algorithmic).** Tools like Google Analytics 4 use ML. Black box but increasingly the default.
|
||||
|
||||
For most businesses: pick one primary attribution model, use multiple secondary models for validation.
|
||||
|
||||
**Segmentation principles:**
|
||||
|
||||
- Segment by what causes different behavior, not by what's easy to track
|
||||
- Useful segments: source/channel, plan tier, geography, device, cohort (signup date)
|
||||
- Less useful: demographic guesses without behavioral validation
|
||||
|
||||
---
|
||||
|
||||
## The tracking plan document
|
||||
|
||||
Output of the analytics strategy. A living document.
|
||||
|
||||
**Structure:**
|
||||
|
||||
1. **Goals and KPIs.** Business objectives, north star, KPI hierarchy.
|
||||
2. **Event catalog.** Every event, with properties, when fired, why tracked.
|
||||
3. **User properties.** Persistent attributes (plan, signup_date, role).
|
||||
4. **Page taxonomy.** Page categories, page properties.
|
||||
5. **Naming conventions.** Snake_case, verb_noun, etc.
|
||||
6. **Implementation notes.** Client-side vs server-side, SDK details, sampling.
|
||||
7. **Privacy and compliance.** PII rules, consent handling, data retention.
|
||||
8. **Governance.** Who can add events, review process, change log.
|
||||
|
||||
---
|
||||
|
||||
## Workflow
|
||||
|
||||
1. **Define the questions.** What does the team need to answer? Working backward from questions to metrics works better than starting from metrics.
|
||||
2. **Define the north star.** One metric. Tested against the criteria above.
|
||||
3. **Build the KPI hierarchy.** Acquisition, activation, engagement, retention, monetization.
|
||||
4. **Audit existing tracking.** What's there? What's broken? What's missing?
|
||||
5. **Design the event taxonomy.** Cover the user journey. Document everything.
|
||||
6. **Implement with care.** Test each event. Verify properties. Catch issues in staging.
|
||||
7. **Build dashboards.** One per audience. Lead with action.
|
||||
8. **Establish review cadence.** Weekly business review, monthly KPI review, quarterly strategy review.
|
||||
9. **Govern.** Who adds events, who reviews, how changes propagate.
|
||||
|
||||
---
|
||||
|
||||
## Failure patterns
|
||||
|
||||
- **Tracking everything.** Noise overwhelms signal.
|
||||
- **Tracking nothing strategic.** Page views and that's it. Cannot answer real questions.
|
||||
- **No documentation.** Tracking plan lives in someone's head.
|
||||
- **Inconsistent naming.** Same concept, three names. Reports become detective work.
|
||||
- **Events fired but never reviewed.** Tracking debt accumulates.
|
||||
- **Dashboards no one looks at.** Built for vanity, not decisions.
|
||||
- **Single attribution model treated as truth.** All models lie. Some lie usefully.
|
||||
- **PII in events.** Compliance and tooling problems.
|
||||
- **Client-side only.** Critical business events should be server-side too. Ad blockers, network issues, edge cases lose client-side events.
|
||||
- **No connection to business outcomes.** Metrics exist in a silo, never connected to revenue, retention, or strategic decisions.
|
||||
|
||||
---
|
||||
|
||||
## Output format
|
||||
|
||||
Default output: a markdown tracking plan at `analytics-tracking-plan.md` plus a dashboard inventory.
|
||||
|
||||
Tracking plan structure:
|
||||
|
||||
```markdown
|
||||
# Tracking Plan
|
||||
|
||||
## North star metric
|
||||
[Definition, calculation, target]
|
||||
|
||||
## KPI hierarchy
|
||||
[Each KPI with definition, calculation, owner]
|
||||
|
||||
## Event catalog
|
||||
| Event | When fired | Properties | Owner | Status |
|
||||
|---|---|---|---|---|
|
||||
| user_signed_up | After successful signup form submit | source, plan, referrer | Marketing | Live |
|
||||
| project_created | When user clicks Create Project | project_type, template_used | Product | Live |
|
||||
| ... | | | | |
|
||||
|
||||
## User properties
|
||||
[List with definitions]
|
||||
|
||||
## Naming conventions
|
||||
[Rules]
|
||||
|
||||
## Privacy and compliance
|
||||
[Rules]
|
||||
|
||||
## Governance
|
||||
[Process]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Reference files
|
||||
|
||||
- [`references/event-taxonomy-template.md`](references/event-taxonomy-template.md) - Starter event catalog with patterns for common product types.
|
||||
+407
@@ -0,0 +1,407 @@
|
||||
# Event Taxonomy Template
|
||||
|
||||
Starter event catalogs for common product types. Adapt to specific products. The patterns generalize.
|
||||
|
||||
---
|
||||
|
||||
## Universal events (most products need these)
|
||||
|
||||
### Lifecycle events
|
||||
|
||||
| Event | When fired | Common properties |
|
||||
|---|---|---|
|
||||
| `user_signed_up` | New account created | signup_method, source, referrer, plan |
|
||||
| `user_logged_in` | Successful login | login_method |
|
||||
| `user_logged_out` | Session ended | session_duration |
|
||||
| `user_deleted_account` | Account deletion | reason (if collected) |
|
||||
|
||||
### Product/feature engagement
|
||||
|
||||
| Event | When fired | Common properties |
|
||||
|---|---|---|
|
||||
| `feature_used` | Specific feature interaction | feature_name, feature_version |
|
||||
| `setting_changed` | User changes a setting | setting_name, old_value, new_value |
|
||||
| `notification_clicked` | User clicks a notification | notification_type, notification_id |
|
||||
|
||||
### Errors
|
||||
|
||||
| Event | When fired | Common properties |
|
||||
|---|---|---|
|
||||
| `error_occurred` | Anywhere an error is shown to user | error_type, error_message, page, action_attempted |
|
||||
| `form_validation_failed` | Form submit blocked by validation | form_name, fields_with_errors |
|
||||
|
||||
### Communication
|
||||
|
||||
| Event | When fired | Common properties |
|
||||
|---|---|---|
|
||||
| `email_received` | Email delivered (server-side, via ESP webhook) | email_type, campaign_id |
|
||||
| `email_opened` | Email opened (via tracking pixel) | email_type, campaign_id |
|
||||
| `email_clicked` | Link in email clicked | email_type, campaign_id, link_text |
|
||||
| `email_unsubscribed` | User unsubscribes | email_type |
|
||||
|
||||
---
|
||||
|
||||
## SaaS / B2B product events
|
||||
|
||||
```
|
||||
Acquisition
|
||||
├── user_signed_up
|
||||
├── trial_started
|
||||
└── trial_extended
|
||||
|
||||
Activation (the "aha" moment)
|
||||
├── workspace_created
|
||||
├── teammate_invited
|
||||
├── first_project_created
|
||||
├── first_integration_connected
|
||||
└── first_value_action (product-specific - the moment user gets value)
|
||||
|
||||
Engagement
|
||||
├── session_started
|
||||
├── project_opened
|
||||
├── workflow_completed
|
||||
└── feature_X_used (one per key feature)
|
||||
|
||||
Conversion
|
||||
├── plan_upgraded
|
||||
├── seats_added
|
||||
├── invoice_paid
|
||||
└── annual_plan_purchased
|
||||
|
||||
Retention
|
||||
├── returned_after_inactivity
|
||||
├── reactivated_from_email
|
||||
└── usage_milestone_hit (e.g., crossed 100 actions)
|
||||
|
||||
Risk signals
|
||||
├── support_ticket_opened
|
||||
├── billing_failure_occurred
|
||||
├── trial_expiring_soon (calculated, server-side)
|
||||
└── churn_risk_threshold_hit (calculated)
|
||||
```
|
||||
|
||||
### Properties to capture across all events
|
||||
|
||||
```
|
||||
user_id Persistent across sessions
|
||||
session_id New per session
|
||||
account_id For multi-user accounts
|
||||
plan Current plan tier
|
||||
days_since_signup
|
||||
device_type
|
||||
browser
|
||||
os
|
||||
geo_country
|
||||
geo_region
|
||||
referrer
|
||||
utm_source / utm_medium / utm_campaign / utm_term / utm_content
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Ecommerce events
|
||||
|
||||
```
|
||||
Discovery
|
||||
├── page_viewed
|
||||
├── search_performed
|
||||
├── search_results_viewed
|
||||
├── filter_applied
|
||||
└── product_listing_viewed
|
||||
|
||||
Consideration
|
||||
├── product_viewed
|
||||
├── product_image_zoomed
|
||||
├── size_selected
|
||||
├── color_selected
|
||||
├── reviews_read
|
||||
└── product_shared
|
||||
|
||||
Cart
|
||||
├── product_added_to_cart
|
||||
├── product_removed_from_cart
|
||||
├── cart_viewed
|
||||
├── cart_quantity_changed
|
||||
└── cart_abandoned (calculated, server-side)
|
||||
|
||||
Checkout
|
||||
├── checkout_started
|
||||
├── shipping_info_entered
|
||||
├── billing_info_entered
|
||||
├── promo_code_applied
|
||||
├── promo_code_failed
|
||||
├── checkout_step_viewed (with step_name)
|
||||
└── purchase_completed
|
||||
|
||||
Post-purchase
|
||||
├── order_shipped
|
||||
├── order_delivered
|
||||
├── product_returned
|
||||
├── review_submitted
|
||||
└── reorder_initiated
|
||||
```
|
||||
|
||||
### Ecommerce-specific properties
|
||||
|
||||
```
|
||||
For purchase_completed:
|
||||
order_id
|
||||
total_value
|
||||
currency
|
||||
shipping_method
|
||||
payment_method
|
||||
discount_applied
|
||||
items: [
|
||||
{ product_id, product_name, category, brand, variant, quantity, unit_price }
|
||||
]
|
||||
|
||||
For product_viewed:
|
||||
product_id
|
||||
product_name
|
||||
category
|
||||
brand
|
||||
price
|
||||
in_stock
|
||||
position (when viewed in a list)
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Content site / publisher events
|
||||
|
||||
```
|
||||
Reading
|
||||
├── page_viewed
|
||||
├── article_started (when article body enters viewport)
|
||||
├── article_25_percent_scrolled
|
||||
├── article_50_percent_scrolled
|
||||
├── article_75_percent_scrolled
|
||||
├── article_100_percent_scrolled (read to end)
|
||||
└── article_time_spent (calculated on page exit)
|
||||
|
||||
Engagement
|
||||
├── newsletter_signup_shown
|
||||
├── newsletter_signup_completed
|
||||
├── comment_posted
|
||||
├── article_shared
|
||||
├── article_bookmarked
|
||||
└── related_article_clicked
|
||||
|
||||
Subscription (if metered/paywalled)
|
||||
├── paywall_hit
|
||||
├── paywall_dismissed
|
||||
├── subscribe_started
|
||||
├── subscribe_completed
|
||||
├── article_unlocked (free, registered, paid)
|
||||
```
|
||||
|
||||
### Content-specific properties
|
||||
|
||||
```
|
||||
For article events:
|
||||
article_id
|
||||
article_title
|
||||
category
|
||||
author
|
||||
published_date
|
||||
word_count
|
||||
paywall_status (free, registered_only, paid_only)
|
||||
is_premium
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Marketplace events
|
||||
|
||||
Marketplaces have two-sided tracking: buyers and sellers/providers.
|
||||
|
||||
```
|
||||
Buyer side
|
||||
├── search_performed
|
||||
├── listing_viewed
|
||||
├── inquiry_sent
|
||||
├── booking_started
|
||||
├── booking_completed
|
||||
├── review_left
|
||||
└── repeat_booking_made
|
||||
|
||||
Seller/provider side
|
||||
├── listing_created
|
||||
├── listing_published
|
||||
├── listing_edited
|
||||
├── inquiry_received
|
||||
├── inquiry_responded
|
||||
├── booking_received
|
||||
├── booking_completed
|
||||
├── payout_received
|
||||
└── review_received
|
||||
```
|
||||
|
||||
### Marketplace-specific properties
|
||||
|
||||
```
|
||||
For listing_viewed:
|
||||
listing_id
|
||||
category
|
||||
price
|
||||
location
|
||||
seller_id
|
||||
position_in_search
|
||||
|
||||
For booking_completed:
|
||||
booking_id
|
||||
listing_id
|
||||
seller_id
|
||||
buyer_id
|
||||
total_value
|
||||
fee_amount
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Mobile app events
|
||||
|
||||
```
|
||||
App lifecycle
|
||||
├── app_installed (server-side or attribution platform)
|
||||
├── app_first_opened
|
||||
├── app_opened (every launch)
|
||||
├── app_backgrounded
|
||||
├── app_foregrounded
|
||||
└── app_uninstalled (often inferred, hard to track directly)
|
||||
|
||||
Engagement
|
||||
├── push_notification_received
|
||||
├── push_notification_opened
|
||||
├── deep_link_opened
|
||||
└── share_extension_used
|
||||
|
||||
Permissions
|
||||
├── permission_requested (push, location, camera, etc.)
|
||||
├── permission_granted
|
||||
└── permission_denied
|
||||
```
|
||||
|
||||
### Mobile-specific properties
|
||||
|
||||
```
|
||||
app_version
|
||||
app_build
|
||||
device_model
|
||||
os_version
|
||||
network_type (wifi, cellular)
|
||||
push_token
|
||||
notification_permission_status
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Forms and surveys
|
||||
|
||||
```
|
||||
Form lifecycle
|
||||
├── form_viewed
|
||||
├── form_started (first field interaction)
|
||||
├── form_field_focused
|
||||
├── form_field_completed
|
||||
├── form_field_validation_failed
|
||||
├── form_submitted
|
||||
└── form_abandoned (left page without submit)
|
||||
```
|
||||
|
||||
### Properties
|
||||
|
||||
```
|
||||
form_name
|
||||
form_id
|
||||
fields_total
|
||||
fields_completed
|
||||
fields_with_errors
|
||||
time_spent_seconds
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Naming convention rules
|
||||
|
||||
### Verb_noun, past tense, snake_case
|
||||
|
||||
✓ `user_signed_up`
|
||||
✓ `product_added_to_cart`
|
||||
✓ `article_50_percent_scrolled`
|
||||
✗ `signupCompleted`
|
||||
✗ `addProduct`
|
||||
✗ `Article 50% Scrolled`
|
||||
|
||||
### Properties: camelCase or snake_case (pick one and stay)
|
||||
|
||||
snake_case is more common in SQL contexts (data warehouses).
|
||||
camelCase is more common in JavaScript/TypeScript contexts.
|
||||
The choice matters less than consistency.
|
||||
|
||||
✓ `user_id`, `signup_method`, `email_type` (consistent snake_case)
|
||||
✓ `userId`, `signupMethod`, `emailType` (consistent camelCase)
|
||||
✗ `userId`, `signup_method`, `EmailType` (mixed)
|
||||
|
||||
### Property values: standardize where possible
|
||||
|
||||
Don't allow free-text where an enum should exist.
|
||||
|
||||
✓ `signup_method: "email" | "google" | "github" | "sso"`
|
||||
✗ `signup_method: "email", "Email", "EMAIL", "via email", "with email address"`
|
||||
|
||||
### Reserved properties
|
||||
|
||||
Most analytics tools have built-in properties. Don't override them.
|
||||
|
||||
Common reserved names:
|
||||
- `id`, `userId` (or system equivalent)
|
||||
- `event`, `event_name`
|
||||
- `timestamp`, `time`
|
||||
- `session_id`
|
||||
- `anonymous_id`
|
||||
- `properties`, `traits`
|
||||
|
||||
---
|
||||
|
||||
## What NOT to track
|
||||
|
||||
- **PII in event properties.** Email, phone, full name, address. Privacy issue and tooling issue.
|
||||
- **Every click.** Track meaningful clicks. Hover events. Mouse movements. Generic interactions are noise.
|
||||
- **Server-side state churn.** Background jobs, cron runs, internal events. These belong in monitoring, not product analytics.
|
||||
- **Anything you cannot define in one sentence.** If you can't describe what the event represents, you won't be able to use it.
|
||||
|
||||
---
|
||||
|
||||
## Privacy and consent
|
||||
|
||||
Common compliance patterns:
|
||||
|
||||
- **Consent before tracking.** Cookie banner, opt-in flow.
|
||||
- **Honor Do Not Track.** Browsers signal preferences.
|
||||
- **Right to deletion.** User can request all their data deleted (GDPR, CCPA).
|
||||
- **Right to export.** User can request their data in machine-readable format.
|
||||
- **No cross-site tracking without consent.** Some jurisdictions require explicit opt-in.
|
||||
- **Data residency.** EU user data may need to stay in EU.
|
||||
|
||||
Standard compliance approaches:
|
||||
|
||||
- Server-side tagging when available (more reliable, more controllable)
|
||||
- Consent management platform (CMP) for cookie consent
|
||||
- Clear privacy policy that lists what you collect
|
||||
- A pseudonymous user ID separate from PII
|
||||
|
||||
Compliance specifics vary by jurisdiction. Consult counsel for high-stakes decisions.
|
||||
|
||||
---
|
||||
|
||||
## Governance and review
|
||||
|
||||
Patterns that work:
|
||||
|
||||
- New events require an RFC or short proposal
|
||||
- Event catalog reviewed quarterly
|
||||
- Deprecated events flagged and removed after a grace period
|
||||
- Tracking plan version-controlled (in Git)
|
||||
- Implementation tested in staging before production
|
||||
- Monitoring on event volume (sudden drops = tracking break)
|
||||
+198
@@ -0,0 +1,198 @@
|
||||
---
|
||||
name: art-direction
|
||||
description: "Direct visual and creative work for campaigns, photography, illustration, video, and branded experiences. Use this skill whenever the user wants to brief a photographer, direct illustrators, plan a creative campaign, develop visual concepts, write a creative direction document, or evaluate creative work for fit. Triggers on art direction, photo brief, photography brief, illustration brief, campaign concept, creative concept, visual direction, mood board, look and feel, visual treatment, video direction. Also triggers when the user has approved brand identity but needs to extend it into specific creative deliverables."
|
||||
category: design
|
||||
catalog_summary: "Photography, illustration, and visual direction for campaigns"
|
||||
display_order: 3
|
||||
---
|
||||
|
||||
# Art Direction
|
||||
|
||||
Direct creative work that extends the brand into specific deliverables. Photography, illustration, video, motion, campaigns, environmental design.
|
||||
|
||||
This skill assumes brand identity is approved (`brand-identity` complete). Art direction is about applying and extending it, not defining it.
|
||||
|
||||
---
|
||||
|
||||
## When to use
|
||||
|
||||
- Briefing photographers, illustrators, videographers
|
||||
- Developing campaign creative concepts
|
||||
- Directing in-house creative teams
|
||||
- Writing creative direction documents for vendors
|
||||
- Evaluating creative deliverables for brand fit
|
||||
- Adapting brand visual identity to a new format or context
|
||||
|
||||
## When NOT to use
|
||||
|
||||
- Setting project-wide aesthetic direction across multiple downstream skills (use `creative-direction` instead). This skill briefs specific creative deliverables; `creative-direction` produces the structured aesthetic brief that this skill consumes.
|
||||
- Defining brand visual identity from scratch (use `brand-identity`)
|
||||
- Day-to-day component design (use `design-standards`)
|
||||
- Writing copy for creative work (use `content-and-copy` or `landing-page-copy`)
|
||||
- Building a design system (use `design-system`)
|
||||
|
||||
---
|
||||
|
||||
## Required inputs
|
||||
|
||||
- The deliverable (photo shoot, illustration set, video, campaign)
|
||||
- The brand identity (visual system, voice, imagery direction)
|
||||
- The audience for this specific work
|
||||
- The goal (brand awareness, conversion, education, emotional connection)
|
||||
- Budget and timeline
|
||||
- Distribution context (where it will be seen)
|
||||
|
||||
---
|
||||
|
||||
## The framework: 5 layers
|
||||
|
||||
A creative brief covers five layers. Each must be clear before the brief leaves your hands.
|
||||
|
||||
### 1. The story
|
||||
|
||||
What this creative work is fundamentally about.
|
||||
|
||||
- **The premise.** The core idea in one sentence.
|
||||
- **The emotional through-line.** What the audience feels.
|
||||
- **The role of the brand.** How the brand shows up in the story.
|
||||
- **The takeaway.** What the audience walks away with.
|
||||
|
||||
A weak premise produces work that's pretty but says nothing. Spend time here.
|
||||
|
||||
### 2. The look
|
||||
|
||||
The visual treatment.
|
||||
|
||||
**For photography:**
|
||||
- Subject and composition (close-up, environmental, candid, posed)
|
||||
- Lighting (natural, studio, dramatic, soft)
|
||||
- Color palette (true color, treated, monochrome)
|
||||
- Locations (specific or general direction)
|
||||
- Wardrobe and props
|
||||
- Mood references (3 to 5 reference images)
|
||||
|
||||
**For illustration:**
|
||||
- Style (flat, dimensional, hand-drawn, geometric, abstract)
|
||||
- Color use (full palette, restricted, brand-only)
|
||||
- Line treatment
|
||||
- Composition style
|
||||
- Detail level
|
||||
- Reference artists or works (with explicit "we want like X but NOT like Y")
|
||||
|
||||
**For video / motion:**
|
||||
- Pacing (slow, medium, fast cuts)
|
||||
- Camera movement (static, handheld, sweeping)
|
||||
- Color grading
|
||||
- Transitions and effects
|
||||
- Audio direction (music, voiceover, ambient)
|
||||
- Reference work (3 to 5 examples)
|
||||
|
||||
### 3. The execution
|
||||
|
||||
Production-level direction.
|
||||
|
||||
**Specifications:**
|
||||
- Deliverable formats and sizes (web hero, social square, print full-page)
|
||||
- Required shots or frames
|
||||
- Optional shots if budget allows
|
||||
- Wardrobe and prop list (for live action)
|
||||
- Color and asset specs (RGB, CMYK, hex codes for matching)
|
||||
|
||||
**Constraints:**
|
||||
- Things to avoid (specific cliches, forbidden treatments, regulatory)
|
||||
- Brand-system requirements (logo placement, color use, type rules)
|
||||
|
||||
### 4. The variants
|
||||
|
||||
How this creative scales across distribution.
|
||||
|
||||
Most creative needs to live in multiple places. Plan the variants up front.
|
||||
|
||||
**Common variant set for a campaign:**
|
||||
- Hero web image (16:9 or wider)
|
||||
- Mobile web hero (4:5 or 1:1)
|
||||
- Social square (1:1)
|
||||
- Social vertical (9:16)
|
||||
- Email banner (3:1 typical)
|
||||
- Display ad sizes (300x250, 728x90, etc.)
|
||||
- Print sizes if applicable
|
||||
|
||||
For each variant, note: how the composition adapts, what gets cropped or repositioned, what assets are required.
|
||||
|
||||
### 5. The standards
|
||||
|
||||
The quality bar.
|
||||
|
||||
**Technical:**
|
||||
- Resolution and format requirements
|
||||
- Color profile
|
||||
- File naming conventions
|
||||
- Delivery format (raw + edited, layered files, exported variants)
|
||||
|
||||
**Creative:**
|
||||
- What "approved" looks like (specific examples of acceptable work)
|
||||
- What "not approved" looks like (specific examples to avoid)
|
||||
- Number of revision rounds budgeted
|
||||
|
||||
---
|
||||
|
||||
## Workflow
|
||||
|
||||
### For briefing external creative
|
||||
|
||||
1. **Confirm the inputs.** Brand identity locked. Audience and goal clear. Budget and timeline known.
|
||||
2. **Develop the concept.** Premise, emotional through-line, takeaway.
|
||||
3. **Build the look.** Mood references. Specific direction on style elements.
|
||||
4. **Write the spec.** Production-level direction. Variants. Constraints.
|
||||
5. **Brief the vendor.** In writing. Walk through it live. Allow questions.
|
||||
6. **Review milestones.** Treatment review, halfway review, final review. Don't skip the early reviews; corrections compound.
|
||||
7. **Approve and document.** What was produced, what's licensed for what use.
|
||||
|
||||
### For directing in-house creative
|
||||
|
||||
1. **Same brief, lighter format.** In-house direction can be more iterative. Still document the brief.
|
||||
2. **Co-create.** In-house teams know the brand. Use their judgment. Don't over-direct.
|
||||
3. **Establish review rhythm.** Daily check-ins for fast work, weekly for longer projects.
|
||||
|
||||
### For evaluating existing creative
|
||||
|
||||
1. **Score against the brief.** Did the work hit the brief? Where did it deviate?
|
||||
2. **Score against the brand.** Does this look like the brand? Could this be confused with a competitor?
|
||||
3. **Score against the goal.** Will this drive the intended outcome?
|
||||
4. **Identify fixes.** What can be improved? What's a deal-breaker vs. acceptable?
|
||||
|
||||
---
|
||||
|
||||
## Failure patterns
|
||||
|
||||
- **"Modern, clean, minimal" briefs.** Means nothing. Force specificity. Use specific reference brands, named artists, or visual examples.
|
||||
- **No "what to avoid" direction.** Vendors interpret broadly. Tell them what's out of bounds explicitly.
|
||||
- **Reference imagery that's actually competitor work.** You'll get something that looks like the competitor. Never use direct competitors as references.
|
||||
- **Skipping early reviews.** Every revision late in the process is 5x more expensive than catching issues at treatment stage.
|
||||
- **Too many cooks.** 6 stakeholders all giving creative feedback produces incoherent work. Concentrate creative authority.
|
||||
- **Ignoring distribution.** Creative that doesn't work in the actual contexts where it will live is failed creative.
|
||||
- **No variant planning.** Discovering at delivery that you need a square crop and the photographer composed for 16:9 only.
|
||||
- **Approving creative that's "fine."** Fine is the enemy of distinctive. If it doesn't move you, it won't move the audience.
|
||||
|
||||
---
|
||||
|
||||
## Output format
|
||||
|
||||
Default output is a creative brief at `creative-brief-[project].md`.
|
||||
|
||||
Structure:
|
||||
1. The story (premise, through-line, role of brand, takeaway)
|
||||
2. The look (visual treatment with references)
|
||||
3. The execution (specs, variants, constraints)
|
||||
4. The standards (quality bar, examples of acceptable and unacceptable)
|
||||
5. The logistics (timeline, milestones, budget, deliverables)
|
||||
|
||||
Plus a separate moodboard or visual reference doc with images.
|
||||
|
||||
---
|
||||
|
||||
## Reference files
|
||||
|
||||
- [`references/creative-brief-template.md`](references/creative-brief-template.md) - Generic art direction brief template covering any production type (photo, illustration, video, animation, mixed).
|
||||
- [`references/photo-shoot-brief.md`](references/photo-shoot-brief.md) - Detailed brief template for photography commissions.
|
||||
- [`references/illustration-brief.md`](references/illustration-brief.md) - Brief template for illustration commissions.
|
||||
@@ -0,0 +1,249 @@
|
||||
# Art Direction Brief Template
|
||||
|
||||
A fillable brief for art direction projects. Fill every section before production begins. A short brief beats a generic brief; a generic brief produces generic work.
|
||||
|
||||
---
|
||||
|
||||
## Project: [Name]
|
||||
|
||||
**Project type:** [Photography / Illustration / Video / Animation / Mixed]
|
||||
**Channel(s):** [Where this will live]
|
||||
**Date briefed:** [YYYY-MM-DD]
|
||||
**Production date:** [YYYY-MM-DD]
|
||||
**Director:** [Name]
|
||||
**Producer:** [Name]
|
||||
**Budget:** [Range]
|
||||
|
||||
---
|
||||
|
||||
## 1. Project context
|
||||
|
||||
**Why this project exists:**
|
||||
[1 to 2 paragraphs. The business reason this work needs to be made.]
|
||||
|
||||
**What it must accomplish:**
|
||||
[The specific outcome. Awareness, conversion, brand association, internal use, etc.]
|
||||
|
||||
**How it will be measured:**
|
||||
[Concrete success indicator. Engagement, completion rate, brand lift, internal feedback.]
|
||||
|
||||
---
|
||||
|
||||
## 2. Concept
|
||||
|
||||
**The big idea (one sentence):**
|
||||
[The angle, insight, or opinion the creative work expresses.]
|
||||
|
||||
**Why this concept now:**
|
||||
[2 to 3 sentences. Why this idea fits the moment, the brand, and the audience.]
|
||||
|
||||
**What this concept rejects:**
|
||||
[The opposite or adjacent ideas this concept is not.]
|
||||
|
||||
---
|
||||
|
||||
## 3. Audience
|
||||
|
||||
**Primary audience:**
|
||||
[Specific persona. "Mid-career operator at a B2B SaaS company evaluating tools for their team," not "B2B buyers."]
|
||||
|
||||
**What they currently feel about the category:**
|
||||
[1 to 2 sentences.]
|
||||
|
||||
**What we want them to feel after seeing this:**
|
||||
[1 to 2 sentences.]
|
||||
|
||||
---
|
||||
|
||||
## 4. Subjects
|
||||
|
||||
**People:**
|
||||
- Cast: [Demographics, archetypes, specific casting direction]
|
||||
- Wardrobe: [Direction]
|
||||
- Expression: [What we want them showing]
|
||||
- Diversity: [Explicit casting expectations]
|
||||
|
||||
**Products:**
|
||||
- What appears: [List]
|
||||
- Staging: [How they're shown]
|
||||
- Hierarchy: [Hero product vs supporting]
|
||||
|
||||
**Settings:**
|
||||
- Locations: [Specific or category]
|
||||
- Environment: [Indoor/outdoor, real/built, public/private]
|
||||
- Time of day: [If relevant]
|
||||
|
||||
**Objects/props:**
|
||||
- Required: [Specific items]
|
||||
- Forbidden: [Things never to include]
|
||||
|
||||
---
|
||||
|
||||
## 5. Composition
|
||||
|
||||
**Formats and channels:**
|
||||
| Channel | Aspect ratio | Resolution | Specific requirements |
|
||||
|---|---|---|---|
|
||||
| [e.g., Instagram feed] | 1:1 | [px] | [Crop-safe area for text overlay] |
|
||||
| [e.g., Instagram stories] | 9:16 | [px] | [Top/bottom safe areas] |
|
||||
| [e.g., Web hero] | 16:9 | [px] | [Subject must allow text overlay on left] |
|
||||
| [e.g., Print] | [Specific] | [DPI] | |
|
||||
|
||||
**Shot list:**
|
||||
[Specific shots required. Include reference frame for each.]
|
||||
|
||||
1. [Shot description]: [Reference image]
|
||||
2. [Shot description]: [Reference image]
|
||||
3. [Shot description]: [Reference image]
|
||||
|
||||
**Framing direction:**
|
||||
- Crop tendency: [Tight / medium / wide]
|
||||
- Subject placement: [Centered / off-center / dynamic]
|
||||
- Eye line: [To camera / away / unspecified]
|
||||
- Depth: [Foreground emphasis / background environment / flat]
|
||||
- Negative space: [Generous / minimal / variable]
|
||||
|
||||
---
|
||||
|
||||
## 6. Lighting
|
||||
|
||||
**Direction:**
|
||||
[2 to 4 sentences describing the lighting approach.]
|
||||
|
||||
**Specific qualities:**
|
||||
- Source: [Natural / available / controlled]
|
||||
- Direction: [Front / side / back / overhead]
|
||||
- Quality: [Hard / soft]
|
||||
- Color temperature: [Warm / neutral / cool]
|
||||
- Time of day if natural: [Specific]
|
||||
|
||||
**Lighting references:**
|
||||
[3 to 5 reference images with annotations.]
|
||||
|
||||
---
|
||||
|
||||
## 7. Color and treatment
|
||||
|
||||
**Color palette:**
|
||||
[Brand palette + any campaign-specific extensions]
|
||||
|
||||
**Treatment direction:**
|
||||
- Saturation: [True / muted / desaturated / heightened]
|
||||
- Contrast: [Low / balanced / high]
|
||||
- Color grade: [Specific look or signature]
|
||||
- Film references: [Specific films, photographers, or art if relevant]
|
||||
|
||||
**Treatment references:**
|
||||
[3 to 5 reference images with annotations.]
|
||||
|
||||
---
|
||||
|
||||
## 8. Tone
|
||||
|
||||
**Adjectives (3 to 5):**
|
||||
- [Adjective], not [opposite tendency]
|
||||
- [Adjective], not [opposite tendency]
|
||||
- [Adjective], not [opposite tendency]
|
||||
|
||||
**Pacing (moving image):**
|
||||
[If applicable: brisk / deliberate / breathless / languid]
|
||||
|
||||
**Sound direction (moving image):**
|
||||
[If applicable: score, sound design, voice, silence]
|
||||
|
||||
---
|
||||
|
||||
## 9. Reference moodboard
|
||||
|
||||
[Link to moodboard with 10 to 15 curated images.]
|
||||
|
||||
Each reference labeled with what we are taking from it (composition, lighting, treatment, casting, etc.). Avoid using a single reference for everything; pull specific elements from different sources.
|
||||
|
||||
---
|
||||
|
||||
## 10. What to avoid
|
||||
|
||||
**Visual cliches in our category to reject:**
|
||||
- [Specific cliche with example]
|
||||
- [Specific cliche with example]
|
||||
- [Specific cliche with example]
|
||||
|
||||
**Treatments not aligned with our direction:**
|
||||
- [Specific treatment]
|
||||
- [Specific treatment]
|
||||
|
||||
**Casting we will not use:**
|
||||
- [Specific casting type and why]
|
||||
|
||||
---
|
||||
|
||||
## 11. Deliverables
|
||||
|
||||
**Final deliverables required:**
|
||||
|
||||
| Asset | Format | Count | Specifications |
|
||||
|---|---|---|---|
|
||||
| [e.g., Hero image] | JPG, PNG | 5 | 16:9, 4K |
|
||||
| [e.g., Story crops] | MP4 | 10 | 9:16, 1080p, 15s max |
|
||||
| [e.g., Behind-the-scenes] | MP4 | 1 | 16:9, 60s |
|
||||
|
||||
**Editing/retouching specifications:**
|
||||
[Color grading approach, retouching rules, watermarking, captions]
|
||||
|
||||
**File naming convention:**
|
||||
[`project-asset-version-channel.format`]
|
||||
|
||||
**Delivery method:**
|
||||
[How files arrive. Drive, DAM, direct upload.]
|
||||
|
||||
---
|
||||
|
||||
## 12. Timeline
|
||||
|
||||
| Milestone | Date | Owner |
|
||||
|---|---|---|
|
||||
| Pre-production complete | | |
|
||||
| Production day(s) | | |
|
||||
| Selects review | | |
|
||||
| Edit v1 / first cut | | |
|
||||
| Final delivery | | |
|
||||
|
||||
---
|
||||
|
||||
## 13. Approvals
|
||||
|
||||
**Approval path:**
|
||||
1. [Person / role] - [What they approve]
|
||||
2. [Person / role] - [What they approve]
|
||||
3. [Final approver]
|
||||
|
||||
**Maximum review rounds:** [Typically 2 to 3]
|
||||
**Hard stop:** [Date after which changes are out of scope]
|
||||
|
||||
---
|
||||
|
||||
## 14. Talent
|
||||
|
||||
**Photographer / Illustrator / Director:** [Name and rate]
|
||||
**Why we picked them:** [1 to 2 sentences linking their portfolio to this brief]
|
||||
**Crew:** [Producer, stylist, lighting, etc.]
|
||||
**Talent (on-camera):** [Casting decisions]
|
||||
|
||||
---
|
||||
|
||||
## 15. Open questions
|
||||
|
||||
[Anything unresolved at brief-writing time. Resolve before production day.]
|
||||
|
||||
- [ ] [Question]
|
||||
- [ ] [Question]
|
||||
|
||||
---
|
||||
|
||||
## Sign-off
|
||||
|
||||
Brief approved by:
|
||||
- [Name] [Date]
|
||||
- [Name] [Date]
|
||||
|
||||
Production day(s) confirmed: [Date]
|
||||
@@ -0,0 +1,238 @@
|
||||
# Illustration Brief
|
||||
|
||||
A complete brief for commissioning illustration work. Use as a starting template, fill out fully before sending to the illustrator.
|
||||
|
||||
The cost of a thorough brief is one extra hour of writing. The cost of a thin brief is a redo (and most illustrators charge for redos).
|
||||
|
||||
---
|
||||
|
||||
## Project overview
|
||||
|
||||
**Project name:** [Working title]
|
||||
**Date of brief:** [YYYY-MM-DD]
|
||||
**Delivery deadline:** [Final files due]
|
||||
**Illustrator / studio:** [If selected]
|
||||
**Producer / point of contact:** [Name and contact]
|
||||
**Budget:** [Total or per-illustration rate]
|
||||
|
||||
---
|
||||
|
||||
## The story
|
||||
|
||||
### Premise
|
||||
[The core idea in one sentence. What is each illustration fundamentally about?]
|
||||
|
||||
### Audience
|
||||
[Who will see these illustrations. Their context, their state of mind.]
|
||||
|
||||
### Goal
|
||||
[What do these illustrations accomplish? Editorial illustration, brand storytelling, product visualization, instruction, decoration?]
|
||||
|
||||
### Brand role
|
||||
[How does the brand show up? Subtle (illustrations stand on their own), prominent (brand mark visible in scene), or in-between?]
|
||||
|
||||
### The feeling
|
||||
[3 to 5 adjectives describing the emotional through-line. "Playful," "considered," "warm," "sharp," "optimistic."]
|
||||
|
||||
---
|
||||
|
||||
## The look
|
||||
|
||||
### Style references
|
||||
|
||||
[5 to 10 reference illustrations. Source: illustrator portfolios (Behance, It's Nice That, Cargo), editorial illustration archives, ad campaigns. AVOID: direct competitor imagery, AI-generated images, copyrighted character work used out of context.]
|
||||
|
||||
For each reference, note WHAT to take from it:
|
||||
- "From this illustration: the loose hand-drawn line quality"
|
||||
- "From this illustration: the limited color palette"
|
||||
- "From this illustration: the flat geometric construction"
|
||||
|
||||
NOT just dumping references with no commentary. The illustrator needs to know which qualities matter.
|
||||
|
||||
### What to AVOID
|
||||
|
||||
- [Specific style cliche to avoid, e.g., "Corporate Memphis / Alegria figures"]
|
||||
- [Specific style cliche to avoid, e.g., "isometric tech-startup spot illustrations"]
|
||||
- [Visual treatment that's been overused in the category]
|
||||
|
||||
### Style and technique
|
||||
|
||||
- **Medium:** [Vector / raster / mixed / hand-drawn scanned / 3D]
|
||||
- **Line quality:** [Geometric and clean / loose and gestural / no line / variable]
|
||||
- **Fill style:** [Flat / textured / gradients / cross-hatching / watercolor]
|
||||
- **Detail level:** [Highly detailed / minimal / mid]
|
||||
- **Perspective:** [Flat / isometric / one-point / loose / mixed]
|
||||
- **Figure style** (if illustrating people): [Realistic / stylized / abstract / no figures]
|
||||
|
||||
### Color
|
||||
|
||||
- [Specific palette with hex codes if matching brand]
|
||||
- [Number of colors: limited (2-3), moderate (4-6), full]
|
||||
- [Treatment: brand-matched / shifted / monochrome / sepia / saturated / muted]
|
||||
|
||||
### Composition
|
||||
|
||||
- [Single subject focus / scene with multiple elements / pattern / decorative]
|
||||
- [Negative space treatment]
|
||||
- [Orientation defaults: square, landscape, portrait, mixed]
|
||||
|
||||
---
|
||||
|
||||
## Illustration list
|
||||
|
||||
A specific list of illustrations needed. Each entry is a deliverable.
|
||||
|
||||
### Required illustrations (must-have)
|
||||
|
||||
1. **[Illustration name]**
|
||||
- Subject: [What's depicted]
|
||||
- Concept: [What it should communicate or evoke]
|
||||
- Use case: [Where it will appear, e.g., "blog post hero, 1200x675"]
|
||||
- Variants: [Aspect ratios or color modes needed]
|
||||
|
||||
2. **[Illustration name]**
|
||||
- Subject:
|
||||
- Concept:
|
||||
- Use case:
|
||||
- Variants:
|
||||
|
||||
[Continue for all required illustrations]
|
||||
|
||||
### Optional illustrations (if time and budget allow)
|
||||
|
||||
1. **[Illustration name]**
|
||||
2. **[Illustration name]**
|
||||
|
||||
### Variants per illustration
|
||||
|
||||
Most illustrations need to work in multiple contexts:
|
||||
|
||||
- **Light mode and dark mode:** does the illustration need a dark-background variant?
|
||||
- **Aspect ratios:** which crops are needed (16:9, 1:1, 9:16, banner)?
|
||||
- **Resolution variants:** retina vs standard, social vs hero
|
||||
- **Cropped vs full:** is a cropped detail of the same illustration also needed?
|
||||
- **Animation:** is a static illustration plus a looping animated version needed?
|
||||
|
||||
When briefing, note which variants each illustration must support.
|
||||
|
||||
---
|
||||
|
||||
## Technical specs
|
||||
|
||||
### Source files
|
||||
|
||||
- **Format:** [AI / SVG / PSD / PNG layered / Procreate / Figma]
|
||||
- **Layered structure required:** [Yes - so the brand can adjust colors, swap elements, or animate later. No - flat delivery only.]
|
||||
- **Editability:** [Editable text and shapes preferred / OK to outline]
|
||||
|
||||
### Export formats
|
||||
|
||||
- **Web:** [SVG for vector, WebP / PNG for raster]
|
||||
- **Print:** [If applicable: CMYK, 300 DPI, with bleed]
|
||||
- **Resolution:** [Specific minimums per use case]
|
||||
- **Color profile:** [sRGB for web, CMYK for print]
|
||||
|
||||
### Delivery
|
||||
|
||||
- **Format:** [Cloud delivery, file sharing, hard drive]
|
||||
- **Naming convention:** [e.g., "ProjectName_IllustrationN_VariantX.svg"]
|
||||
- **Asset management:** [Where the files live after delivery]
|
||||
|
||||
### Licensing
|
||||
|
||||
- **Usage:** [Where the illustrations can be used; web, print, paid media, all media, in perpetuity]
|
||||
- **Term:** [Duration of license; usually 1 year, 2 years, or perpetual]
|
||||
- **Geography:** [Worldwide, US-only, etc.]
|
||||
- **Exclusivity:** [Exclusive to brand, or illustrator can include in portfolio? Most illustrators want portfolio rights even on exclusive work.]
|
||||
- **Modification rights:** [Can the brand modify the illustration in-house, or does any change require returning to the illustrator?]
|
||||
- **NFT / generative AI training:** [Explicitly state whether the illustrator can use the work to train AI, and whether the brand can.]
|
||||
|
||||
---
|
||||
|
||||
## Process and milestones
|
||||
|
||||
### Stages and approvals
|
||||
|
||||
A typical illustration commission moves through these stages. Define what each milestone delivers and who approves.
|
||||
|
||||
| Stage | What is delivered | Who approves |
|
||||
|---|---|---|
|
||||
| Brief approved | This document, signed | Brand lead |
|
||||
| Sketches / thumbnails | 2-3 rough directions per illustration | Brand lead + creative director |
|
||||
| Refined sketch | Single chosen direction, more detail | Brand lead + creative director |
|
||||
| Color and style test | One illustration finalized as reference | Brand lead + creative director |
|
||||
| Final illustrations | All deliverables, in all variants | Brand lead |
|
||||
| Files handed over | Source + exports, organized | Brand lead |
|
||||
|
||||
### Revision rounds
|
||||
|
||||
- **Sketch round 1:** [What is in scope. Typically composition and concept. Major changes are easier here.]
|
||||
- **Sketch round 2:** [Refinement only. Style and composition are locked.]
|
||||
- **Final art rounds:** [Typically 1 round of small adjustments. Beyond this, usually billed separately.]
|
||||
- **Beyond included rounds:** [Cost or process for additional rounds.]
|
||||
|
||||
### Timeline
|
||||
|
||||
| Milestone | Date | Owner |
|
||||
|---|---|---|
|
||||
| Brief approved | | |
|
||||
| Sketches delivered | | |
|
||||
| Sketch sign-off | | |
|
||||
| First finished illustration | | |
|
||||
| Style sign-off | | |
|
||||
| Remaining illustrations delivered | | |
|
||||
| Final files handed over | | |
|
||||
|
||||
---
|
||||
|
||||
## Budget breakdown
|
||||
|
||||
| Item | Cost | Notes |
|
||||
|---|---|---|
|
||||
| Illustrator fee (base) | | |
|
||||
| Per-illustration rate | | |
|
||||
| Style test / first finish | | |
|
||||
| Revisions beyond included rounds | | |
|
||||
| Rush fees (if applicable) | | |
|
||||
| License fees (if separate from base) | | |
|
||||
| Source file delivery (if separate) | | |
|
||||
| **Total** | | |
|
||||
|
||||
---
|
||||
|
||||
## Approval process
|
||||
|
||||
### Who approves at each stage
|
||||
|
||||
- **Brief:** [Name]
|
||||
- **Sketches:** [Names]
|
||||
- **Style test:** [Names]
|
||||
- **Final illustrations:** [Name]
|
||||
- **Final delivery:** [Name]
|
||||
|
||||
### Use of work
|
||||
|
||||
- All deliverables become brand-owned within the licensing terms above.
|
||||
- Illustrator credit: [Required / optional / no credit. Typical: credit required where editorial use, optional where commercial.]
|
||||
- Promotion: [Illustrator can / cannot promote on their own portfolio. Typical: yes after the work is publicly launched.]
|
||||
|
||||
---
|
||||
|
||||
## Open questions
|
||||
|
||||
[Things still being decided.]
|
||||
|
||||
- [ ] [Question]
|
||||
- [ ] [Question]
|
||||
- [ ] [Question]
|
||||
|
||||
---
|
||||
|
||||
## Sign-off
|
||||
|
||||
Brief approved by:
|
||||
|
||||
- [Name, role, date]
|
||||
- [Name, role, date]
|
||||
|
||||
Once signed off, scope changes require a written change order.
|
||||
@@ -0,0 +1,255 @@
|
||||
# Photo Shoot Brief
|
||||
|
||||
A complete brief for commissioning a photo shoot. Use as a starting template, fill out fully before sending to the photographer.
|
||||
|
||||
The cost of a thorough brief is one extra hour of writing. The cost of a thin brief is a reshoot.
|
||||
|
||||
---
|
||||
|
||||
## Project overview
|
||||
|
||||
**Project name:** [Working title]
|
||||
**Date of brief:** [YYYY-MM-DD]
|
||||
**Shoot date(s):** [Target dates]
|
||||
**Location(s):** [Specific or "TBD - photographer recommends"]
|
||||
**Photographer / studio:** [If selected]
|
||||
**Producer / point of contact:** [Name and contact]
|
||||
**Budget:** [Total or range]
|
||||
|
||||
---
|
||||
|
||||
## The story
|
||||
|
||||
### Premise
|
||||
[The core idea in one sentence. What is this shoot fundamentally about?]
|
||||
|
||||
### Audience
|
||||
[Who will see these images. Be specific. Their context, their state of mind.]
|
||||
|
||||
### Goal
|
||||
[What do these images accomplish? Brand awareness? Conversion? Emotional connection? Editorial illustration?]
|
||||
|
||||
### Brand role
|
||||
[How does the brand show up? Subtle (it's about the people), prominent (the product is the hero), or in-between?]
|
||||
|
||||
### The feeling
|
||||
[3 to 5 adjectives describing the emotional through-line. "Confident," "intimate," "celebratory," "considered," "energetic."]
|
||||
|
||||
---
|
||||
|
||||
## The look
|
||||
|
||||
### Visual references
|
||||
|
||||
[5 to 10 reference images. Source: photographers' portfolios, ad campaigns, editorial work. AVOID: direct competitor imagery.]
|
||||
|
||||
For each reference, note WHAT to take from it:
|
||||
- "From this image: the soft natural light"
|
||||
- "From this image: the close composition on hands"
|
||||
- "From this image: the muted color palette"
|
||||
|
||||
NOT just dumping references with no commentary.
|
||||
|
||||
### What to AVOID
|
||||
|
||||
- [Specific visual cliche to avoid, e.g., "Stock-photo-style smiling at camera"]
|
||||
- [Specific visual cliche to avoid]
|
||||
- [Visual treatment that's been overused in the category]
|
||||
|
||||
### Lighting
|
||||
|
||||
- [Natural / studio / mixed]
|
||||
- [Soft and diffused / dramatic and directional / high-contrast / low-contrast]
|
||||
- [Time of day if natural]
|
||||
|
||||
### Color
|
||||
|
||||
- [True color / treated / monochrome / desaturated]
|
||||
- [Specific color palette or mood, with hex codes if matching brand]
|
||||
|
||||
### Composition
|
||||
|
||||
- [Tight crops vs. wide environments]
|
||||
- [Symmetrical vs. asymmetrical]
|
||||
- [Subject placement preferences]
|
||||
- [Portrait vs. landscape orientation defaults]
|
||||
|
||||
### Wardrobe and styling
|
||||
|
||||
- [Casual / formal / specific style direction]
|
||||
- [Color preferences for wardrobe]
|
||||
- [Things to avoid (logos other than ours, distracting patterns, etc.)]
|
||||
|
||||
### Subjects / talent
|
||||
|
||||
- [Demographics and casting direction]
|
||||
- [Specific talent if cast, or open call criteria]
|
||||
- [Diversity considerations]
|
||||
- [Number of subjects per shot]
|
||||
|
||||
### Props and set
|
||||
|
||||
- [Required props]
|
||||
- [Set direction (clean, lived-in, organized, chaotic, etc.)]
|
||||
- [Branded elements (yes / no / minimal)]
|
||||
|
||||
---
|
||||
|
||||
## Shot list
|
||||
|
||||
A specific list of shots needed. Each entry is a shot the photographer must deliver.
|
||||
|
||||
### Required shots (must-have)
|
||||
|
||||
1. **[Shot name]**
|
||||
- Description: [What's in the frame]
|
||||
- Composition: [Tight, wide, environmental]
|
||||
- Use case: [Where this image will be used, e.g., "homepage hero, 16:9"]
|
||||
- Quantity: [How many variations]
|
||||
|
||||
2. **[Shot name]**
|
||||
- Description:
|
||||
- Composition:
|
||||
- Use case:
|
||||
- Quantity:
|
||||
|
||||
[Continue for all required shots]
|
||||
|
||||
### Optional shots (if time and budget allow)
|
||||
|
||||
1. **[Shot name]**
|
||||
2. **[Shot name]**
|
||||
|
||||
### Variants per shot
|
||||
|
||||
Most shots need to work in multiple aspect ratios. Specify:
|
||||
|
||||
- **16:9 (wide):** for web hero, video thumbnails
|
||||
- **4:5 (vertical):** for social, mobile hero
|
||||
- **1:1 (square):** for Instagram, app icons, avatars
|
||||
- **9:16 (vertical extreme):** for Stories, vertical video
|
||||
|
||||
When briefing, note which aspect ratios each shot must support. Photographer composes accordingly (loose enough to crop multiple ways, OR shoots specifically for each crop).
|
||||
|
||||
---
|
||||
|
||||
## Technical specs
|
||||
|
||||
### Resolution and format
|
||||
|
||||
- **Minimum resolution:** [e.g., 6000x4000]
|
||||
- **File format:** [RAW + edited high-res JPG / TIFF]
|
||||
- **Color profile:** [sRGB / Adobe RGB]
|
||||
- **Color space:** [Web vs. print]
|
||||
|
||||
### Editing
|
||||
|
||||
- **Editing scope:** [Color correction only / full retouch / specific retouch needs]
|
||||
- **Editing reference:** [Examples of approved final-look]
|
||||
|
||||
### Delivery
|
||||
|
||||
- **Format:** [Cloud delivery, file sharing, hard drive]
|
||||
- **Naming convention:** [e.g., "ProjectName_ShotN_VariantX.jpg"]
|
||||
- **Asset management:** [Where the files live after delivery]
|
||||
|
||||
### Licensing
|
||||
|
||||
- **Usage:** [Where the images can be used; web, print, paid media, all media, in perpetuity]
|
||||
- **Term:** [Duration of license; usually 1 year, 2 years, or perpetual]
|
||||
- **Geography:** [Worldwide, US-only, etc.]
|
||||
- **Exclusivity:** [Exclusive to brand, or photographer can include in portfolio?]
|
||||
|
||||
---
|
||||
|
||||
## Logistics
|
||||
|
||||
### Timeline
|
||||
|
||||
| Milestone | Date | Owner |
|
||||
|---|---|---|
|
||||
| Brief approved | | |
|
||||
| Treatment / mood board sign-off | | |
|
||||
| Casting / location finalized | | |
|
||||
| Shoot day(s) | | |
|
||||
| Selects delivered | | |
|
||||
| Final edits delivered | | |
|
||||
|
||||
### Budget breakdown
|
||||
|
||||
| Item | Cost | Notes |
|
||||
|---|---|---|
|
||||
| Photographer fee | | |
|
||||
| Talent | | |
|
||||
| Wardrobe / styling | | |
|
||||
| Hair / makeup | | |
|
||||
| Location fee | | |
|
||||
| Set / props | | |
|
||||
| Equipment | | |
|
||||
| Editing / retouching | | |
|
||||
| Production / coordination | | |
|
||||
| Contingency (10%) | | |
|
||||
| **Total** | | |
|
||||
|
||||
### Crew
|
||||
|
||||
- Photographer: [Name]
|
||||
- Photo assistant: [Name]
|
||||
- Producer: [Name]
|
||||
- Stylist: [Name]
|
||||
- Hair / makeup: [Name]
|
||||
- Talent: [Names]
|
||||
- Brand reps on set: [Names]
|
||||
|
||||
### Logistics day-of
|
||||
|
||||
- Call time: [Time]
|
||||
- Wrap time (target): [Time]
|
||||
- Catering / craft services: [Plan]
|
||||
- Wet weather plan: [If outdoor]
|
||||
- Day-of contact list: [Names and numbers]
|
||||
|
||||
---
|
||||
|
||||
## Approval process
|
||||
|
||||
### Who approves at each stage
|
||||
|
||||
- **Brief:** [Name]
|
||||
- **Treatment / mood board:** [Names]
|
||||
- **Day-of selects:** [Names on set or remote review]
|
||||
- **Edited final selects:** [Name]
|
||||
- **Final delivery:** [Name]
|
||||
|
||||
### Revision rounds
|
||||
|
||||
- **Edits round 1:** [What's in scope]
|
||||
- **Edits round 2:** [What's in scope]
|
||||
- **Beyond round 2:** [Cost or process for additional rounds]
|
||||
|
||||
### Use of work
|
||||
|
||||
- All deliverables become brand-owned within the licensing terms above.
|
||||
- Photographer credit: [Required / optional / no credit]
|
||||
- Promotion: [Photographer can / cannot promote on their own portfolio]
|
||||
|
||||
---
|
||||
|
||||
## Open questions
|
||||
|
||||
[Things still being decided.]
|
||||
|
||||
- [ ] [Question]
|
||||
- [ ] [Question]
|
||||
- [ ] [Question]
|
||||
|
||||
---
|
||||
|
||||
## Sign-off
|
||||
|
||||
Brief approved by:
|
||||
|
||||
- [Name, role, date]
|
||||
- [Name, role, date]
|
||||
|
||||
Once signed off, scope changes require a written change order.
|
||||
@@ -0,0 +1,268 @@
|
||||
---
|
||||
name: backup-and-disaster-recovery
|
||||
description: "Plan and run backups, set recovery objectives, and run disaster recovery drills. Use this skill when defining RPO/RTO targets, designing backup architecture, deciding what to back up and how often, planning for full-region or platform outages, or running a restoration drill. Triggers on backup, restore, RPO, RTO, disaster recovery, DR, business continuity, what if the database is gone, what if our hosting goes down, recovery drill, ransomware planning. Also triggers when an incident reveals a gap in restoration capability."
|
||||
category: operations
|
||||
catalog_summary: "RPO/RTO targets, backup strategy, restoration drills"
|
||||
display_order: 6
|
||||
---
|
||||
|
||||
# Backup and Disaster Recovery
|
||||
|
||||
Plan for the worst case: the database is gone, the host is down for a week, the deploy was poisoned, ransomware encrypted everything. The skill is in advance preparation, not reaction.
|
||||
|
||||
---
|
||||
|
||||
## When to use
|
||||
|
||||
- Setting up backups for a new system
|
||||
- Reviewing and validating backup architecture
|
||||
- Defining RPO (recovery point objective) and RTO (recovery time objective)
|
||||
- Running a disaster recovery drill
|
||||
- Diagnosing gaps after an incident
|
||||
- Planning for ransomware, data corruption, or insider threats
|
||||
- Migrating to a new platform (DR planning belongs in the migration plan)
|
||||
|
||||
## When NOT to use
|
||||
|
||||
- Active incident response (use `incident-response`)
|
||||
- Routine deploy rollbacks (use `launch-runbook`)
|
||||
- Code or content versioning (covered by Git, CMS revision history)
|
||||
- Routine database snapshots (use this skill to set them up; routine review goes in monitoring)
|
||||
|
||||
---
|
||||
|
||||
## Required inputs
|
||||
|
||||
- The systems in scope (databases, file storage, code, configs, secrets)
|
||||
- The hosting platforms and providers
|
||||
- Existing backup tooling and what it covers
|
||||
- Tolerance for data loss (in time)
|
||||
- Tolerance for downtime (in time)
|
||||
- Compliance requirements (some regulations mandate specific backup standards)
|
||||
|
||||
---
|
||||
|
||||
## The framework: 4 questions
|
||||
|
||||
Every disaster recovery plan answers four questions explicitly.
|
||||
|
||||
### Question 1: What needs to be recoverable?
|
||||
|
||||
List every system that holds state. Categorize by criticality.
|
||||
|
||||
**Tier 1: must recover.** Without it, the business stops. (Customer database, transaction log, primary content store.)
|
||||
|
||||
**Tier 2: should recover.** Loss is painful but not fatal. (Analytics, logs, secondary services.)
|
||||
|
||||
**Tier 3: nice to recover.** Easy to rebuild. (Caches, derived data, temporary state.)
|
||||
|
||||
The tier drives RPO, RTO, backup frequency, and storage spend.
|
||||
|
||||
### Question 2: How much data loss is acceptable? (RPO)
|
||||
|
||||
RPO is the maximum age of data that's acceptable to lose, measured in time.
|
||||
|
||||
- RPO = 1 hour: hourly backups or continuous replication needed
|
||||
- RPO = 1 day: daily backups acceptable
|
||||
- RPO = 1 week: weekly backups acceptable
|
||||
|
||||
For most production data, RPO of 1 hour or less is the target. For critical financial systems, near-zero RPO (continuous replication).
|
||||
|
||||
For derived or rebuildable data, RPO of 1 day or longer is fine.
|
||||
|
||||
### Question 3: How much downtime is acceptable? (RTO)
|
||||
|
||||
RTO is the maximum time to restore service after a disaster.
|
||||
|
||||
| RTO target | Implies |
|
||||
|---|---|
|
||||
| < 5 minutes | Hot standby with automatic failover |
|
||||
| < 1 hour | Warm standby with manual failover or fast restore from recent snapshot |
|
||||
| < 24 hours | Cold backup with documented restore process |
|
||||
| Days to weeks | Best-effort, accept extended downtime |
|
||||
|
||||
RTO drives architecture spend. Aggressive RTOs (< 1 hour) are expensive. Loose RTOs (days) are cheap.
|
||||
|
||||
### Question 4: What's the disaster?
|
||||
|
||||
Plan for specific scenarios. Each has different implications.
|
||||
|
||||
**Hardware failure.** Disk dies. Standard backups solve this. Most modern hosts handle automatically.
|
||||
|
||||
**Provider outage.** Region or vendor goes down. Cross-region or cross-provider redundancy needed for low RTO.
|
||||
|
||||
**Data corruption.** Bad migration, bug, accidental delete. Point-in-time restore needed. The latest backup might be corrupted; you need history.
|
||||
|
||||
**Ransomware or compromise.** Attacker encrypts or deletes. Backups must be immutable or air-gapped, otherwise the attacker takes them too.
|
||||
|
||||
**Account compromise.** Attacker has admin credentials, deletes everything. Same defense as ransomware: immutable backups, separate access control.
|
||||
|
||||
**Vendor lock-out.** Account suspended, billing dispute, vendor disappears. Backups outside the vendor needed.
|
||||
|
||||
**Insider threat.** Disgruntled employee deletes or exfiltrates. Audit logs, separation of duties, immutable backups.
|
||||
|
||||
A backup strategy that handles only hardware failure isn't a strategy. It's the easiest case.
|
||||
|
||||
---
|
||||
|
||||
## Workflow
|
||||
|
||||
### Step 1: Inventory state
|
||||
|
||||
Every system that holds state goes on a list:
|
||||
|
||||
| System | Data type | Tier | Current backup | Tested? |
|
||||
|---|---|---|---|---|
|
||||
|
||||
If you can't list it, you can't protect it. Often the inventory itself reveals gaps (the "we forgot about that database" moment).
|
||||
|
||||
### Step 2: Set RPO and RTO per tier
|
||||
|
||||
For each tier, agree on RPO and RTO. Get sign-off from the people who'd be impacted by a disaster.
|
||||
|
||||
Push back on aspirational targets that aren't backed by infrastructure spend. RTO of 5 minutes for a system without a hot standby is not real.
|
||||
|
||||
### Step 3: Verify or design backup architecture
|
||||
|
||||
For each system, ensure:
|
||||
|
||||
- **Frequency** matches RPO.
|
||||
- **Retention** covers point-in-time recovery (typically 30+ days for production data).
|
||||
- **Storage location** is separate from the source. Same disk, same account, same region: not enough.
|
||||
- **Immutability or write-once storage** for at least some backup copies. Defends against ransomware.
|
||||
- **Encryption at rest.** Standard for compliance.
|
||||
- **Tested restore procedure.** Untested backups are not backups.
|
||||
|
||||
The "3-2-1 rule" is a useful starting point: 3 copies of data, 2 different storage types, 1 offsite (or off-account, off-platform).
|
||||
|
||||
### Step 4: Document the restore runbook
|
||||
|
||||
For each system, write the runbook:
|
||||
|
||||
1. How to detect the disaster (cross-reference monitoring)
|
||||
2. How to decide to restore (decision criteria, who authorizes)
|
||||
3. The exact restore steps (commands, screenshots, sequence)
|
||||
4. How to verify the restore worked
|
||||
5. How to switch traffic back
|
||||
6. Communication template (status page, customer notice)
|
||||
|
||||
The runbook is for the worst night of someone's career. Write it for tired, panicked you.
|
||||
|
||||
### Step 5: Run a drill
|
||||
|
||||
The first restore should never be during a real disaster.
|
||||
|
||||
Drills can be:
|
||||
|
||||
- **Tabletop:** walk through the runbook on paper. Useful for finding gaps in the plan.
|
||||
- **Partial:** restore to a non-production environment. Verify the data, validate the steps.
|
||||
- **Full:** simulate the disaster. Production failover or full restore. Maximum confidence, maximum risk.
|
||||
|
||||
For most teams: quarterly tabletop, annual partial drill, full drill before major launches or after major architecture changes.
|
||||
|
||||
### Step 6: Document drill results
|
||||
|
||||
After each drill, document:
|
||||
- What was tested
|
||||
- What worked
|
||||
- What broke
|
||||
- What the actual RPO and RTO were (vs. targets)
|
||||
- Action items
|
||||
|
||||
If the actual RTO was 6 hours when the target was 1 hour, the target is fiction. Either fix the gap or revise the target.
|
||||
|
||||
### Step 7: Schedule the next drill
|
||||
|
||||
Calendar it. Assign an owner. Backups that aren't drilled drift toward useless.
|
||||
|
||||
---
|
||||
|
||||
## Special topics
|
||||
|
||||
### Database point-in-time recovery
|
||||
|
||||
Many managed databases offer point-in-time recovery (PITR) within a retention window (often 7-35 days). This typically achieves RPO of seconds to minutes.
|
||||
|
||||
For longer retention, schedule periodic exports to immutable storage.
|
||||
|
||||
PITR alone isn't enough. If the database service itself is compromised, PITR is gone too. Always have at least one backup outside the source service.
|
||||
|
||||
### File storage backups
|
||||
|
||||
Object stores (S3, GCS, Azure Blob) usually offer:
|
||||
|
||||
- Versioning (recover overwritten objects)
|
||||
- Replication (cross-region)
|
||||
- Object lock or immutability (defense against deletion)
|
||||
|
||||
Set all three for production-critical buckets. Don't rely on the storage provider's default retention.
|
||||
|
||||
### Code and config backups
|
||||
|
||||
Code lives in Git. The Git host (GitHub, GitLab, etc.) is your backup, but a single host is a single point of failure.
|
||||
|
||||
For high-criticality code:
|
||||
- Mirror to a second host or your own server
|
||||
- Periodic offline exports
|
||||
|
||||
Configs and secrets need separate handling:
|
||||
- Infrastructure-as-code: in Git, mirrored
|
||||
- Runtime configs: backed up alongside the system
|
||||
- Secrets: in a secret manager with its own backup story
|
||||
|
||||
### Backups of backups
|
||||
|
||||
The backup system itself can fail. Backup metadata, backup credentials, encryption keys: all must be backed up.
|
||||
|
||||
If your backup is encrypted with a key you've lost, the backup is useless.
|
||||
|
||||
### Compliance backups
|
||||
|
||||
Some regulations require specific retention (e.g., 7 years for financial data). Comply with the highest applicable standard.
|
||||
|
||||
Don't conflate compliance retention with operational backup. Compliance often allows much slower restore (just need to be able to produce the data eventually).
|
||||
|
||||
---
|
||||
|
||||
## Failure patterns
|
||||
|
||||
**Untested backups.** The single most common failure. Backups appear to work; restore fails. Test.
|
||||
|
||||
**Backups in the same account or region as the source.** Account compromise or region outage takes both.
|
||||
|
||||
**No immutability.** Ransomware encrypts the backups too. Use object lock or air-gapped storage.
|
||||
|
||||
**RTO and RPO that aren't measured.** Target says "1 hour" but no one has verified the actual RTO. Assume the actual is longer than the target until proven otherwise.
|
||||
|
||||
**Restore runbook only in someone's head.** Person leaves or is unavailable; runbook is gone. Document.
|
||||
|
||||
**Backups but no DR plan.** "We have backups" isn't a plan. The plan is the runbook plus the architecture plus the drilling.
|
||||
|
||||
**Optimism bias.** "It won't happen to us." It happens. Plan as if it will.
|
||||
|
||||
**Backups too old or too new.** Want point-in-time history (in case corruption isn't immediately discovered). Daily snapshots with 30+ day retention. Or continuous replication with separate periodic snapshots for history.
|
||||
|
||||
**Skipping drills "because we're busy."** Then you'll be busier during the disaster.
|
||||
|
||||
**No communication plan.** Restoring data is half the job. Telling customers, stakeholders, and internal teams what's happening is the other half.
|
||||
|
||||
---
|
||||
|
||||
## Output format
|
||||
|
||||
A DR plan document includes:
|
||||
|
||||
- **Inventory:** every stateful system
|
||||
- **Tiering:** criticality per system
|
||||
- **Targets:** RPO and RTO per tier
|
||||
- **Architecture:** backup tooling, frequency, storage, immutability
|
||||
- **Runbooks:** restore procedures per system
|
||||
- **Drill schedule:** what gets tested when
|
||||
- **Drill log:** results of past drills
|
||||
- **Communication templates:** what to say during a real DR event
|
||||
|
||||
---
|
||||
|
||||
## Reference files
|
||||
|
||||
- [`references/restore-runbook-template.md`](references/restore-runbook-template.md): Fillable template for a restore runbook, covering detection, authorization, steps, verification, and rollback.
|
||||
+231
@@ -0,0 +1,231 @@
|
||||
# Restore Runbook Template
|
||||
|
||||
Fill out one of these per system that needs to be restorable. The runbook is read by a tired, panicked person at 3am. Optimize for that reader.
|
||||
|
||||
---
|
||||
|
||||
## System: [System name]
|
||||
|
||||
**Owner team:** [Team name]
|
||||
**On-call escalation:** [Who, how to reach]
|
||||
**Last drill:** [YYYY-MM-DD]
|
||||
**Last verified working:** [YYYY-MM-DD]
|
||||
|
||||
---
|
||||
|
||||
## Tier and targets
|
||||
|
||||
| | Target | Last measured |
|
||||
|---|---|---|
|
||||
| Tier | [1 / 2 / 3] | |
|
||||
| RPO | [Time] | [Time] |
|
||||
| RTO | [Time] | [Time] |
|
||||
|
||||
If the last measured RTO is longer than the target, the target needs revision or the architecture needs investment.
|
||||
|
||||
---
|
||||
|
||||
## What this system does
|
||||
|
||||
[2-3 sentences describing what the system is and why it matters. The reader may not be familiar with this system in a panic.]
|
||||
|
||||
---
|
||||
|
||||
## What "lost" looks like
|
||||
|
||||
The triggers for using this runbook:
|
||||
|
||||
- [ ] [Specific symptom, e.g., "Database returns errors on all queries"]
|
||||
- [ ] [Specific symptom, e.g., "Data has been deleted or appears corrupted"]
|
||||
- [ ] [Specific symptom, e.g., "Provider region is down per their status page"]
|
||||
- [ ] [Specific symptom, e.g., "Account access is locked or suspended"]
|
||||
|
||||
If none of these match, this might not be the right runbook. Pause and check `incident-response`.
|
||||
|
||||
---
|
||||
|
||||
## Decision: should we restore?
|
||||
|
||||
Restoring is destructive. Don't do it without authorization.
|
||||
|
||||
**Authorize restoration if:**
|
||||
- [Condition 1]
|
||||
- [Condition 2]
|
||||
- [Condition 3]
|
||||
|
||||
**Do NOT restore if:**
|
||||
- The system is recoverable through less destructive means (failover, replica promotion, partial fix)
|
||||
- The data loss is recoverable through other channels (event replay, cache rebuild)
|
||||
- We're not yet sure of the cause (restoring on top of an unknown cause can make things worse)
|
||||
|
||||
**Authorization required from:** [Role]
|
||||
**Backup authorization from:** [Role]
|
||||
|
||||
Document the authorization in the incident channel before proceeding.
|
||||
|
||||
---
|
||||
|
||||
## Pre-restore checklist
|
||||
|
||||
- [ ] Authorization received and documented
|
||||
- [ ] Communication sent: status page updated, internal notice posted
|
||||
- [ ] Recent backup identified and validated
|
||||
- [ ] Backup integrity verified (checksum, sample query, etc.)
|
||||
- [ ] Target environment prepared (downtime accepted, traffic redirected)
|
||||
- [ ] Rollback plan understood
|
||||
- [ ] Timer started (track actual RTO)
|
||||
|
||||
---
|
||||
|
||||
## Restore procedure
|
||||
|
||||
### Step 1: Identify the backup to restore from
|
||||
|
||||
[Specific instructions: which backup system, how to find the right one, how to verify it's the right one.]
|
||||
|
||||
```
|
||||
[Example commands]
|
||||
```
|
||||
|
||||
### Step 2: Prepare the target
|
||||
|
||||
[Specific instructions: which environment, how to ensure no traffic, how to clear or prepare destination.]
|
||||
|
||||
```
|
||||
[Example commands]
|
||||
```
|
||||
|
||||
### Step 3: Run the restore
|
||||
|
||||
[Specific instructions: the actual restore command(s), expected duration, what success looks like.]
|
||||
|
||||
```
|
||||
[Example commands]
|
||||
```
|
||||
|
||||
Expected duration: [Time]
|
||||
|
||||
### Step 4: Verify
|
||||
|
||||
[Specific instructions: how to know the restore worked. Sample queries, row counts, data spot-checks.]
|
||||
|
||||
```
|
||||
[Example commands and queries]
|
||||
```
|
||||
|
||||
Expected results: [What to look for]
|
||||
|
||||
### Step 5: Re-enable traffic
|
||||
|
||||
[Specific instructions: how to direct traffic back to the restored system.]
|
||||
|
||||
```
|
||||
[Example commands]
|
||||
```
|
||||
|
||||
### Step 6: Monitor
|
||||
|
||||
For [time period] after the restore:
|
||||
|
||||
- [ ] Watch error rates (link to dashboard)
|
||||
- [ ] Watch latency (link to dashboard)
|
||||
- [ ] Spot-check user-visible behavior
|
||||
- [ ] Confirm no further data anomalies
|
||||
|
||||
---
|
||||
|
||||
## Rollback
|
||||
|
||||
If the restore makes things worse:
|
||||
|
||||
[Specific instructions for reverting. This is rarely possible for data restores, but for failover-style restores, rollback is just the failover in reverse.]
|
||||
|
||||
---
|
||||
|
||||
## Post-restore
|
||||
|
||||
### Communication
|
||||
|
||||
- [ ] Status page updated (resolved)
|
||||
- [ ] Internal notice updated (system restored)
|
||||
- [ ] Customer comms (if appropriate, who and what)
|
||||
- [ ] Stakeholder summary
|
||||
|
||||
### Documentation
|
||||
|
||||
- [ ] Actual RTO recorded
|
||||
- [ ] Actual RPO measured (latest data point preserved vs latest data point lost)
|
||||
- [ ] Notes on any deviations from the runbook
|
||||
- [ ] Items to fix in the runbook
|
||||
|
||||
### After-action
|
||||
|
||||
Schedule the after-action report within 5 business days. See `after-action-report` skill for the framework.
|
||||
|
||||
---
|
||||
|
||||
## Backup details
|
||||
|
||||
### Backup architecture
|
||||
|
||||
| | Detail |
|
||||
|---|---|
|
||||
| Backup tool | [Tool name] |
|
||||
| Frequency | [Cadence] |
|
||||
| Retention | [Period] |
|
||||
| Storage location | [Where, including account/region] |
|
||||
| Immutable? | [Yes / No, details] |
|
||||
| Encryption | [Method, key location] |
|
||||
|
||||
### How backups are tested
|
||||
|
||||
- [ ] [Test method 1]
|
||||
- [ ] [Test method 2]
|
||||
- [ ] [Test method 3]
|
||||
|
||||
Last test: [YYYY-MM-DD]
|
||||
Test cadence: [How often]
|
||||
|
||||
---
|
||||
|
||||
## Dependencies
|
||||
|
||||
This system depends on:
|
||||
- [Dependency 1, what it provides]
|
||||
- [Dependency 2, what it provides]
|
||||
|
||||
If a dependency is also down, the restore may need to wait or proceed with workarounds. Document the workarounds:
|
||||
|
||||
- [Dependency unavailable scenario 1]: [Workaround]
|
||||
- [Dependency unavailable scenario 2]: [Workaround]
|
||||
|
||||
---
|
||||
|
||||
## Drill log
|
||||
|
||||
| Date | Type (tabletop / partial / full) | Outcome | Issues found | Fixes |
|
||||
|---|---|---|---|---|
|
||||
| YYYY-MM-DD | [Type] | [Pass / Partial / Fail] | [Issues] | [Fixes applied] |
|
||||
|
||||
---
|
||||
|
||||
## Maintenance
|
||||
|
||||
This runbook needs review:
|
||||
- After every restore (real or drill)
|
||||
- When the system architecture changes
|
||||
- When backup tooling changes
|
||||
- At least quarterly
|
||||
|
||||
Last review: [YYYY-MM-DD] by [Name]
|
||||
Next review: [YYYY-MM-DD]
|
||||
|
||||
---
|
||||
|
||||
## Common gotchas
|
||||
|
||||
[List of things that have surprised people during past restores or drills. Specific to this system.]
|
||||
|
||||
- [Gotcha 1]
|
||||
- [Gotcha 2]
|
||||
- [Gotcha 3]
|
||||
@@ -0,0 +1,312 @@
|
||||
---
|
||||
name: beta-program-management
|
||||
description: "Running closed and open betas that produce real signal. Beta participant selection, structured feedback collection, beta-to-GA decision criteria, and the difference between soft-launch (no structure, no signal), kitchen-sink (everyone in, no actionable feedback), and structured beta (calibrated cohort, intentional feedback loops, clear graduation criteria). Triggers on beta program, alpha test, beta cohort, beta participant, beta feedback, beta to GA decision, design partner, early access program, closed beta, open beta, RC release. Also triggers when a feature is approaching launch and the team needs structured pre-GA validation, when prior betas produced noise rather than signal, or when the team has soft-launched before but wants more structured feedback this time."
|
||||
category: product
|
||||
catalog_summary: "Running betas that produce real signal. Participant selection, structured feedback, beta-to-GA decisions. Distinguishes soft-launch (no structure) from kitchen-sink (everyone in) from structured-beta (calibrated cohort with intentional feedback loops)"
|
||||
display_order: 13
|
||||
---
|
||||
|
||||
# Beta Program Management
|
||||
|
||||
A senior product leader's playbook for running betas that produce real signal. Closed and open betas, alpha programs, design partner programs, early access. Participant selection, structured feedback collection, beta-to-GA decision criteria, and the difference between soft-launch (no structure, no signal), kitchen-sink (everyone in, no actionable feedback), and structured beta (calibrated cohort, intentional feedback loops, clear graduation criteria).
|
||||
|
||||
Most betas underperform. Teams ship a beta because they think they should run a beta; participants are recruited loosely or open-flooded; feedback is collected ad-hoc through whatever channels exist; the decision to graduate to GA happens on calendar rather than on signal. The beta produced activity but not learning; the team launches with the same uncertainty they had before the beta.
|
||||
|
||||
This skill is the discipline that turns betas into decision input. Calibrated cohorts who match the post-launch user profile. Structured feedback that captures what the team needs to know. Mid-beta triage that uses what is being learned. Graduation criteria that distinguish "ready" from "we are tired of running the beta." The discipline is not bureaucratic; it is the difference between a beta that informs the GA launch and a beta that produces noise.
|
||||
|
||||
The voice is the senior product leader who has run betas with real signal and watched plenty of betas produce nothing. Concrete, opinionated about what produces signal, willing to call out where beta programs slide into ceremony.
|
||||
|
||||
When to use this skill: planning a beta for an upcoming launch, auditing why prior betas have not produced actionable signal, designing the beta participant experience, or deciding whether a feature is ready to graduate from beta to GA.
|
||||
|
||||
---
|
||||
|
||||
## What this skill is for
|
||||
|
||||
This skill spans beta program design and execution. The PM and engineering distinction:
|
||||
|
||||
- `feature-flagging` is rollout mechanics; the technical layer for controlling who gets which features.
|
||||
- **`beta-program-management` (this skill)** is participant management and feedback discipline; the human layer.
|
||||
- `feature-launch-playbook` is the full launch (post-GA); this skill is what happens BEFORE GA.
|
||||
- `experiment-design` is rigorous A/B testing; betas are softer, qualitative-leaning, smaller-N.
|
||||
- `user-feedback-aggregation` is ongoing feedback streams; beta feedback is bounded to the beta period.
|
||||
- `discovery-research-synthesis` is one-off discovery research; betas are validation-stage rather than discovery-stage.
|
||||
|
||||
The audience: senior PMs, product directors, engineering leads coordinating with product, customer success and support running beta cohorts, anyone planning a closed or open beta.
|
||||
|
||||
What is not in scope: the broader feature launch (covered by `feature-launch-playbook`); the technical rollout mechanics (covered by `feature-flagging`); the rigorous experimentation methodology (covered by `experiment-design`); the discovery-stage research that informs whether to build the feature in the first place.
|
||||
|
||||
---
|
||||
|
||||
## Soft-launch vs kitchen-sink vs structured-beta
|
||||
|
||||
The keystone framing.
|
||||
|
||||
**Soft-launch.** "We will just turn it on for some users." No structured participant selection, no defined feedback collection, no graduation criteria. The beta runs because the team wanted to ship the feature without the full launch ceremony. Output: the feature is in production for some users; the team has no organized way to learn from their experience; signal accumulates through whatever channels happen to surface it; mid-beta course-correction does not happen because there is no structure to surface what should be corrected.
|
||||
|
||||
**Kitchen-sink.** Everyone gets in. The beta opens to whoever signs up. 5,000 beta users; 50 useful pieces of feedback; 4,950 silent users who provide no signal. Volume drowns signal. The team cannot tell which users matched the target post-launch profile. Feedback channels overflow; useful patterns get lost in noise; mid-beta triage cannot keep up. Output: a sense of "we ran a big beta" without the actionable feedback that smaller calibrated cohorts produce.
|
||||
|
||||
**Structured-beta.** Calibrated cohort selected by participant criteria. Intentional feedback loops the cohort knows to use. Clear graduation criteria that distinguish "ready for GA" from "tired of the beta." Mid-beta triage that uses what is being learned. Output: the beta produces decision-grade signal; the GA launch ships with confidence; problems that would have surfaced in production get caught and addressed in beta.
|
||||
|
||||
The litmus test. After the beta concludes, ask: what specifically did we learn from this beta that changed the GA launch? If the team can name 3-7 specific lessons, the beta was structured. If the team can only generally say "the beta went well," the beta was soft-launch or kitchen-sink.
|
||||
|
||||
---
|
||||
|
||||
## Beta type decisions
|
||||
|
||||
Several axes of beta-type choice. The right combination depends on the launch context.
|
||||
|
||||
**Closed vs open.**
|
||||
|
||||
- Closed: invite-only. Participants are selected by criteria. Cohort is bounded.
|
||||
- Open: anyone can join. Cohort is self-selecting.
|
||||
- Closed produces calibrated signal; open produces volume signal that may not match the target user profile.
|
||||
|
||||
**Alpha vs beta vs RC.**
|
||||
|
||||
- Alpha: very early, internal or trusted-partner only, expectation of bugs.
|
||||
- Beta: more polished, broader cohort, expectation of feedback rather than crash discovery.
|
||||
- RC (release candidate): essentially launch-ready, last validation, expectation of production-grade quality.
|
||||
|
||||
**Internal vs external.**
|
||||
|
||||
- Internal: only employees use the feature.
|
||||
- External: real customers use the feature.
|
||||
- Internal betas catch only what employees would experience; external betas catch the full user-context complexity.
|
||||
|
||||
**Time-bounded vs open-ended.**
|
||||
|
||||
- Time-bounded: 4-week beta, 8-week beta, with a defined end.
|
||||
- Open-ended: beta runs until the team decides to graduate.
|
||||
- Time-bounded forces the graduation decision; open-ended risks beta-purgatory.
|
||||
|
||||
The combination decision. A typical structured beta might be closed + beta + external + 6-week time-bounded. A design partner program might be closed + alpha + external + open-ended. An open early access might be open + beta + external + time-bounded. The combination should match the kind of signal the team needs.
|
||||
|
||||
Detail in [`references/beta-type-decisions.md`](references/beta-type-decisions.md).
|
||||
|
||||
---
|
||||
|
||||
## Participant selection criteria
|
||||
|
||||
The discipline that makes calibrated cohorts possible.
|
||||
|
||||
**The criteria that work.**
|
||||
|
||||
- **Match the post-launch user profile.** If the feature is for enterprise admins, beta participants should be enterprise admins, not curious individual users. The beta participant profile should resemble the target GA audience.
|
||||
- **Variety across relevant dimensions.** Not all participants identical. If the feature has segment-specific behavior, the cohort spans segments. If usage volume varies, the cohort includes high-volume and low-volume users.
|
||||
- **Feedback willingness.** Participants who agree to provide feedback through the structured channels. Soft commitment ("I will give feedback when I have time") is weaker than explicit commitment ("I will respond to weekly check-ins and complete the structured survey").
|
||||
- **Existing relationship strength.** Customers with strong existing relationships are more likely to engage substantively. Customers in churn-risk are less likely to engage; their feedback may also be less representative.
|
||||
|
||||
**The criteria that fail.**
|
||||
|
||||
- **Self-selection only.** Open beta sign-ups skew toward enthusiasts and tinkerers; their feedback may not represent the broader target user.
|
||||
- **Highest-paying customers only.** Skews toward enterprise patterns that may not generalize; misses smaller-team use cases.
|
||||
- **Internal employees only.** Misses the customer-context complexity; signals "we tested" without "real users tested."
|
||||
|
||||
**The cohort size question.** Calibrated cohorts are usually 20-200 participants for closed external betas. Smaller (5-20) for design partner programs. Larger (200-2,000) for open early access. Beyond 2,000 the program is a soft-launch with beta branding.
|
||||
|
||||
Detail in [`references/participant-selection-criteria.md`](references/participant-selection-criteria.md).
|
||||
|
||||
---
|
||||
|
||||
## Beta cohort sizing
|
||||
|
||||
How big is enough; when does signal saturate.
|
||||
|
||||
**Saturation patterns.**
|
||||
|
||||
- Critical feedback (bugs, crashes, broken flows) saturates quickly. 20-30 participants surface most critical issues in the first 2 weeks.
|
||||
- Behavioral feedback (how users actually use the feature) saturates more slowly. 50-100 participants needed to see usage patterns clearly.
|
||||
- Edge case feedback saturates slowly. 100+ participants needed; some edge cases never surface in beta.
|
||||
|
||||
**Sizing decisions.**
|
||||
|
||||
- For betas focused on bug discovery: 20-50 participants for 2-4 weeks. Beyond this, returns diminish.
|
||||
- For betas focused on behavioral signal: 50-200 participants for 4-8 weeks.
|
||||
- For betas focused on validating product-market fit assumptions: 100-500 participants over 8-12 weeks.
|
||||
- For betas focused on at-scale infrastructure validation: 500-2,000 participants over 4-8 weeks.
|
||||
|
||||
**The "beta size matches signal need" principle.** Cohort size follows from what the team needs to learn. Larger is not always better; calibrated is.
|
||||
|
||||
Detail in [`references/cohort-sizing-patterns.md`](references/cohort-sizing-patterns.md).
|
||||
|
||||
---
|
||||
|
||||
## Onboarding beta participants
|
||||
|
||||
How participants enter the beta and what they know going in.
|
||||
|
||||
**The setup.**
|
||||
|
||||
- Welcome communication that sets expectations: what the beta is, what feedback is expected, how long it runs, what happens at graduation.
|
||||
- NDAs where relevant (for unannounced features, design partner programs).
|
||||
- Feedback channel access: where participants give feedback, what format, what cadence.
|
||||
- Support escalation path: who participants contact when things break.
|
||||
- Compensation or incentive disclosure: free access to the feature post-GA, gift cards, swag, named recognition, etc.
|
||||
|
||||
**The expectations contract.**
|
||||
|
||||
- What the team commits to participants: communication cadence, response to feedback, transparent about graduation criteria.
|
||||
- What participants commit to the team: feedback through the structured channels, not sharing externally during NDA, willingness to engage in interviews if requested.
|
||||
|
||||
**Common onboarding failures.**
|
||||
|
||||
- Vague expectations. Participants do not know what feedback is wanted; ad-hoc venting fills the channels.
|
||||
- No NDA where appropriate. Beta features get screenshotted on social before the team is ready.
|
||||
- Missing support path. Participants hit issues, do not know who to contact, churn out of the beta.
|
||||
- No incentive clarity. Participants feel underrecognized; engagement decays.
|
||||
|
||||
Detail in [`references/beta-onboarding-templates.md`](references/beta-onboarding-templates.md).
|
||||
|
||||
---
|
||||
|
||||
## Feedback collection patterns
|
||||
|
||||
Structured channels that produce signal rather than noise.
|
||||
|
||||
**Channels that work.**
|
||||
|
||||
- **Structured surveys.** 5-15 question surveys at defined points (week 1, week 4, end of beta). Specific questions tied to the team's learning goals.
|
||||
- **Async feedback forms.** Participants submit specific feedback through a defined form. Fields prompt for use case, severity, expected vs actual behavior.
|
||||
- **Structured interviews.** 30-60 minute interviews with a subset of participants (5-15 per beta). Focused on usage patterns, decision moments, and qualitative depth.
|
||||
- **In-product feedback widgets.** Contextualized to the moment. The feedback is timestamped to the user's actual experience.
|
||||
- **Support tickets routed to beta-aware support.** Beta participants get faster, more contextualized support; the support interactions surface usage friction.
|
||||
|
||||
**Channels that fail.**
|
||||
|
||||
- **Slack channels for venting.** Beta participants vent in real time; signal mixes with noise; nobody synthesizes.
|
||||
- **"Reply to this email with feedback."** Returns long unstructured emails; synthesis is hard; useful patterns get lost.
|
||||
- **"Tell us what you think in the survey at the end."** End-of-beta surveys catch only what participants remember; in-the-moment friction is forgotten.
|
||||
|
||||
**Channel mix discipline.** Most structured betas use 3-5 channels. Each channel surfaces different kinds of signal. The team synthesizes across channels.
|
||||
|
||||
Detail in [`references/feedback-collection-patterns.md`](references/feedback-collection-patterns.md).
|
||||
|
||||
---
|
||||
|
||||
## Mid-beta triage and iteration
|
||||
|
||||
How the team responds to feedback during the beta.
|
||||
|
||||
**The principle.** Betas where the team responds to feedback during the beta produce stronger signal than betas where the team waits for the end.
|
||||
|
||||
**The triage cadence.**
|
||||
|
||||
- Weekly: review feedback across all channels. Categorize: critical bug, friction issue, feature request, positive signal, edge case.
|
||||
- Bi-weekly: surface patterns. What recurring feedback are we seeing? What signal is converging?
|
||||
- As-needed: critical issues get same-day response. Bugs that prevent core flows are not allowed to sit.
|
||||
|
||||
**The iteration discipline.**
|
||||
|
||||
- Critical bugs fixed during the beta. Beta participants experience the fixes; the post-fix experience informs the GA decision.
|
||||
- Friction issues prioritized for fixes during the beta where feasible; documented for the GA decision where not.
|
||||
- Feature requests captured for post-GA roadmap; not added during the beta unless they are graduation-blocking.
|
||||
- Positive signal validated; surfaces what works, informs marketing copy and onboarding for GA.
|
||||
|
||||
**The communication discipline.** Participants are kept informed: "We received your feedback on X; we are addressing it in next week's beta update." Silence makes participants feel ignored; over-communication signals overhead. Calibrate.
|
||||
|
||||
Detail in [`references/mid-beta-triage-and-iteration.md`](references/mid-beta-triage-and-iteration.md).
|
||||
|
||||
---
|
||||
|
||||
## Beta-to-GA decision criteria
|
||||
|
||||
Graduation gates that distinguish "ready" from "tired of running the beta."
|
||||
|
||||
**The criteria.**
|
||||
|
||||
- **Critical bugs cleared.** No known crashes, data loss, or core-flow failures.
|
||||
- **Friction issues addressed or accepted.** Friction the team will not address by GA is documented and accepted as known limitation.
|
||||
- **Behavioral validation.** Beta participants are using the feature in the patterns the team expected. Unexpected patterns are understood (either incorporated into the GA experience or addressed).
|
||||
- **Performance under load.** The feature performs adequately at the scale GA will produce. (For infrastructure betas, this is the central criterion.)
|
||||
- **Documentation and support readiness.** Help docs reflect actual usage; support team is trained on common issues; escalation paths work.
|
||||
- **Positive signal sufficient.** Feedback is net-positive enough to launch with confidence. Not all participants delighted, but a substantial majority finding value.
|
||||
|
||||
**The "we are tired of running the beta" anti-pattern.** Beta has run long enough that the team wants to graduate regardless of signal. The graduation decision happens on calendar rather than on criteria. Resist this; either the criteria are met (graduate) or they are not (extend or reset).
|
||||
|
||||
**The "perpetual beta" anti-pattern.** Beta runs indefinitely because no firm graduation criteria were set. The team avoids the GA commitment by keeping the feature in beta. Force the graduation decision; if the feature is not ready for GA, identify what would make it ready or reconsider whether to ship at all.
|
||||
|
||||
Detail in [`references/beta-to-ga-graduation-criteria.md`](references/beta-to-ga-graduation-criteria.md).
|
||||
|
||||
---
|
||||
|
||||
## Beta wind-down and participant communication
|
||||
|
||||
How the beta ends.
|
||||
|
||||
**The graduation announcement.** Participants are told the feature is graduating. Specific date. What changes for them: continued access (typically yes), pricing changes (often beta participants get free access for some period), feature stability commitments (the GA version is what they will use going forward).
|
||||
|
||||
**The transition.**
|
||||
|
||||
- For most participants: nothing changes operationally. The feature stays available; the "beta" label drops.
|
||||
- Pricing transitions communicated explicitly if applicable.
|
||||
- Beta-only features that did not make GA are flagged. Participants who relied on those features are given alternatives or transition timelines.
|
||||
|
||||
**The thank-you.** Beta participants invested time providing feedback. Recognition matters: named in changelog (with consent), gift cards or swag, advance access to future betas. The recognition strengthens future-beta recruitment.
|
||||
|
||||
**The postmortem.** Internal review of what the beta produced. What was learned, what changed in the GA launch, what would be done differently in future betas. This feeds the team's beta program practice.
|
||||
|
||||
Detail in [`references/beta-wind-down-communication.md`](references/beta-wind-down-communication.md).
|
||||
|
||||
---
|
||||
|
||||
## Common failure modes
|
||||
|
||||
Rapid-fire. Diagnoses in [`references/common-beta-failures.md`](references/common-beta-failures.md).
|
||||
|
||||
- "Our beta produced no signal." Soft-launch pattern; no structured selection or feedback collection.
|
||||
- "Our beta has 5,000 users and we cannot synthesize feedback." Kitchen-sink; cohort too large for the structured signal the team needs.
|
||||
- "Our beta participants never gave feedback." Onboarding contract was unclear or feedback channels were friction-laden.
|
||||
- "We graduated to GA on schedule but launched with critical bugs." Graduation criteria not enforced; calendar-driven graduation.
|
||||
- "Our beta has been running for 8 months with no graduation." Perpetual beta; no firm graduation criteria; graduation decision avoided.
|
||||
- "Beta participants vented on Twitter before the launch." NDA missing or unclear; trust violation early erodes participant willingness.
|
||||
- "The beta surfaced patterns we did not act on." Mid-beta triage missing; feedback collected but not used during the beta.
|
||||
- "The GA launch surprised us." Beta was not actually validating the GA experience; cohort or feedback structure was wrong.
|
||||
- "Beta participants felt ignored after providing feedback." Communication discipline missing; participants commit time and want to know it mattered.
|
||||
- "We ran a closed beta that was effectively employees only." Internal-only beta; missed customer-context complexity.
|
||||
|
||||
---
|
||||
|
||||
## The framework: 12 considerations for beta program management
|
||||
|
||||
When designing or auditing a beta program, walk these 12 considerations.
|
||||
|
||||
1. **Structured-beta, not soft-launch or kitchen-sink.** Calibrated cohort, intentional feedback, clear graduation.
|
||||
2. **Beta type matches signal need.** Closed/open, alpha/beta/RC, internal/external, time-bounded/open-ended.
|
||||
3. **Participants match the post-launch profile.** Match the user the GA serves.
|
||||
4. **Cohort size calibrated to signal need.** Smaller for bugs; larger for behavioral signal.
|
||||
5. **Onboarding contract clear.** Expectations on both sides documented.
|
||||
6. **Feedback channels structured.** 3-5 channels; signal not noise.
|
||||
7. **Mid-beta triage active.** Feedback acted on during the beta.
|
||||
8. **Communication keeps participants engaged.** Updates on what was heard and what is changing.
|
||||
9. **Graduation criteria explicit.** Critical bugs cleared, friction addressed, behavioral validation, performance under load, support readiness, positive signal.
|
||||
10. **Wind-down treats participants well.** Transition clarity, recognition, thank-you.
|
||||
11. **Postmortem feeds practice.** Each beta improves the next.
|
||||
12. **Honest decisions on graduation.** Either criteria met (graduate) or not (extend or reconsider). No tired-of-the-beta graduation.
|
||||
|
||||
The output of the framework is a beta program that produces decision-grade signal, supports the GA launch, and treats participants well enough to recruit them for future betas.
|
||||
|
||||
---
|
||||
|
||||
## Reference files
|
||||
|
||||
- [`references/beta-type-decisions.md`](references/beta-type-decisions.md) - Closed/open, alpha/beta/RC, internal/external, time-bounded/open-ended. The combination decision and how it matches signal need.
|
||||
- [`references/participant-selection-criteria.md`](references/participant-selection-criteria.md) - Criteria that produce calibrated cohorts. Common selection failures. The cohort size question.
|
||||
- [`references/cohort-sizing-patterns.md`](references/cohort-sizing-patterns.md) - Saturation patterns by feedback type. Sizing decisions for different beta goals. The size-matches-signal principle.
|
||||
- [`references/beta-onboarding-templates.md`](references/beta-onboarding-templates.md) - Welcome communication structure. NDAs, feedback channels, support paths, incentives. The expectations contract.
|
||||
- [`references/feedback-collection-patterns.md`](references/feedback-collection-patterns.md) - Structured surveys, async forms, interviews, in-product widgets, beta-aware support. Channels that work and fail. Channel mix discipline.
|
||||
- [`references/mid-beta-triage-and-iteration.md`](references/mid-beta-triage-and-iteration.md) - Triage cadence. Iteration discipline (what to fix during, what to defer). Communication with participants.
|
||||
- [`references/beta-to-ga-graduation-criteria.md`](references/beta-to-ga-graduation-criteria.md) - The six graduation criteria. The "tired of the beta" anti-pattern. Perpetual beta anti-pattern.
|
||||
- [`references/beta-wind-down-communication.md`](references/beta-wind-down-communication.md) - Graduation announcement, transition, recognition, postmortem. Treating participants well.
|
||||
- [`references/common-beta-failures.md`](references/common-beta-failures.md) - 10+ failure patterns with diagnoses and cures.
|
||||
|
||||
---
|
||||
|
||||
## Closing: betas earn their keep with structure
|
||||
|
||||
A structured beta is one of the most useful product activities available. The cohort experiences the feature; the team learns from their experience; the GA launch ships with reduced uncertainty. The discipline pays back many times its cost.
|
||||
|
||||
A soft-launch or kitchen-sink beta is one of the least useful. The team spends weeks running an activity that produces ambient activity without converting to learning. The GA launches with the same uncertainty the beta was supposed to address.
|
||||
|
||||
The teams that earn returns on betas are the ones that take the structure seriously: cohorts calibrated to the GA profile, feedback channels designed for signal, mid-beta triage that uses what is being learned, graduation criteria that distinguish ready from tired, wind-down communication that treats participants well enough to recruit them again.
|
||||
|
||||
When in doubt about whether a beta is ready, ask: are participants matched to the GA user, are feedback channels structured, is the team responding to feedback during the beta, are graduation criteria explicit and being applied honestly, will participants want to join the next beta? If yes to all of those, the beta is real. If no to any, the gap is where the beta will fail to convert participation into learning.
|
||||
+230
@@ -0,0 +1,230 @@
|
||||
# Beta onboarding templates
|
||||
|
||||
Welcome communication structure. NDAs, feedback channels, support paths, incentives. The expectations contract.
|
||||
|
||||
Onboarding sets the tone for the beta. Done well, participants enter with clear expectations and stay engaged through the program. Done badly, participants drop off, fail to provide feedback, or violate confidentiality unintentionally.
|
||||
|
||||
---
|
||||
|
||||
## The welcome communication
|
||||
|
||||
The first message participants receive after accepting the invitation.
|
||||
|
||||
**What it covers.**
|
||||
|
||||
- Welcome and thank-you for joining.
|
||||
- What the beta is: the feature, the goals, what is being validated.
|
||||
- Beta duration: start date, end date, what graduation looks like.
|
||||
- What is expected of participants: feedback channels, cadence, format.
|
||||
- What participants get: access to the feature, support, recognition or compensation, post-GA terms.
|
||||
- NDA reminder where applicable.
|
||||
- How to access the feature: links, accounts, configuration steps.
|
||||
- Who to contact: support escalation path, beta program manager.
|
||||
- First feedback prompt: what the team would like to hear about in the first week.
|
||||
|
||||
**What it does not cover.**
|
||||
|
||||
- A complete product manual. The participant should be able to use the feature; in-product guidance handles the detail.
|
||||
- Internal team structure or politics. Participants do not need to know who reports to whom.
|
||||
- Future roadmap. The beta is about this feature; future plans are separate communication.
|
||||
|
||||
**Length.** 400-800 words for substantive features. Shorter for simpler features. The welcome should be readable in 3-5 minutes.
|
||||
|
||||
**Tone.** Warm but professional. Beta participants are doing the team a favor; the welcome reflects that. Avoid corporate-stiff or overly casual.
|
||||
|
||||
---
|
||||
|
||||
## The expectations contract
|
||||
|
||||
Both sides commit to specific behaviors.
|
||||
|
||||
**What the team commits to.**
|
||||
|
||||
- Communication cadence: regular updates (weekly or bi-weekly).
|
||||
- Response to feedback: critical issues addressed quickly; friction issues prioritized; feature requests captured.
|
||||
- Transparency: participants are told what is being changed based on feedback and what is being deferred.
|
||||
- Graduation criteria: explicit criteria, applied honestly.
|
||||
- Post-GA continuity: participants know what their access looks like after graduation (typically continued access; sometimes special pricing).
|
||||
|
||||
**What participants commit to.**
|
||||
|
||||
- Feedback through the structured channels (specific channels named).
|
||||
- Confidentiality where NDA applies (no public posts, screenshots, or sharing of beta features outside the participant's organization).
|
||||
- Reasonable engagement: not required to use the feature daily, but expected to use it enough to provide informed feedback.
|
||||
- Willingness to engage in interviews if requested (with the right to decline specific interviews).
|
||||
|
||||
**The signed-or-implicit agreement.**
|
||||
|
||||
- For substantial NDAs, participants sign an explicit agreement.
|
||||
- For lighter beta agreements, the welcome communication may be the implicit acceptance (participation implies agreement to terms).
|
||||
- The team should know which approach applies and apply it consistently.
|
||||
|
||||
---
|
||||
|
||||
## NDA considerations
|
||||
|
||||
When NDAs are appropriate.
|
||||
|
||||
**NDA appropriate.**
|
||||
|
||||
- Unannounced features (the beta is essentially confidential).
|
||||
- Features that affect competitive positioning (the team does not want competitors to see the feature early).
|
||||
- Design partner programs with deep collaboration on feature shaping.
|
||||
- Enterprise features that touch sensitive customer data or workflows.
|
||||
|
||||
**NDA not appropriate or unnecessary.**
|
||||
|
||||
- Open public betas.
|
||||
- Features that have already been announced.
|
||||
- Features where the team welcomes public discussion (e.g., developer-tool launches that benefit from community feedback).
|
||||
|
||||
**NDA enforcement reality.**
|
||||
|
||||
- NDAs in open beta are essentially unenforceable. Pretending an open beta has NDA protection is theater.
|
||||
- Closed-beta NDAs are enforceable but require trust; the team should not invite participants who are likely to violate confidentiality.
|
||||
- For sensitive betas, the cohort selection itself is the primary control; NDAs are the legal backstop.
|
||||
|
||||
**What an NDA covers.**
|
||||
|
||||
- Confidentiality of the beta feature, its functionality, and the team's plans.
|
||||
- Restrictions on screenshots, public posts, recordings.
|
||||
- Term: typically until the feature is publicly announced or for a defined period.
|
||||
- Exceptions: feedback to the team is allowed; discussion within the participant's organization is usually allowed.
|
||||
|
||||
---
|
||||
|
||||
## Feedback channel access
|
||||
|
||||
What participants need to know about how to give feedback.
|
||||
|
||||
**Channel inventory.**
|
||||
|
||||
- Structured surveys: when they will arrive, how long they take, how to access.
|
||||
- Async feedback forms: link, instructions, what fields to fill.
|
||||
- Interview signups: how to volunteer for interviews, what compensation if any.
|
||||
- In-product feedback widget: how to use, what context it captures.
|
||||
- Support routing: how beta participants flag issues to the support team.
|
||||
- Slack or community: if a beta-only channel exists, how to join and what tone is expected.
|
||||
|
||||
**Channel discipline.**
|
||||
|
||||
- Each channel serves a different purpose. The welcome communication explains which channel is for which feedback type.
|
||||
- Avoid duplicating channels (multiple Slack-like channels for the same feedback) or confusing channel mappings.
|
||||
|
||||
---
|
||||
|
||||
## Support paths
|
||||
|
||||
How participants escalate issues.
|
||||
|
||||
**The escalation map.**
|
||||
|
||||
- Bug reports: filed through the structured form or support ticketing system tagged "beta."
|
||||
- Critical issues (crashes, data loss): escalation contact named explicitly; not buried in standard support queues.
|
||||
- Feature questions and how-to: routed to in-product help or beta program manager.
|
||||
- Account issues: standard support paths or beta-aware support reps.
|
||||
|
||||
**Support team awareness.**
|
||||
|
||||
- Support team should know the beta is running and how to handle beta-tagged tickets.
|
||||
- Beta-tagged tickets often deserve faster response than standard tickets (the participant is doing the team a favor; long support waits damage the relationship).
|
||||
- Common beta issues should be documented for the support team in advance.
|
||||
|
||||
---
|
||||
|
||||
## Incentive disclosure
|
||||
|
||||
What participants get for joining.
|
||||
|
||||
**Common incentives.**
|
||||
|
||||
- Free access to the feature post-GA for some period.
|
||||
- Discounted pricing on the feature post-GA.
|
||||
- Beta-only feature flags or capabilities preserved post-GA.
|
||||
- Recognition (named in changelog, on website, in launch communications) with consent.
|
||||
- Gift cards, swag, or other compensation.
|
||||
- Direct access to product team during the beta (some participants value this most).
|
||||
|
||||
**Disclosure discipline.**
|
||||
|
||||
- The welcome communication names the incentives explicitly. No surprise reveals at the end.
|
||||
- Different participants may have different incentive packages (design partners often get more); each participant knows their package.
|
||||
- The incentives match the commitment level. Light betas have light incentives; design partner programs have substantive ones.
|
||||
|
||||
**The "no incentive" pattern.**
|
||||
|
||||
- Some betas offer no formal incentive beyond access to the feature.
|
||||
- This works for high-engagement audiences (developers, enthusiasts) where access itself is the incentive.
|
||||
- It does not work for audiences where the time investment is significant; participants need a reason to engage substantively.
|
||||
|
||||
---
|
||||
|
||||
## First-week onboarding
|
||||
|
||||
What happens after the welcome message.
|
||||
|
||||
**The first week's actions.**
|
||||
|
||||
- Day 1: welcome arrives; participants get access; first-day checklist (set up, access feature, complete profile if applicable).
|
||||
- Day 2-3: first feedback prompt arrives. Could be an in-product widget triggered after first usage, or an email asking specifically about the first impression.
|
||||
- End of week 1: brief check-in. Are participants able to access? Have they used the feature? Any friction with onboarding itself?
|
||||
|
||||
**Onboarding-specific friction.**
|
||||
|
||||
- Beta participants who cannot access the feature in the first 24-48 hours often disengage. Access friction is the most consequential onboarding failure.
|
||||
- Documentation that does not match the actual experience (because the docs were written for a slightly different feature version) frustrates early.
|
||||
- Missing context about what the feature is for. Participants who do not know what the feature is meant to accomplish use it tentatively or not at all.
|
||||
|
||||
---
|
||||
|
||||
## Onboarding for different beta types
|
||||
|
||||
Different beta types warrant different onboarding intensity.
|
||||
|
||||
**Lightweight onboarding (open beta, RC validation).**
|
||||
|
||||
- Email welcome with key information.
|
||||
- Self-service access.
|
||||
- In-product guidance handles most setup.
|
||||
|
||||
**Standard onboarding (closed beta, structured cohort).**
|
||||
|
||||
- More substantial welcome email.
|
||||
- Optional onboarding call for participants who request it.
|
||||
- Beta program manager available via direct channel.
|
||||
|
||||
**Deep onboarding (design partner program, complex feature).**
|
||||
|
||||
- Onboarding call with each participant or company.
|
||||
- Custom configuration support.
|
||||
- Direct channel to product team for ongoing collaboration.
|
||||
|
||||
The onboarding intensity matches the beta type. Heavyweight onboarding for an open beta with 5,000 participants is impossible; lightweight onboarding for a 5-partner design program under-invests in the relationships.
|
||||
|
||||
---
|
||||
|
||||
## Common onboarding failures
|
||||
|
||||
**Vague expectations.** Participants do not know what feedback is wanted; ad-hoc venting fills the channels.
|
||||
|
||||
**Missing NDA where appropriate.** Beta features get screenshotted on social before the team is ready.
|
||||
|
||||
**Missing support path.** Participants hit issues, do not know who to contact, churn out of the beta.
|
||||
|
||||
**No incentive clarity.** Participants feel underrecognized; engagement decays.
|
||||
|
||||
**Welcome communication too long or too short.** Too long: participants do not read; too short: participants miss critical context.
|
||||
|
||||
**Access friction in first 24-48 hours.** Participants cannot get into the feature; many disengage permanently.
|
||||
|
||||
**Onboarding intensity mismatched to beta type.** Heavy onboarding for an open beta wastes effort; light onboarding for a design partner program under-invests.
|
||||
|
||||
---
|
||||
|
||||
## Methodology-level choices that stay in the public skill
|
||||
|
||||
The welcome communication structure. The expectations contract for both sides. NDA considerations. Feedback channel access. Support paths. Incentive disclosure. First-week onboarding. Onboarding by beta type. Common failures.
|
||||
|
||||
## Implementation choices that stay internal
|
||||
|
||||
Specific welcome email templates. Specific NDA boilerplate. Specific support routing automation. Specific incentive packages and approval workflows. The team's own conventions for onboarding intensity. These vary by team and beta type.
|
||||
Vendored
+239
@@ -0,0 +1,239 @@
|
||||
# Beta-to-GA graduation criteria
|
||||
|
||||
The six graduation criteria. The "tired of the beta" anti-pattern. The perpetual beta anti-pattern.
|
||||
|
||||
Graduation is the decision that distinguishes a structured beta from beta theater. Honest graduation criteria, applied honestly, separate "ready for GA" from "we are tired of running the beta." Defining the criteria explicitly upfront prevents calendar-driven graduation decisions later.
|
||||
|
||||
---
|
||||
|
||||
## The six graduation criteria
|
||||
|
||||
The criteria that should be met before graduating from beta to GA.
|
||||
|
||||
### 1. Critical bugs cleared
|
||||
|
||||
**The criterion.** No known crashes, data loss, or core-flow failures.
|
||||
|
||||
**The validation.** Bug tracker shows no open critical issues. The beta cohort has not reported new critical issues in the past 1-2 weeks.
|
||||
|
||||
**The exception.** Some critical issues may be acceptable if they affect a tiny segment that the GA can either exclude or address with documentation. Decisions to graduate with known issues should be explicit.
|
||||
|
||||
### 2. Friction issues addressed or accepted
|
||||
|
||||
**The criterion.** Friction issues are either fixed before GA or documented as known limitations the team is choosing not to address pre-GA.
|
||||
|
||||
**The validation.** Each friction issue from the beta has a disposition: fixed, fix-in-progress (with timeline), accepted-for-now (with rationale), accepted-permanently (with rationale).
|
||||
|
||||
**The honest disposition.** "Accepted for now" is honest if the team plans to address post-GA. "Accepted permanently" is honest if the team has decided the friction is not worth the engineering cost. Hidden friction that the team hopes nobody will notice is not honest.
|
||||
|
||||
### 3. Behavioral validation
|
||||
|
||||
**The criterion.** Beta participants are using the feature in patterns the team expected. Unexpected patterns are understood (either incorporated into the GA experience or addressed).
|
||||
|
||||
**The validation.** Usage data from the beta cohort shows the feature being used in the ways the design assumed. Significant deviations are investigated; either the design is adjusted, or the GA experience is modified to support the actual usage pattern.
|
||||
|
||||
**The unexpected-pattern handling.**
|
||||
|
||||
- Pattern A: most beta participants are using the feature in a different way than the design assumed. The design is wrong; iterate before GA.
|
||||
- Pattern B: a subset of participants is using the feature in an unexpected way that suggests an additional use case. Capture for post-GA expansion; do not delay GA.
|
||||
- Pattern C: participants are not using the feature much at all. The feature may not be solving a real problem; reconsider whether to ship.
|
||||
|
||||
### 4. Performance under load
|
||||
|
||||
**The criterion.** The feature performs adequately at the scale GA will produce.
|
||||
|
||||
**The validation.** Performance testing under projected GA load. Beta cohort performance was acceptable; the GA scale projection has been tested.
|
||||
|
||||
**The infrastructure-validation focus.** For features where scale is the primary concern (data-processing features, real-time features, multi-tenant features), this criterion is the central one. RC betas often exist primarily to validate this.
|
||||
|
||||
### 5. Documentation and support readiness
|
||||
|
||||
**The criterion.** Help docs reflect actual usage; support team is trained on common issues; escalation paths work.
|
||||
|
||||
**The validation.**
|
||||
|
||||
- Help docs match the feature as it will ship at GA.
|
||||
- Support team has been briefed and has handled at least the simulated beta-tier ticket volume.
|
||||
- Common issues are documented for the support team's reference.
|
||||
- Escalation paths from support to engineering are tested.
|
||||
|
||||
**The skip risk.** Teams often graduate before docs and support are ready. The GA launch then catches the support team off-guard; tickets pile up; users have a worse experience than they would have with proper readiness.
|
||||
|
||||
### 6. Positive signal sufficient
|
||||
|
||||
**The criterion.** Beta feedback is net-positive enough to launch with confidence.
|
||||
|
||||
**The validation.**
|
||||
|
||||
- Survey signal shows positive sentiment among beta participants.
|
||||
- Behavioral signal shows continued usage (participants are not just trying the feature once).
|
||||
- Participants would recommend the feature to others.
|
||||
|
||||
**The "sufficient" calibration.** Not all participants need to be delighted. A substantial majority finding value, with the dissenting voices understood (segment misfit, expectations mismatch, unfixable friction), is sufficient. A divided cohort with no clear majority signal is not.
|
||||
|
||||
---
|
||||
|
||||
## The "tired of the beta" anti-pattern
|
||||
|
||||
Graduation that happens because the team wants to be done with the beta.
|
||||
|
||||
**The pattern.**
|
||||
|
||||
- Beta has run for the planned duration.
|
||||
- Some criteria are met; some are not.
|
||||
- The team graduates anyway because "we have to ship at some point" or "the beta cannot run forever."
|
||||
|
||||
**Why it fails.**
|
||||
|
||||
- Unmet criteria mean the GA launches with known issues that are not yet addressed or acknowledged.
|
||||
- Support, marketing, and customer success encounter problems the beta would have caught if extended.
|
||||
- Trust degrades: customers experience friction the beta participants reported but the team did not fix.
|
||||
|
||||
**The cure.**
|
||||
|
||||
- Either extend the beta until criteria are met.
|
||||
- Or graduate with explicit acknowledgment of the unmet criteria (known issues, deferred work).
|
||||
- Or reset the beta if significant changes are needed.
|
||||
|
||||
The discipline: the graduation decision is criteria-driven, not calendar-driven. Calendar pressure can inform whether to ship a smaller scope, but it should not produce graduation despite unmet criteria.
|
||||
|
||||
---
|
||||
|
||||
## The perpetual beta anti-pattern
|
||||
|
||||
Graduation that does not happen because the beta drifts indefinitely.
|
||||
|
||||
**The pattern.**
|
||||
|
||||
- Beta runs without firm graduation criteria.
|
||||
- Issues keep surfacing; the team keeps fixing; the beta extends.
|
||||
- 6 months later, the beta is still running. The "perpetual beta" branding becomes a strategic stance ("everything is always evolving").
|
||||
- The GA commitment is avoided.
|
||||
|
||||
**Why it fails.**
|
||||
|
||||
- Beta participants experience indefinite uncertainty about the feature's status.
|
||||
- The team avoids the discipline of GA readiness; the feature stays in a less-mature state than it could be.
|
||||
- Marketing, support, and customer success cannot operate around a beta-forever feature.
|
||||
- Stakeholder trust degrades: the team is not shipping.
|
||||
|
||||
**The cure.**
|
||||
|
||||
- Force the graduation decision. Either the criteria are met (graduate) or they are not (decide what would make them met, set a timeline, commit).
|
||||
- "Perpetual beta" as a strategic stance is rare and usually a rationalization.
|
||||
- Some features genuinely need extended-beta status for valid reasons (regulatory complexity, unusual scale validation); these should be exceptions documented explicitly, not the default.
|
||||
|
||||
---
|
||||
|
||||
## Honest graduation patterns
|
||||
|
||||
When graduation criteria are mostly but not fully met.
|
||||
|
||||
**Graduation with known issues.**
|
||||
|
||||
- Some criteria fully met; one or two have known gaps.
|
||||
- Graduate with explicit acknowledgment: "We are shipping with X known limitation; documented; will address in [timeline]."
|
||||
- Communicate the known issues to support, marketing, customer success.
|
||||
- Customers who hit the known issue are not surprised; they were warned.
|
||||
|
||||
**Graduation with extended monitoring.**
|
||||
|
||||
- Behavioral signal not fully validated due to cohort limitations.
|
||||
- Graduate with monitoring infrastructure that surfaces issues at GA scale.
|
||||
- Plan for fast iteration if monitoring catches issues post-GA.
|
||||
|
||||
**Graduation with phased rollout.**
|
||||
|
||||
- All criteria met for a subset of users; less certain for broader users.
|
||||
- Graduate to the validated subset first; expand the rollout in phases.
|
||||
|
||||
These patterns preserve graduation discipline while accommodating real-world constraints.
|
||||
|
||||
---
|
||||
|
||||
## When NOT to graduate
|
||||
|
||||
Conditions that warrant extending or resetting the beta.
|
||||
|
||||
**Not to graduate.**
|
||||
|
||||
- Critical bugs are unaddressed.
|
||||
- Major friction issues affect mainline usage.
|
||||
- Behavioral signal contradicts the design assumptions.
|
||||
- Performance under projected load is inadequate.
|
||||
- Documentation and support are not ready.
|
||||
- Beta sentiment is divided without clear positive signal.
|
||||
|
||||
**The honest extension.**
|
||||
|
||||
- Acknowledge the gap explicitly.
|
||||
- Define what would close the gap.
|
||||
- Set a new timeline.
|
||||
- Communicate to participants and stakeholders.
|
||||
|
||||
**The reset.**
|
||||
|
||||
- If the gap requires significant feature changes, end the current beta and start a new one with the changed feature.
|
||||
- Do not blend "old beta" and "new feature" data.
|
||||
|
||||
---
|
||||
|
||||
## Graduation decision-making
|
||||
|
||||
Who decides graduation and how.
|
||||
|
||||
**The decision-maker.** Typically the product manager who owns the feature, with input from engineering lead, design lead, and beta program manager.
|
||||
|
||||
**The decision process.**
|
||||
|
||||
- Beta program manager prepares a graduation review document: status against each criterion, known issues, recommendation.
|
||||
- Decision meeting (60-90 minutes): review the document, discuss any open questions, make the decision.
|
||||
- Decision recorded explicitly: graduate, extend, or reset.
|
||||
|
||||
**Stakeholder visibility.** The decision is communicated to stakeholders (executives, marketing, sales, customer success) before participants are notified.
|
||||
|
||||
**Graduation timing.** Once the decision is made, graduation typically takes 1-2 weeks to execute (final code, marketing prep, support readiness, participant communication).
|
||||
|
||||
---
|
||||
|
||||
## Graduation criteria for different beta types
|
||||
|
||||
The criteria adapt to the beta type.
|
||||
|
||||
**Closed beta with calibrated cohort.** All six criteria apply. The cohort is small enough to validate behavioral signal directly.
|
||||
|
||||
**Open beta with large volume.** Behavioral signal validates at scale. Critical bugs and performance criteria are more central. Documentation and support readiness scale with the open-beta visibility.
|
||||
|
||||
**RC validation.** Performance under load is the central criterion. Other criteria should already have been met in prior alpha or beta stages.
|
||||
|
||||
**Design partner program.** The criteria apply but graduation often happens incrementally (specific design partners moving to GA terms while the program continues with new partners). Less of a single graduation moment.
|
||||
|
||||
**Internal beta.** Customer-context criteria (behavioral validation, support readiness for external) may need to be validated at GA rather than during beta. Honest disclosure: the beta did not fully validate the customer experience.
|
||||
|
||||
---
|
||||
|
||||
## Common graduation failures
|
||||
|
||||
**Calendar-driven graduation.** Graduate when the planned duration ends regardless of criteria.
|
||||
|
||||
**Criteria not defined upfront.** Graduation decision happens without explicit criteria; subjective decision.
|
||||
|
||||
**Hidden known issues.** Graduate with known issues that are not surfaced; customers and support discover them later.
|
||||
|
||||
**Perpetual beta.** Indefinite extension; graduation decision avoided.
|
||||
|
||||
**Premature graduation.** Graduate before behavioral signal has emerged or critical bugs are fully cleared.
|
||||
|
||||
**No stakeholder notification.** Graduation happens; support, marketing, customer success encounter the GA launch unprepared.
|
||||
|
||||
**No participant communication about graduation.** Beta participants are not told about graduation timing or what changes for them.
|
||||
|
||||
---
|
||||
|
||||
## Methodology-level choices that stay in the public skill
|
||||
|
||||
The six graduation criteria. The "tired of the beta" anti-pattern. The perpetual beta anti-pattern. Honest graduation patterns. When not to graduate. Graduation decision-making. Graduation criteria for different beta types. Common failures.
|
||||
|
||||
## Implementation choices that stay internal
|
||||
|
||||
Specific graduation review document templates. Specific decision-meeting formats. Specific stakeholder notification workflows. The team's own conventions for graduation timing. These vary by team and tooling.
|
||||
+228
@@ -0,0 +1,228 @@
|
||||
# Beta type decisions
|
||||
|
||||
Closed/open, alpha/beta/RC, internal/external, time-bounded/open-ended. The combination decision and how it matches signal need.
|
||||
|
||||
Beta type is the upstream decision that constrains everything downstream: who participates, what feedback channels make sense, what graduation looks like. Getting the type wrong makes the rest of the program harder.
|
||||
|
||||
---
|
||||
|
||||
## Closed vs open
|
||||
|
||||
The cohort-control axis.
|
||||
|
||||
**Closed beta.** Invite-only. Participants are selected by the team based on criteria. Cohort is bounded.
|
||||
|
||||
**Strengths.**
|
||||
|
||||
- Calibrated cohort: the team knows who is in the beta and can match participants to the GA user profile.
|
||||
- Quality of feedback: invited participants typically engage more substantively than self-selected open-beta users.
|
||||
- NDA enforceability: closed cohorts can sign NDAs; open cohorts usually cannot.
|
||||
- Synthesis tractability: bounded cohort means feedback volume is manageable.
|
||||
|
||||
**Weaknesses.**
|
||||
|
||||
- Recruiting overhead: identifying and inviting participants is real work.
|
||||
- Limited diversity: the cohort reflects the team's recruiting choices; gaps in selection produce gaps in feedback.
|
||||
- Slower feedback volume: smaller cohorts produce less total feedback.
|
||||
|
||||
**Open beta.** Anyone can join. Cohort is self-selecting.
|
||||
|
||||
**Strengths.**
|
||||
|
||||
- Volume: large numbers of participants quickly.
|
||||
- No recruiting overhead: participants opt in.
|
||||
- Marketing value: open betas can build pre-launch audience awareness.
|
||||
|
||||
**Weaknesses.**
|
||||
|
||||
- Self-selection bias: early adopters and enthusiasts skew the cohort; their feedback may not represent the broader target user.
|
||||
- Signal-to-noise ratio: most participants do not provide actionable feedback; the team must mine signal from volume.
|
||||
- NDA difficulty: open cohorts cannot reasonably enforce NDAs; the feature is essentially public.
|
||||
|
||||
---
|
||||
|
||||
## Alpha vs beta vs RC
|
||||
|
||||
The polish axis.
|
||||
|
||||
**Alpha.**
|
||||
|
||||
- Very early. Significant bugs expected.
|
||||
- Internal users or trusted partners only.
|
||||
- Goal: surface fundamental issues before broader exposure.
|
||||
- Feedback orientation: bug discovery, fundamental flow validation.
|
||||
|
||||
**Beta.**
|
||||
|
||||
- More polished. Major bugs caught; remaining issues are friction or edge cases.
|
||||
- Broader cohort. External customers in calibrated cohorts.
|
||||
- Goal: validate the feature works for real users in real contexts.
|
||||
- Feedback orientation: usage patterns, friction, behavioral signal, edge cases.
|
||||
|
||||
**RC (release candidate).**
|
||||
|
||||
- Essentially launch-ready. Production-grade quality expected.
|
||||
- Cohort can be large (open beta or extended beta).
|
||||
- Goal: last validation before GA, performance at scale, infrastructure readiness.
|
||||
- Feedback orientation: scale issues, infrastructure issues, last-mile polish.
|
||||
|
||||
**The progression.** Many features pass through all three (alpha → beta → RC) before GA. Some skip alpha (sufficient internal testing) or skip RC (the beta is the last validation). The decision depends on feature complexity and risk tolerance.
|
||||
|
||||
---
|
||||
|
||||
## Internal vs external
|
||||
|
||||
The audience axis.
|
||||
|
||||
**Internal beta.** Only employees use the feature.
|
||||
|
||||
**Strengths.**
|
||||
|
||||
- Fast feedback: employees are easy to recruit and follow up with.
|
||||
- High engagement: employees usually feel some ownership of company products.
|
||||
- NDA simplicity: confidentiality is implicit.
|
||||
|
||||
**Weaknesses.**
|
||||
|
||||
- Missing customer context: employees experience features differently than customers (familiarity, infrastructure context, motivations).
|
||||
- Bias toward team-known patterns: employees use products in ways the team designed for; customers often use products differently.
|
||||
- Limited signal: internal-only cannot validate customer-context complexity.
|
||||
|
||||
**External beta.** Real customers use the feature.
|
||||
|
||||
**Strengths.**
|
||||
|
||||
- Real customer experience: feedback reflects how customers actually use the product.
|
||||
- Behavioral signal: usage patterns from real customers inform GA decisions.
|
||||
- Trust building: customers who beta-test become advocates.
|
||||
|
||||
**Weaknesses.**
|
||||
|
||||
- Requires customer relationship: cannot just turn the feature on for employees.
|
||||
- Recruiting overhead: identifying willing customers and managing the cohort.
|
||||
- Risk: bugs reaching customers can damage trust if not handled well.
|
||||
|
||||
**The combination.** Most strong betas pass through both: internal alpha, then external beta. Some skip internal (when internal use cases differ enough from customer use cases that internal validation is misleading).
|
||||
|
||||
---
|
||||
|
||||
## Time-bounded vs open-ended
|
||||
|
||||
The duration axis.
|
||||
|
||||
**Time-bounded beta.** A defined end date. Common durations: 4 weeks, 6 weeks, 8 weeks, 12 weeks.
|
||||
|
||||
**Strengths.**
|
||||
|
||||
- Forces the graduation decision. The end date arrives; the team must decide ready or not.
|
||||
- Clarity for participants: they know how long they are committing.
|
||||
- Resource bounding: the team's beta-running effort is bounded.
|
||||
|
||||
**Weaknesses.**
|
||||
|
||||
- Calendar pressure can force premature graduation: "we are at the end date so we are graduating" regardless of signal.
|
||||
- Some signals need longer to surface: behavioral patterns may not be visible in 4 weeks.
|
||||
|
||||
**Open-ended beta.** No defined end. The beta runs until the team decides to graduate.
|
||||
|
||||
**Strengths.**
|
||||
|
||||
- Signal-driven graduation: the team graduates when the criteria are met, regardless of calendar.
|
||||
- Allows long-running validation: behavioral signal can develop over months.
|
||||
- Suits design partner programs: ongoing relationships rather than time-bounded cohorts.
|
||||
|
||||
**Weaknesses.**
|
||||
|
||||
- Beta-purgatory risk: beta runs indefinitely because nobody forces the graduation decision.
|
||||
- Participant fatigue: open-ended commitments without clear duration drain engagement.
|
||||
- Resource drain: the team's beta-running effort is open-ended.
|
||||
|
||||
**The default.** Most betas should be time-bounded. Open-ended is appropriate for design partner programs and specific extended-validation scenarios.
|
||||
|
||||
---
|
||||
|
||||
## The combination decision
|
||||
|
||||
How to choose across the four axes.
|
||||
|
||||
**Worked combinations.**
|
||||
|
||||
**Standard structured beta:** closed + beta + external + time-bounded (6-8 weeks).
|
||||
|
||||
- Use when: shipping a meaningful feature that needs validation before GA. Most common combination.
|
||||
|
||||
**Alpha:** closed + alpha + internal + open-ended (typically 2-6 weeks of internal testing before external alpha).
|
||||
|
||||
- Use when: very early feature; need to surface fundamental issues before exposing customers.
|
||||
|
||||
**Design partner program:** closed + alpha or beta + external + open-ended.
|
||||
|
||||
- Use when: building a feature with deep customer involvement; small set of partner customers (3-10) collaborating closely on shaping the feature.
|
||||
|
||||
**Open early access:** open + beta or RC + external + time-bounded (4-12 weeks).
|
||||
|
||||
- Use when: pre-GA marketing matters; the feature is sufficiently polished that early access can build audience; team can handle the volume.
|
||||
|
||||
**RC validation:** open or closed + RC + external + time-bounded (2-4 weeks).
|
||||
|
||||
- Use when: the feature is essentially launch-ready; need last validation at scale or in the production environment.
|
||||
|
||||
**Internal-only RC:** closed + RC + internal + time-bounded.
|
||||
|
||||
- Use when: the feature is for internal users (e.g., admin tools used by support team), or when external testing is impractical for the type of feature.
|
||||
|
||||
---
|
||||
|
||||
## When the combination decision goes wrong
|
||||
|
||||
Common mismatches.
|
||||
|
||||
**Open + alpha.** Open cohorts on an alpha-stage feature exposes customers to bugs the team has not caught. Damages trust. Cure: alpha should be closed; open up at beta stage when the feature is more polished.
|
||||
|
||||
**Closed + RC.** Closed RCs miss the at-scale validation that RCs are meant to provide. The cohort is too small to surface scale issues. Cure: RCs are usually open or large-closed.
|
||||
|
||||
**External + alpha + open-ended.** External customers commit to an alpha that has no end date and many bugs. Engagement decays. Cure: alpha should be internal or trusted-partner only; external alpha should be time-bounded and limited.
|
||||
|
||||
**Open + beta + open-ended.** Volume cohort with no end date. The beta runs forever; participants lose interest; the team cannot synthesize. Cure: time-bound the beta; force graduation decision.
|
||||
|
||||
---
|
||||
|
||||
## Beta type for specific contexts
|
||||
|
||||
Common contexts and the typical type combinations.
|
||||
|
||||
**B2B SaaS feature launch.** Closed + beta + external + time-bounded. 20-200 participants from existing customer base, 6-8 weeks.
|
||||
|
||||
**Consumer product launch.** Open + beta + external + time-bounded (or open + RC). 1,000-10,000+ participants, 4-8 weeks. Marketing value is part of the rationale.
|
||||
|
||||
**Enterprise platform major release.** Closed + alpha + design-partner + open-ended initially, then closed + beta + extended cohort + time-bounded for validation.
|
||||
|
||||
**Developer-tool launch.** Open + beta + external + time-bounded, with public roadmap and community feedback channels.
|
||||
|
||||
**Internal tool launch.** Closed + alpha or beta + internal + time-bounded. The cohort is the internal users who will use the tool post-GA.
|
||||
|
||||
**Compliance-impacting feature.** Closed + extended beta + external + carefully selected design partners. The validation needs to surface compliance edge cases before GA.
|
||||
|
||||
---
|
||||
|
||||
## Common beta-type failures
|
||||
|
||||
**Defaulting to soft-launch.** Skipping beta-type decisions and just turning the feature on for some users. Decide the type explicitly.
|
||||
|
||||
**Defaulting to open beta for everything.** Open volume substituted for calibrated cohorts. Open is right for some contexts; not for all.
|
||||
|
||||
**Mismatching alpha/beta/RC to feature polish.** Calling something "beta" when it is alpha (too many bugs); calling something "RC" when it is beta (not yet production-grade).
|
||||
|
||||
**Internal-only when external context matters.** Validates an internal experience that does not match what customers will encounter.
|
||||
|
||||
**Open-ended without graduation criteria.** Beta drifts into perpetual beta because no firm end was set.
|
||||
|
||||
---
|
||||
|
||||
## Methodology-level choices that stay in the public skill
|
||||
|
||||
The four axes (closed/open, alpha/beta/RC, internal/external, time-bounded/open-ended). Strengths and weaknesses per axis. Worked combinations. Common mismatches. Beta type for specific contexts. Common failures.
|
||||
|
||||
## Implementation choices that stay internal
|
||||
|
||||
Specific platform feature-flagging configurations. Specific recruitment platforms and processes. Specific NDA templates. Specific time-bounding workflows. The team's own conventions for beta-type decisions in different contexts. These vary by team and tooling.
|
||||
+231
@@ -0,0 +1,231 @@
|
||||
# Beta wind-down communication
|
||||
|
||||
Graduation announcement, transition, recognition, postmortem. Treating participants well.
|
||||
|
||||
The beta's wind-down is its closing impression. Done well, participants leave the beta engaged and willing to participate in future betas. Done badly, participants feel discarded after providing significant feedback.
|
||||
|
||||
---
|
||||
|
||||
## The graduation announcement
|
||||
|
||||
Communication to participants when the beta graduates.
|
||||
|
||||
**Timing.** 1-2 weeks before graduation, with confirmation at graduation.
|
||||
|
||||
**Content.**
|
||||
|
||||
- The feature is graduating to GA. Specific date.
|
||||
- What changes for participants.
|
||||
- What does not change.
|
||||
- Recognition or thank-you for participation.
|
||||
- Information about post-GA support, pricing, or special terms.
|
||||
- Any beta-specific features or terms that will not carry to GA.
|
||||
|
||||
**Tone.** Warm, appreciative. Participants invested time; the announcement reflects that.
|
||||
|
||||
**Length.** 300-600 words. Long enough to cover the necessary information; short enough to be readable.
|
||||
|
||||
---
|
||||
|
||||
## What changes for participants at graduation
|
||||
|
||||
**Continued access.** Most beta participants retain access to the feature post-GA. The beta was their preview; GA continues their use.
|
||||
|
||||
**Pricing transitions.** If the feature has paid tiers, participants need to know:
|
||||
|
||||
- Does beta access include free use of the feature post-GA for some period?
|
||||
- Does the feature require an upgraded plan for full access?
|
||||
- Are there special pricing terms for beta participants (early-bird discount, lifetime grandfathering, etc.)?
|
||||
|
||||
**Feature stability.** Communicate what level of stability participants should expect post-GA. Beta features sometimes have rough edges; GA implies stability commitments.
|
||||
|
||||
**Support transition.** Beta-aware support routing typically ends at GA. Participants now use standard support channels.
|
||||
|
||||
**Beta-only features.** Some features in the beta may not make GA (deprecated, simplified, removed). Participants who relied on those features need clear communication about alternatives.
|
||||
|
||||
---
|
||||
|
||||
## Recognition
|
||||
|
||||
Beta participants invested time providing feedback. Recognition matters.
|
||||
|
||||
**Forms of recognition.**
|
||||
|
||||
- **Named in changelog or launch communications** (with consent).
|
||||
- **Gift cards or compensation** for substantial time investment.
|
||||
- **Swag** for closed-beta participants.
|
||||
- **Advance access to future betas.**
|
||||
- **Direct thank-you from product team**, often via personal email.
|
||||
- **Public acknowledgment** in marketing or community materials.
|
||||
|
||||
**Calibration.**
|
||||
|
||||
- Light betas: direct thank-you, possibly modest swag.
|
||||
- Standard betas: thank-you, swag, post-GA continued access on favorable terms.
|
||||
- Design partner programs: substantial recognition, sometimes including case studies, named partnerships, financial compensation.
|
||||
|
||||
**The discipline.** Recognition matches the participant's investment. Light recognition for a heavy commitment feels dismissive; heavy recognition for a light commitment is unnecessary.
|
||||
|
||||
---
|
||||
|
||||
## The post-beta survey
|
||||
|
||||
A final feedback collection at graduation.
|
||||
|
||||
**Purpose.** Capture overall reflections on the beta experience and the feature.
|
||||
|
||||
**Content.**
|
||||
|
||||
- Overall feature satisfaction.
|
||||
- Likelihood to continue using post-GA.
|
||||
- Likelihood to recommend.
|
||||
- What worked well in the beta program (process feedback, not feature feedback).
|
||||
- What could be improved in future betas.
|
||||
- Optional open-ended reflections.
|
||||
|
||||
**Length.** 5-10 questions, 5-10 minutes to complete.
|
||||
|
||||
**Why it matters.** The post-beta survey closes the loop with participants and informs the team's beta-program practice. The process feedback is particularly valuable: future betas improve based on past feedback.
|
||||
|
||||
---
|
||||
|
||||
## The beta postmortem
|
||||
|
||||
Internal review of what the beta produced.
|
||||
|
||||
**Timing.** Within 1-2 weeks of graduation.
|
||||
|
||||
**Participants.** Beta program manager, product manager, engineering lead, design lead, customer success lead, support lead.
|
||||
|
||||
**Content.**
|
||||
|
||||
- What was learned from the beta? (Patterns, behavioral validation, friction discovery.)
|
||||
- What changed in the GA launch as a result?
|
||||
- What worked well in the beta program (process)?
|
||||
- What did not work? What would the team do differently next time?
|
||||
- What patterns recur across multiple betas? Are there lessons for the broader practice?
|
||||
|
||||
**Output.** A short postmortem document. Surfaces lessons. Informs future betas.
|
||||
|
||||
**Why it matters.** Beta programs improve through accumulated learning. Without postmortems, the team repeats the same mistakes; with postmortems, the practice gets sharper over time.
|
||||
|
||||
---
|
||||
|
||||
## Recruiting for future betas
|
||||
|
||||
The wind-down is a recruiting moment for future betas.
|
||||
|
||||
**The pattern.** Participants who had a good beta experience are likely to participate in future ones. The wind-down communication can include an invitation: would they like to be considered for future betas?
|
||||
|
||||
**The benefits.**
|
||||
|
||||
- Builds a roster of engaged beta participants for future programs.
|
||||
- Reduces recruiting overhead for future betas.
|
||||
- Strengthens the participant relationship.
|
||||
|
||||
**The discipline.** Do not over-commit; future betas should not be promised in ways that are not honored. The invitation is to be considered, not a guarantee.
|
||||
|
||||
---
|
||||
|
||||
## Handling beta-only features that do not make GA
|
||||
|
||||
Sometimes beta features include capabilities that are removed or simplified at GA.
|
||||
|
||||
**Why it happens.**
|
||||
|
||||
- The feature scope was reduced based on beta findings.
|
||||
- Some capabilities did not perform well enough to ship at GA.
|
||||
- The team learned the capability was not load-bearing.
|
||||
|
||||
**The communication.**
|
||||
|
||||
- Surface the change explicitly. Do not silently remove.
|
||||
- Explain the reasoning where appropriate.
|
||||
- Provide alternatives or workarounds for participants who relied on the removed capability.
|
||||
- Acknowledge the impact on participants.
|
||||
|
||||
**The participant impact.** Some participants may push back; their usage assumed the capability would persist. The team must decide whether to extend support, offer migration help, or accept the participant churn.
|
||||
|
||||
---
|
||||
|
||||
## Special cases: extended beta
|
||||
|
||||
Some betas extend beyond their planned duration.
|
||||
|
||||
**Communication for extension.**
|
||||
|
||||
- Tell participants when the extension is decided, not when the original end date passes.
|
||||
- Explain why the extension is needed.
|
||||
- Give a specific new end date.
|
||||
- Acknowledge the participant impact (they committed to the original timeline).
|
||||
- Provide an option to opt out if the extension is significant.
|
||||
|
||||
**Avoid.**
|
||||
|
||||
- Silent extensions where the planned end passes without acknowledgment.
|
||||
- Multiple extensions that erode the timeline credibility.
|
||||
- Extensions framed as "no big deal" when they affect participants' ongoing time investment.
|
||||
|
||||
---
|
||||
|
||||
## Special cases: beta cancellation
|
||||
|
||||
Sometimes the team decides not to graduate the feature to GA.
|
||||
|
||||
**Why it happens.**
|
||||
|
||||
- The beta revealed the feature does not work as intended.
|
||||
- Strategic shift redirected resources.
|
||||
- The feature would compete poorly at GA scale.
|
||||
|
||||
**The communication.**
|
||||
|
||||
- Be honest about the cancellation.
|
||||
- Acknowledge the participants' time investment.
|
||||
- Explain (at appropriate level of detail) why the cancellation.
|
||||
- Discuss what happens to participants' beta data, configurations, etc.
|
||||
- Recognize the participation despite the cancellation.
|
||||
|
||||
**The participant impact.** Cancellation can frustrate participants who invested time. Honest communication and good recognition mitigate the impact.
|
||||
|
||||
---
|
||||
|
||||
## Long-term participant relationships
|
||||
|
||||
Beta participants represent ongoing relationships, not transactional interactions.
|
||||
|
||||
**The relationship investment.**
|
||||
|
||||
- Participants who had a good beta experience may become advocates, references, case study subjects.
|
||||
- Future product strategy benefits from continued conversation with beta alumni.
|
||||
- Customer success can use beta participation as relationship signal.
|
||||
|
||||
**The maintenance.** Periodic check-ins with notable beta participants strengthen relationships even outside formal beta programs. Light-touch communication (annual newsletter, occasional product updates, personalized outreach for major launches) maintains the connection.
|
||||
|
||||
---
|
||||
|
||||
## Common wind-down failures
|
||||
|
||||
**Silent graduation.** Beta participants discover graduation through the public launch announcement rather than through advance communication.
|
||||
|
||||
**Vague transition information.** Participants do not know what changes for them; uncertainty produces churn.
|
||||
|
||||
**Insufficient recognition.** Heavy participation rewarded with thin thank-you; participants feel dismissed.
|
||||
|
||||
**Missing post-beta survey.** Process feedback is lost; future betas do not improve.
|
||||
|
||||
**No postmortem.** Internal lessons are lost; the team repeats mistakes.
|
||||
|
||||
**Surprise feature removals.** Beta-only features removed without warning; participants discover at GA that capabilities they relied on are gone.
|
||||
|
||||
**No invitation to future betas.** The relationship ends at graduation; future betas restart recruitment from scratch.
|
||||
|
||||
---
|
||||
|
||||
## Methodology-level choices that stay in the public skill
|
||||
|
||||
The graduation announcement structure. What changes for participants. Recognition forms and calibration. The post-beta survey. The beta postmortem. Recruiting for future betas. Handling beta-only feature removals. Extended betas. Beta cancellations. Long-term relationships. Common failures.
|
||||
|
||||
## Implementation choices that stay internal
|
||||
|
||||
Specific graduation announcement templates. Specific recognition packages and approval. Specific postmortem templates. Specific CRM tracking of beta alumni. The team's own conventions for relationship maintenance. These vary by team.
|
||||
+207
@@ -0,0 +1,207 @@
|
||||
# Cohort sizing patterns
|
||||
|
||||
Saturation patterns by feedback type. Sizing decisions for different beta goals. The size-matches-signal principle.
|
||||
|
||||
Cohort size is a calibration decision, not a maximize-volume decision. Each beta has a specific signal need; the right cohort size is the smallest that produces that signal reliably.
|
||||
|
||||
---
|
||||
|
||||
## Saturation patterns by feedback type
|
||||
|
||||
Different kinds of feedback saturate at different cohort sizes.
|
||||
|
||||
**Critical bugs (crashes, data loss, broken core flows).**
|
||||
|
||||
- Saturate fast: most surface in the first 1-2 weeks with 20-30 participants.
|
||||
- Beyond ~50 participants, additional volume produces few new critical bugs.
|
||||
- The cohort size for bug discovery: 20-50 participants is usually sufficient.
|
||||
|
||||
**Friction issues (workflow interruptions, confusing flows, slow performance in specific cases).**
|
||||
|
||||
- Saturate moderately: most surface in 2-4 weeks with 50-100 participants.
|
||||
- Volume helps surface friction in less-common usage patterns.
|
||||
- The cohort size for friction discovery: 50-200 participants typical.
|
||||
|
||||
**Behavioral patterns (how users actually use the feature, what flows they follow, what features they ignore).**
|
||||
|
||||
- Saturate slowly: 4-8 weeks with 100-500 participants needed for clear patterns.
|
||||
- Patterns require usage volume; small cohorts may not generate enough usage to see patterns.
|
||||
- The cohort size for behavioral signal: 100-500+ participants typical.
|
||||
|
||||
**Edge cases (unusual configurations, rare usage contexts, specific environment combinations).**
|
||||
|
||||
- Saturate very slowly: 500+ participants needed; some edge cases never surface in beta and are discovered post-GA.
|
||||
- Volume is the only way to surface low-frequency edge cases.
|
||||
- The cohort size for edge case discovery: 500-5,000+ participants; even at this scale, rare cases may slip through.
|
||||
|
||||
**Performance under load (scale-related issues, infrastructure constraints, concurrent-use issues).**
|
||||
|
||||
- Saturate when cohort exceeds the load threshold the issue requires.
|
||||
- 1,000-10,000+ participants for at-scale validation.
|
||||
- Often the central goal of RC betas.
|
||||
|
||||
---
|
||||
|
||||
## Sizing decisions for different beta goals
|
||||
|
||||
The cohort size matches what the team needs to learn.
|
||||
|
||||
**Goal: Catch critical bugs before GA.**
|
||||
|
||||
- Cohort size: 20-50 participants.
|
||||
- Duration: 2-4 weeks.
|
||||
- Closed cohort, calibrated to GA user profile.
|
||||
- Most critical bugs surface fast; beyond this, returns diminish.
|
||||
|
||||
**Goal: Validate behavioral assumptions about how users will use the feature.**
|
||||
|
||||
- Cohort size: 100-300 participants.
|
||||
- Duration: 4-8 weeks.
|
||||
- Closed cohort with variety across usage patterns.
|
||||
- Behavioral patterns need usage volume to emerge clearly.
|
||||
|
||||
**Goal: Validate product-market fit assumptions for a major new feature.**
|
||||
|
||||
- Cohort size: 200-500 participants.
|
||||
- Duration: 8-12 weeks.
|
||||
- Closed cohort spanning segments.
|
||||
- Long enough duration to see retention and continued usage, not just initial engagement.
|
||||
|
||||
**Goal: Validate at-scale infrastructure for a launch.**
|
||||
|
||||
- Cohort size: 1,000-5,000+ participants.
|
||||
- Duration: 4-8 weeks.
|
||||
- Often open beta or large closed RC.
|
||||
- Volume is the point; calibration is less important than scale.
|
||||
|
||||
**Goal: Build a design partner program for ongoing collaboration.**
|
||||
|
||||
- Cohort size: 3-10 partners.
|
||||
- Duration: open-ended (months to years).
|
||||
- Highly calibrated cohort with strong relationships.
|
||||
- Depth over breadth; the program is qualitative collaboration, not at-scale validation.
|
||||
|
||||
**Goal: Generate pre-launch marketing and audience.**
|
||||
|
||||
- Cohort size: 1,000-10,000+ participants.
|
||||
- Duration: 4-12 weeks.
|
||||
- Open beta with marketing-driven recruitment.
|
||||
- The cohort serves both validation and pre-launch buzz.
|
||||
|
||||
---
|
||||
|
||||
## The size-matches-signal principle
|
||||
|
||||
The cohort should be the smallest size that produces the signal the team needs.
|
||||
|
||||
**Why "smaller is better when calibrated."**
|
||||
|
||||
- Smaller cohorts produce more synthesizable feedback. The team can read every transcript, review every survey response, follow up with every participant who reports an issue.
|
||||
- Smaller cohorts make participant relationships stronger. Each participant feels seen; engagement is higher.
|
||||
- Larger cohorts produce volume that can drown signal. The team cannot synthesize 5,000 pieces of feedback as well as 50.
|
||||
|
||||
**When larger is necessary.**
|
||||
|
||||
- The team needs at-scale validation (load, concurrent users, edge cases).
|
||||
- The team needs marketing reach.
|
||||
- The team needs behavioral signal that requires substantial usage volume.
|
||||
|
||||
**The discipline.** Default to the smallest cohort that produces the needed signal. Justify any larger size against specific signal needs.
|
||||
|
||||
---
|
||||
|
||||
## Cohort size and feedback channel design
|
||||
|
||||
Larger cohorts require different feedback channel design than smaller ones.
|
||||
|
||||
**For cohorts of 5-50.**
|
||||
|
||||
- Direct channels work: email, dedicated Slack, structured interviews.
|
||||
- The team can engage with each participant individually.
|
||||
- Synthesis can include reviewing all feedback.
|
||||
|
||||
**For cohorts of 50-500.**
|
||||
|
||||
- Mixed channels: structured surveys + sample interviews + in-product feedback widgets.
|
||||
- Sampling required for synthesis: review all surveys, sample interviews and tickets.
|
||||
|
||||
**For cohorts of 500-5,000.**
|
||||
|
||||
- Aggregated channels: in-product feedback widgets, support ticket aggregation, automated surveys.
|
||||
- Heavy sampling: review aggregate patterns, sample individual feedback.
|
||||
|
||||
**For cohorts of 5,000+.**
|
||||
|
||||
- Volume aggregation: NPS-style scoring, automated categorization, statistical analysis of usage patterns.
|
||||
- Individual feedback rarely reviewed; patterns are the signal.
|
||||
|
||||
The implication. Beta planning includes feedback channel design appropriate to cohort size. Mismatches (small cohort with aggregated channels, or large cohort with direct channels) produce friction.
|
||||
|
||||
---
|
||||
|
||||
## Adjusting cohort size mid-beta
|
||||
|
||||
Sometimes the team realizes mid-beta that the cohort is wrong-sized.
|
||||
|
||||
**Cohort too small.**
|
||||
|
||||
- Symptom: feedback volume is insufficient to see patterns.
|
||||
- Cure: open recruitment for additional participants, applying the same selection criteria.
|
||||
- Caution: late additions have less time in the beta; their feedback covers less of the beta period.
|
||||
|
||||
**Cohort too large.**
|
||||
|
||||
- Symptom: feedback volume overwhelms synthesis capacity; the team is reactive rather than analytical.
|
||||
- Cure: usually do not reduce; instead, scale up synthesis capacity (more reviewers, more aggregation tooling). Reducing cohort feels like a betrayal to participants.
|
||||
- Prevention: better sizing decision upstream.
|
||||
|
||||
**Cohort skewed.**
|
||||
|
||||
- Symptom: feedback patterns reflect skew (one segment over-represented).
|
||||
- Cure: targeted recruitment to balance the cohort, or explicit acknowledgment of skew in synthesis.
|
||||
- The cohort cannot always be re-balanced quickly; sometimes the synthesis adjusts for the skew rather than the cohort.
|
||||
|
||||
---
|
||||
|
||||
## Cohort and beta duration
|
||||
|
||||
Cohort size and duration interact.
|
||||
|
||||
**Short beta (2-4 weeks).** Smaller cohort works because feedback saturates faster on critical issues. 20-100 participants typical.
|
||||
|
||||
**Medium beta (4-8 weeks).** Mid-size cohort matches the duration. 50-300 participants typical.
|
||||
|
||||
**Long beta (8+ weeks).** Larger cohort works because behavioral signal needs duration. 100-1,000+ participants.
|
||||
|
||||
**The mismatch failures.**
|
||||
|
||||
- Long beta with small cohort: insufficient volume; the duration produces no proportional signal.
|
||||
- Short beta with very large cohort: insufficient time; the volume produces no proportional learning.
|
||||
|
||||
The matching. Beta duration and cohort size both follow from signal need; they should be consistent.
|
||||
|
||||
---
|
||||
|
||||
## Common cohort sizing failures
|
||||
|
||||
**Defaulting to "more is better."** Large cohorts where small calibrated ones would produce stronger signal.
|
||||
|
||||
**Sizing without reference to signal need.** Cohort size set arbitrarily; team cannot defend why this size.
|
||||
|
||||
**Cohort size mismatched to duration.** Small cohort in a long beta produces sparse signal; large cohort in a short beta produces noise.
|
||||
|
||||
**Cohort size mismatched to feedback channel design.** Direct channels with too many participants overwhelm; aggregated channels with too few participants under-utilize.
|
||||
|
||||
**Mid-beta cohort changes without synthesis adjustment.** Cohort grows or shrinks; the synthesis approach does not adapt.
|
||||
|
||||
**Confusing volume with signal.** Larger cohort numbers reported as success; the team did not actually learn proportionally more.
|
||||
|
||||
---
|
||||
|
||||
## Methodology-level choices that stay in the public skill
|
||||
|
||||
The saturation patterns by feedback type. Sizing decisions for different beta goals. The size-matches-signal principle. Cohort size and feedback channel design alignment. Adjusting cohort size mid-beta. Cohort and beta duration interaction. Common failures.
|
||||
|
||||
## Implementation choices that stay internal
|
||||
|
||||
Specific recruitment automation tooling. Specific aggregation tooling for large cohorts. Specific synthesis processes for different cohort sizes. The team's own conventions for sizing within the bands. These vary by team and tooling.
|
||||
+205
@@ -0,0 +1,205 @@
|
||||
# Common beta failures
|
||||
|
||||
Ten-plus failure patterns with diagnoses and cures. The cross-cutting pattern: most beta failures share a single root, which is treating beta as ceremony rather than as decision input.
|
||||
|
||||
---
|
||||
|
||||
## Failure 1: Our beta produced no signal
|
||||
|
||||
**Symptom.** The beta ran. The team has nothing actionable to show for it. The GA launch will happen with the same uncertainty the beta was supposed to address.
|
||||
|
||||
**Diagnosis.** Soft-launch pattern. No structured selection, no defined feedback collection, no graduation criteria.
|
||||
|
||||
**Cure.** Restructure the beta. Define the cohort, channels, criteria, and triage cadence. If the current beta cannot be saved, plan a more structured beta for the next feature.
|
||||
|
||||
**Prevention.** Plan beta structure at the start, not after the beta has been running.
|
||||
|
||||
---
|
||||
|
||||
## Failure 2: Our beta has 5,000 users and we cannot synthesize
|
||||
|
||||
**Symptom.** Open beta or large cohort. Volume is high. The team is reactive rather than analytical. Synthesis cannot keep up.
|
||||
|
||||
**Diagnosis.** Kitchen-sink. Cohort too large for the structured signal the team needs.
|
||||
|
||||
**Cure.** Two paths. Scale up synthesis capacity (more reviewers, aggregation tooling). Or reduce the active cohort by focusing structured channels on a calibrated subset (e.g., select 200 active participants for interviews; let the rest contribute through aggregated channels).
|
||||
|
||||
**Prevention.** Size cohort to match synthesis capacity. Larger cohorts require aggregated feedback infrastructure.
|
||||
|
||||
---
|
||||
|
||||
## Failure 3: Our beta participants never gave feedback
|
||||
|
||||
**Symptom.** Few survey responses. Few in-product widget submissions. Few interview signups. The cohort is silent.
|
||||
|
||||
**Diagnosis.** Onboarding contract was unclear or feedback channels were friction-laden. Participants did not know what was expected or could not easily give feedback.
|
||||
|
||||
**Cure.** Re-engage. Send specific, prompted requests for feedback. Make the channels easier (in-product prompts, simpler forms). Communicate what is being heard from those who do respond.
|
||||
|
||||
**Prevention.** Onboarding makes feedback expectations explicit. Channels are designed for low friction.
|
||||
|
||||
---
|
||||
|
||||
## Failure 4: We graduated to GA on schedule but launched with critical bugs
|
||||
|
||||
**Symptom.** The GA launches. Critical issues that the beta cohort would have surfaced (or did surface but were not addressed) appear post-GA.
|
||||
|
||||
**Diagnosis.** Graduation criteria were not enforced. The decision was calendar-driven; the team graduated before the criteria were met.
|
||||
|
||||
**Cure.** Damage control: address the bugs quickly, communicate transparently, reset support expectations.
|
||||
|
||||
**Prevention.** Graduation criteria are enforced honestly. The decision is criteria-driven, not calendar-driven. If criteria are not met, extend the beta or graduate with explicit acknowledgment of unmet criteria.
|
||||
|
||||
---
|
||||
|
||||
## Failure 5: Our beta has been running for 8 months with no graduation
|
||||
|
||||
**Symptom.** Beta has run far longer than planned. No firm graduation date. The team has avoided the GA decision.
|
||||
|
||||
**Diagnosis.** Perpetual beta. No firm graduation criteria; the team avoided commitment.
|
||||
|
||||
**Cure.** Force the graduation decision. Define criteria explicitly. Decide: graduate now, graduate by a specific date, or reset the beta.
|
||||
|
||||
**Prevention.** Time-bound the beta from the start. Define graduation criteria upfront. Force the decision when the criteria are met or when the time is up.
|
||||
|
||||
---
|
||||
|
||||
## Failure 6: Beta participants vented on Twitter before the launch
|
||||
|
||||
**Symptom.** Beta participants posted screenshots, mentioned the feature publicly, or discussed the beta outside the cohort.
|
||||
|
||||
**Diagnosis.** NDA missing or unclear. Trust violation early erodes participant willingness; broader visibility may damage launch plans.
|
||||
|
||||
**Cure.** Damage control depending on impact. Reach out to participants individually. Adjust the launch plan if the leaked information affects positioning.
|
||||
|
||||
**Prevention.** NDAs in place where appropriate. Confidentiality expectations explicit in onboarding. Cohort selection includes trust assessment.
|
||||
|
||||
---
|
||||
|
||||
## Failure 7: The beta surfaced patterns we did not act on
|
||||
|
||||
**Symptom.** The beta produced clear feedback about specific issues. The GA launches without addressing them. Customers hit the same issues post-GA.
|
||||
|
||||
**Diagnosis.** Mid-beta triage missing. Feedback was collected but not used during the beta.
|
||||
|
||||
**Cure.** For the GA: address the issues quickly post-launch; communicate transparently. For future betas: implement the triage cadence and iteration discipline.
|
||||
|
||||
**Prevention.** Weekly triage cadence. Categorization of feedback. Iteration on critical and high-impact items during the beta.
|
||||
|
||||
---
|
||||
|
||||
## Failure 8: The GA launch surprised us
|
||||
|
||||
**Symptom.** Issues emerge at GA that the team did not anticipate from the beta. The beta did not actually validate the GA experience.
|
||||
|
||||
**Diagnosis.** Cohort or feedback structure was wrong. The cohort did not match the GA user; the channels did not surface the kinds of issues the GA exposed.
|
||||
|
||||
**Cure.** Address the surprises post-GA. Investigate the gap between beta and GA experience. Apply lessons to future betas.
|
||||
|
||||
**Prevention.** Cohort calibrated to GA user. Channels designed to surface the kinds of signal the GA decision needs. Validation of the cohort-GA match before the beta starts.
|
||||
|
||||
---
|
||||
|
||||
## Failure 9: Beta participants felt ignored after providing feedback
|
||||
|
||||
**Symptom.** Participants gave feedback. The team did not communicate what was heard or addressed. Participants disengaged.
|
||||
|
||||
**Diagnosis.** Communication discipline missing. Participants commit time and want to know it mattered.
|
||||
|
||||
**Cure.** Re-engage with appreciation and specific acknowledgment. For future participants, tighten the communication discipline.
|
||||
|
||||
**Prevention.** Weekly or bi-weekly updates to participants. Updates reference specific feedback. Participants who give substantive feedback receive direct acknowledgment.
|
||||
|
||||
---
|
||||
|
||||
## Failure 10: We ran a closed beta that was effectively employees only
|
||||
|
||||
**Symptom.** The "external beta" included primarily employees, employees' family members, or very-friendly customers. Not actual representative customers.
|
||||
|
||||
**Diagnosis.** Internal-only beta with external branding. Missed the customer-context complexity.
|
||||
|
||||
**Cure.** Run a true external beta before GA, even if shorter. Apply lessons to future cohort selection.
|
||||
|
||||
**Prevention.** Cohort selection includes "are these actually external customers using the product in real conditions?" Internal-leaning cohorts get flagged in cohort review.
|
||||
|
||||
---
|
||||
|
||||
## Failure 11: Cohort and channels mismatched
|
||||
|
||||
**Symptom.** Small cohort with aggregated channels (no signal extracted from the small volume). Or large cohort with direct channels (overwhelmed synthesis).
|
||||
|
||||
**Diagnosis.** Cohort size and channel design did not align.
|
||||
|
||||
**Cure.** Adjust mid-beta if possible: scale synthesis for large cohorts, deepen direct channels for small ones.
|
||||
|
||||
**Prevention.** Cohort size and channel design decided together. Mismatches caught at planning.
|
||||
|
||||
---
|
||||
|
||||
## Failure 12: Feedback collected but not synthesized
|
||||
|
||||
**Symptom.** Surveys completed; widgets submitted; interviews recorded. The beta ends; the team has not synthesized the feedback into patterns or recommendations.
|
||||
|
||||
**Diagnosis.** Synthesis was treated as optional or postponed. Without synthesis, the feedback never produced decisions.
|
||||
|
||||
**Cure.** Allocate synthesis time post-beta. Apply discovery-research-synthesis discipline (see that skill). Produce the synthesis even if delayed.
|
||||
|
||||
**Prevention.** Plan synthesis as part of the beta timeline. Allocate explicit time and ownership.
|
||||
|
||||
---
|
||||
|
||||
## Failure 13: Wind-down treated participants poorly
|
||||
|
||||
**Symptom.** Participants graduated to GA without clear transition information. Recognition was thin or missing. Future-beta recruitment is harder because alumni are unenthused.
|
||||
|
||||
**Diagnosis.** Wind-down communication missed key elements. Recognition was insufficient for the time invested.
|
||||
|
||||
**Cure.** Reach out individually to participants who feel underrecognized. Adjust future wind-down templates.
|
||||
|
||||
**Prevention.** Wind-down communication template covers all elements (transition, recognition, post-survey, future beta invitation).
|
||||
|
||||
---
|
||||
|
||||
## Failure 14: No postmortem
|
||||
|
||||
**Symptom.** Beta ends; team moves on. Lessons from this beta do not inform future ones. Patterns recur across multiple betas because nobody surfaced them.
|
||||
|
||||
**Diagnosis.** Postmortem was skipped. The beta program does not improve.
|
||||
|
||||
**Cure.** Run a delayed postmortem if feasible. Establish postmortem as a non-negotiable step.
|
||||
|
||||
**Prevention.** Postmortem on the timeline. Owner identified. Lessons documented and applied.
|
||||
|
||||
---
|
||||
|
||||
## Failure 15: Beta scope crept
|
||||
|
||||
**Symptom.** Mid-beta, additional capabilities were added based on participant requests. The beta validated a different feature than the original.
|
||||
|
||||
**Diagnosis.** Scope creep during the beta. Feature requests were absorbed into the live beta.
|
||||
|
||||
**Cure.** Reset the beta if the changes are significant. Capture for post-GA roadmap rather than addressing during the beta.
|
||||
|
||||
**Prevention.** Triage discipline rejects scope-expanding feature requests during the beta. Capture for post-GA; do not add.
|
||||
|
||||
---
|
||||
|
||||
## The cross-cutting pattern
|
||||
|
||||
Most beta failures share a single root: treating beta as ceremony rather than as decision input.
|
||||
|
||||
Ceremony focuses on running a beta because betas are expected: invite participants, collect feedback, ship the GA. The beta is a stage gate, not a learning loop.
|
||||
|
||||
Decision input focuses on what the beta needs to inform: which decisions, what signal will inform them, what cohort and channels will produce that signal. The beta is structured around the decision it serves.
|
||||
|
||||
The fix for almost any beta failure starts with the same question: what specifically did the team need to learn from this beta, and how is the beta structured to produce that learning? When the answers are clear, the beta becomes load-bearing. When the answers are vague, the beta becomes ceremony.
|
||||
|
||||
---
|
||||
|
||||
## Methodology-level choices that stay in the public skill
|
||||
|
||||
The fifteen failure patterns with diagnoses and cures. The cross-cutting ceremony-vs-decision pattern.
|
||||
|
||||
## Implementation choices that stay internal
|
||||
|
||||
Specific failure-pattern detection. Specific reviewer training. Specific intervention patterns. The team's own conventions for catching failures early. These vary by team.
|
||||
+295
@@ -0,0 +1,295 @@
|
||||
# Feedback collection patterns
|
||||
|
||||
Structured surveys, async forms, interviews, in-product widgets, beta-aware support. Channels that work and fail. Channel mix discipline.
|
||||
|
||||
The feedback collection design is what determines whether the beta produces signal or noise. Structured channels capture usable data; ad-hoc venting channels produce volume that does not synthesize.
|
||||
|
||||
---
|
||||
|
||||
## Structured surveys
|
||||
|
||||
Surveys at defined points in the beta.
|
||||
|
||||
**The structure.**
|
||||
|
||||
- 5-15 questions per survey.
|
||||
- Mix of structured questions (Likert scale, multiple choice) and 1-2 open-ended questions.
|
||||
- Tied to specific learning goals: each question has a reason for being there.
|
||||
- Sent at defined points: end of week 1, mid-beta, end of beta.
|
||||
|
||||
**Strong survey questions.**
|
||||
|
||||
- "On a scale of 1-7, how likely are you to use this feature daily?" (closed-ended; quantitative signal)
|
||||
- "What's the most useful thing you've done with this feature so far?" (open-ended; surfaces use cases)
|
||||
- "What was confusing or frustrating in your first week?" (open-ended; surfaces friction)
|
||||
- "Compared to how you did this task before, is this feature better, worse, or about the same?" (specific comparison)
|
||||
|
||||
**Weak survey questions.**
|
||||
|
||||
- "Do you like the feature?" (binary; not actionable)
|
||||
- "What features would you like next?" (out of beta scope; produces wishlist)
|
||||
- "How can we improve?" (too open-ended; produces unfocused responses)
|
||||
|
||||
**Why structured surveys work.**
|
||||
|
||||
- Quantitative signal aggregates. Mid-beta NPS or satisfaction trend lines surface signal.
|
||||
- Open-ended questions tied to specific topics produce focused qualitative data.
|
||||
- Participants understand what is being asked; response rates are higher than for vague open-ended surveys.
|
||||
|
||||
---
|
||||
|
||||
## Async feedback forms
|
||||
|
||||
Forms participants fill when they encounter specific issues.
|
||||
|
||||
**The structure.**
|
||||
|
||||
- Always-available link or in-product entry point.
|
||||
- Form fields prompt for specific information: use case, severity, expected vs actual behavior, screenshots if applicable.
|
||||
- Auto-routes to the team's tracking system (issue tracker, feedback aggregation tool).
|
||||
|
||||
**Strong form fields.**
|
||||
|
||||
- "What were you trying to do?" (use case context)
|
||||
- "What did you expect to happen?" (mental model)
|
||||
- "What actually happened?" (observed behavior)
|
||||
- "How blocking is this?" (severity)
|
||||
- "Steps to reproduce" (when applicable)
|
||||
|
||||
**Why async forms work.**
|
||||
|
||||
- Captures issues at the moment they happen.
|
||||
- Structured fields produce consistent data across submissions.
|
||||
- Synthesis is easier when each submission has the same information shape.
|
||||
|
||||
---
|
||||
|
||||
## Structured interviews
|
||||
|
||||
30-60 minute interviews with a subset of participants.
|
||||
|
||||
**The structure.**
|
||||
|
||||
- 5-15 interviews per beta, depending on cohort size.
|
||||
- Mid-beta or near end of beta.
|
||||
- Discussion guide tied to the team's learning goals.
|
||||
- Recorded with permission; transcribed for synthesis.
|
||||
|
||||
**Strong interview prompts.**
|
||||
|
||||
- "Walk me through the last time you used this feature. What were you trying to do?"
|
||||
- "What was the most useful thing about it? What was the most frustrating?"
|
||||
- "How did you decide to use this instead of [alternative]?"
|
||||
- "Looking back, what do you wish was different?"
|
||||
|
||||
**Why structured interviews work.**
|
||||
|
||||
- Depth that surveys cannot capture.
|
||||
- Specific moments and decisions surface in conversation that participants would not write into surveys.
|
||||
- The qualitative data complements the quantitative survey data.
|
||||
|
||||
**Cross-reference `discovery-research-synthesis`** for the broader interview discipline. Beta interviews are validation-stage; the interviewing methodology is similar.
|
||||
|
||||
---
|
||||
|
||||
## In-product feedback widgets
|
||||
|
||||
Feedback collection contextualized to the moment.
|
||||
|
||||
**The structure.**
|
||||
|
||||
- Trigger: button or prompt within the beta feature.
|
||||
- Captures: what the user was doing (page or context), brief feedback text, optional rating.
|
||||
- Routes to the team's tracking system.
|
||||
|
||||
**Strong in-product widget design.**
|
||||
|
||||
- Triggered after specific moments (completing the feature's primary action, abandoning a flow).
|
||||
- Brief: 1-3 fields max.
|
||||
- Optional severity or sentiment rating.
|
||||
- Captures the page or context automatically.
|
||||
|
||||
**Why in-product widgets work.**
|
||||
|
||||
- Capture friction at the moment, not weeks later.
|
||||
- Context is preserved automatically.
|
||||
- Low friction encourages submissions.
|
||||
|
||||
---
|
||||
|
||||
## Beta-aware support tickets
|
||||
|
||||
Support tickets routed to a beta-aware support team.
|
||||
|
||||
**The structure.**
|
||||
|
||||
- Beta participants flagged in the support system.
|
||||
- Tickets from beta participants get special handling: tagged "beta," routed to support reps trained on the feature, given priority response.
|
||||
- Common beta issues documented for the support team in advance.
|
||||
|
||||
**Strong beta-support practices.**
|
||||
|
||||
- Faster response than standard tickets (the participant is doing the team a favor).
|
||||
- Support reps escalate beta issues to product team where the issue affects beta program decisions.
|
||||
- Patterns across tickets surface to the beta program manager.
|
||||
|
||||
**Why beta-aware support works.**
|
||||
|
||||
- Surfaces issues participants encounter "in the wild," not just the issues they choose to flag through formal channels.
|
||||
- Captures the support burden of the feature, which informs GA support readiness.
|
||||
|
||||
---
|
||||
|
||||
## Channels that fail
|
||||
|
||||
Common feedback channels that produce noise rather than signal.
|
||||
|
||||
**Beta-only Slack channels for venting.**
|
||||
|
||||
- Participants vent in real time.
|
||||
- Mixes critical signal with casual chat.
|
||||
- Nobody synthesizes.
|
||||
- High-engagement participants drown out quieter ones.
|
||||
- Cure: structured channels instead, or use Slack for community building rather than feedback collection.
|
||||
|
||||
**"Reply to this email with feedback."**
|
||||
|
||||
- Returns long unstructured emails.
|
||||
- Synthesis is hard; useful patterns get lost.
|
||||
- Cure: structured forms or surveys.
|
||||
|
||||
**End-of-beta survey only.**
|
||||
|
||||
- Catches only what participants remember at the end.
|
||||
- In-the-moment friction is forgotten.
|
||||
- Cure: surveys at multiple points; in-product widgets for moment-of capture.
|
||||
|
||||
**"Tell us anything."**
|
||||
|
||||
- Unfocused open-ended prompts produce unfocused responses.
|
||||
- Participants do not know what is wanted; many do not respond.
|
||||
- Cure: specific prompts tied to what the team needs to learn.
|
||||
|
||||
---
|
||||
|
||||
## Channel mix discipline
|
||||
|
||||
Most structured betas use 3-5 channels. Each surfaces different signal.
|
||||
|
||||
**Typical channel mix.**
|
||||
|
||||
- 1 structured survey at end of week 1 (quantitative + first-impression qualitative).
|
||||
- 1 structured survey at mid-beta (quantitative trend + behavior signal).
|
||||
- Always-available async feedback form (specific issues as they arise).
|
||||
- 5-10 structured interviews near end of beta (qualitative depth).
|
||||
- In-product feedback widget (in-the-moment friction).
|
||||
- Beta-aware support routing (issues participants choose to escalate).
|
||||
|
||||
**The synthesis.** The team synthesizes across channels. Patterns that appear in multiple channels are stronger; signals from a single channel are weaker.
|
||||
|
||||
**Channel mix calibration.**
|
||||
|
||||
- Smaller cohorts (5-50): more interviews, less aggregation.
|
||||
- Larger cohorts (100-500): more surveys and aggregation, fewer interviews.
|
||||
- Largest cohorts (500+): heavy aggregation, sampling for interviews.
|
||||
|
||||
---
|
||||
|
||||
## Feedback synthesis cadence
|
||||
|
||||
How feedback gets reviewed during the beta.
|
||||
|
||||
**Weekly synthesis.**
|
||||
|
||||
- 1-2 hours weekly during the beta.
|
||||
- Review feedback across all channels for the week.
|
||||
- Categorize: critical bug, friction, feature request, positive signal, edge case.
|
||||
- Surface patterns: what recurring feedback are we seeing?
|
||||
|
||||
**Bi-weekly pattern review.**
|
||||
|
||||
- 1-2 hours bi-weekly.
|
||||
- Look at patterns across the past 2-4 weeks.
|
||||
- Identify converging signal: which patterns are strengthening?
|
||||
- Decide: what to fix during the beta vs what to defer to post-GA roadmap.
|
||||
|
||||
**End-of-beta synthesis.**
|
||||
|
||||
- Substantial work: 1-2 weeks of synthesis depending on cohort size.
|
||||
- Apply discovery-research-synthesis discipline (see that skill).
|
||||
- Output: beta synthesis document with patterns, implications, and graduation recommendation.
|
||||
|
||||
---
|
||||
|
||||
## Feedback signal quality
|
||||
|
||||
Not all feedback is equally valuable.
|
||||
|
||||
**High-signal feedback.**
|
||||
|
||||
- Specific moments of friction with reproducible context.
|
||||
- Patterns across multiple participants.
|
||||
- Behavioral data showing what users actually do (vs what they say).
|
||||
- Comparison to alternatives (what users tried before, why they switched).
|
||||
|
||||
**Lower-signal feedback.**
|
||||
|
||||
- One-off complaints with no pattern.
|
||||
- Hypothetical preferences ("it would be nice if...").
|
||||
- Wishlist features unrelated to the beta scope.
|
||||
- Venting without specific context.
|
||||
|
||||
**The discipline.** Synthesis weights higher-signal feedback. Lower-signal feedback gets noted but does not drive decisions.
|
||||
|
||||
---
|
||||
|
||||
## Feedback volume management
|
||||
|
||||
Managing the flow of feedback as the beta runs.
|
||||
|
||||
**Volume signals.**
|
||||
|
||||
- Critical issues surface fast: most appear in the first 2 weeks.
|
||||
- Friction issues surface continuously through the beta.
|
||||
- Behavioral signal accumulates; visible by mid-beta.
|
||||
|
||||
**Volume management.**
|
||||
|
||||
- The team's synthesis capacity bounds usable volume. Beyond that capacity, additional feedback produces less actionable signal.
|
||||
- For larger cohorts, aggregate channels (surveys, in-product widgets) scale better than direct channels (Slack, email).
|
||||
|
||||
**Burnout risk.**
|
||||
|
||||
- Beta program managers reading 100+ feedback items per week burn out.
|
||||
- Triage is the discipline: not all feedback gets equal attention.
|
||||
- Critical and pattern feedback gets full attention; one-off venting gets noted briefly.
|
||||
|
||||
---
|
||||
|
||||
## Common feedback collection failures
|
||||
|
||||
**Single-channel reliance.** Only one feedback channel; misses signal that other channels would have caught.
|
||||
|
||||
**Channels not tied to learning goals.** Feedback collected without clear purpose; synthesis cannot tell what to do with it.
|
||||
|
||||
**Noisy channels (Slack venting).** High volume, low signal-to-noise ratio.
|
||||
|
||||
**End-of-beta only.** Misses in-the-moment friction; relies on participant memory.
|
||||
|
||||
**Vague prompts.** Open-ended questions without focus; produces unfocused responses.
|
||||
|
||||
**No mid-beta synthesis.** Feedback collected but not reviewed until end; opportunities to address issues during the beta missed.
|
||||
|
||||
**Feedback channels that conflict.** Multiple Slack channels for the same purpose; participants confused about where to post.
|
||||
|
||||
**No closing the loop.** Participants give feedback; team never tells them what was heard or changed; engagement decays.
|
||||
|
||||
---
|
||||
|
||||
## Methodology-level choices that stay in the public skill
|
||||
|
||||
Channels that work (structured surveys, async forms, interviews, in-product widgets, beta-aware support). Channels that fail. Channel mix discipline. Feedback synthesis cadence. Signal quality discipline. Volume management. Common failures.
|
||||
|
||||
## Implementation choices that stay internal
|
||||
|
||||
Specific survey tools and templates. Specific feedback form integrations. Specific in-product widget implementations. Specific support ticketing systems. The team's own conventions for channel selection. These vary by team and tooling.
|
||||
+216
@@ -0,0 +1,216 @@
|
||||
# Mid-beta triage and iteration
|
||||
|
||||
Triage cadence. Iteration discipline (what to fix during the beta, what to defer). Communication with participants.
|
||||
|
||||
Betas where the team responds to feedback during the beta produce stronger signal than betas where the team waits for the end. Mid-beta triage turns a static validation into an iterative one.
|
||||
|
||||
---
|
||||
|
||||
## The triage cadence
|
||||
|
||||
How the team reviews feedback during the beta.
|
||||
|
||||
**Weekly triage (1-2 hours).**
|
||||
|
||||
- Review feedback across all channels for the week.
|
||||
- Categorize each piece: critical bug, friction issue, feature request, positive signal, edge case.
|
||||
- Tag for action: fix this week, fix later in the beta, defer to post-GA, no action needed (one-off).
|
||||
- Identify any critical issues warranting immediate response.
|
||||
|
||||
**Bi-weekly pattern review (1-2 hours).**
|
||||
|
||||
- Look at patterns across the past 2-4 weeks.
|
||||
- Identify converging signal: which patterns are strengthening, which are not surfacing in volume?
|
||||
- Surface decisions: what to address in the remaining beta period.
|
||||
|
||||
**As-needed escalation.**
|
||||
|
||||
- Critical issues (data loss, security, broken core flows) get same-day response regardless of cadence.
|
||||
- The triage cadence does not delay critical-issue response.
|
||||
|
||||
---
|
||||
|
||||
## Categorization
|
||||
|
||||
Each piece of feedback gets categorized.
|
||||
|
||||
**Categories.**
|
||||
|
||||
- **Critical bug.** Crashes, data loss, broken core flows, security issues. Must be fixed before GA.
|
||||
- **Friction issue.** Workflows that are confusing, slow, or sub-optimal but functional. Fix during beta where feasible; document otherwise.
|
||||
- **Feature request.** Capability the participant wants that is outside beta scope. Capture for post-GA roadmap; do not add during beta.
|
||||
- **Positive signal.** What is working well; what users find valuable. Surfaces what to preserve in GA and what to highlight in marketing.
|
||||
- **Edge case.** Unusual configurations or contexts. Note for post-GA monitoring; address only if affecting many participants.
|
||||
- **One-off.** Single observation without pattern. Note briefly; do not action.
|
||||
|
||||
**Why categorization matters.**
|
||||
|
||||
- Different categories have different action paths. Treating all feedback the same overwhelms triage.
|
||||
- The categorization is the basis for the iteration decisions.
|
||||
|
||||
---
|
||||
|
||||
## What to fix during the beta
|
||||
|
||||
The team should fix some things during the beta and defer others.
|
||||
|
||||
**Fix during the beta.**
|
||||
|
||||
- Critical bugs that prevent participants from using the feature. The beta cannot validate the feature if participants cannot use it.
|
||||
- Friction issues that are clearly addressable and significantly affect participant experience. Fixing them produces stronger end-of-beta signal.
|
||||
- Issues that, if unfixed, will surface again post-GA at higher cost.
|
||||
- Issues that participants are about to escalate publicly (if NDA-relevant) or that damage trust if left.
|
||||
|
||||
**Defer to post-GA.**
|
||||
|
||||
- Feature requests outside beta scope.
|
||||
- Friction issues that affect a small subset of users in ways the team can document.
|
||||
- Polish work that does not block the GA decision.
|
||||
- Edge cases that do not affect mainline usage.
|
||||
|
||||
**The "what changes the GA decision" test.** If fixing this issue affects whether the team can ship to GA, fix it. If it does not affect the GA decision, capture it for post-GA roadmap.
|
||||
|
||||
---
|
||||
|
||||
## The iteration discipline
|
||||
|
||||
Mid-beta iteration adds value but has constraints.
|
||||
|
||||
**The discipline.**
|
||||
|
||||
- Iterate on the feature, not the beta scope. Adding features to the beta mid-way confuses participants and dilutes signal.
|
||||
- Fix critical and high-impact friction; capture rather than fix lower-impact issues.
|
||||
- Communicate iteration to participants: when they see a fix or change, they know it came from their feedback.
|
||||
|
||||
**The "do not redesign mid-beta" rule.**
|
||||
|
||||
- Significant feature changes mid-beta produce two betas: the pre-change beta and the post-change beta. Neither is fully validated.
|
||||
- If significant changes are needed, end the current beta, redesign, and start a new beta. Do not blend them.
|
||||
|
||||
**The "no creep" discipline.**
|
||||
|
||||
- Mid-beta is not the time to add capabilities outside the beta's original scope.
|
||||
- Feature requests get captured for post-GA, not added to the beta.
|
||||
- The beta's signal depends on consistency; scope creep undermines the validation.
|
||||
|
||||
---
|
||||
|
||||
## Communication with participants
|
||||
|
||||
Mid-beta communication keeps participants engaged.
|
||||
|
||||
**The cadence.**
|
||||
|
||||
- Weekly or bi-weekly updates to participants.
|
||||
- Format: short email or in-product notification.
|
||||
- Content: what was heard, what is being addressed, what is being deferred, what to expect next week.
|
||||
|
||||
**Strong update content.**
|
||||
|
||||
- "We heard your feedback about the configuration friction in step 3. We pushed a fix this week; please let us know if it is improved."
|
||||
- "Several of you reported the dashboard load time is slow at scale. We are investigating; we expect a fix in the next 1-2 weeks."
|
||||
- "We are seeing strong positive signal on the new export functionality. We will expand the format options in the next iteration."
|
||||
- "Several of you requested integrations beyond the beta scope. We have captured these for post-GA roadmap."
|
||||
|
||||
**Why communication matters.**
|
||||
|
||||
- Participants who see their feedback acted on engage more substantively.
|
||||
- Participants who feel ignored decay.
|
||||
- Communication signals to participants that the team is listening.
|
||||
|
||||
**Common communication failures.**
|
||||
|
||||
- Silence between welcome and end of beta. Participants feel ignored.
|
||||
- Generic updates that do not reference specific feedback. Feels performative.
|
||||
- Over-communication. Daily updates are too much; participants tune out.
|
||||
- Updates that promise more than the team will deliver. Erodes trust when promises are not kept.
|
||||
|
||||
---
|
||||
|
||||
## The mid-beta health check
|
||||
|
||||
A specific mid-beta milestone.
|
||||
|
||||
**The milestone.** Roughly the midpoint of the beta. The team takes stock of where the beta is.
|
||||
|
||||
**The questions.**
|
||||
|
||||
- Is the feedback volume what was expected? If not, what is causing the difference?
|
||||
- Are critical issues surfacing or has the team caught them all in the first part of the beta?
|
||||
- Are behavioral patterns emerging? What do they suggest for the GA experience?
|
||||
- Are participants engaged? Are some segments dropping off?
|
||||
- Is the trajectory toward graduation criteria? Where are gaps?
|
||||
|
||||
**The output.**
|
||||
|
||||
- Adjustments to the beta operations: more triage, more communication, additional cohort recruitment if needed.
|
||||
- Surfaced concerns about graduation: are the criteria reachable in the remaining beta time?
|
||||
- Surfaced wins: what is going well that the team can build on for GA.
|
||||
|
||||
---
|
||||
|
||||
## Mid-beta participant churn
|
||||
|
||||
Some participants will drop off during the beta.
|
||||
|
||||
**Why participants churn.**
|
||||
|
||||
- The feature did not match their use case (they expected something different).
|
||||
- They lost interest or got busy.
|
||||
- They hit critical friction early and gave up.
|
||||
- They felt ignored after providing feedback.
|
||||
|
||||
**The response.**
|
||||
|
||||
- Investigate churn. A subset of churn is normal; high churn is signal.
|
||||
- For participants who churned because of friction: address the friction; possibly re-engage them.
|
||||
- For participants who churned because of misfit: the cohort may have been miscalibrated; learn for future betas.
|
||||
- For participants who felt ignored: tighten the communication discipline; thank them for prior feedback even if they have stopped engaging.
|
||||
|
||||
**Replacement recruitment.**
|
||||
|
||||
- For betas that need a specific cohort size for signal, replace churned participants if possible.
|
||||
- Late-recruited replacements have less time in the beta; their feedback covers less of the beta period.
|
||||
- Sometimes accepting churn and a smaller-than-planned cohort is the right call.
|
||||
|
||||
---
|
||||
|
||||
## Triage anti-patterns
|
||||
|
||||
Common ways triage decays.
|
||||
|
||||
**Triage skipping.** No formal triage cadence; feedback accumulates without categorization or action.
|
||||
|
||||
**Triage as logging.** Feedback gets categorized but never actioned. The categorization is documentation theater.
|
||||
|
||||
**Triage by loudest voice.** Loudest participants get attention; quieter ones with similar feedback do not. Skews the synthesis.
|
||||
|
||||
**Triage by easiness.** Easy fixes get prioritized regardless of impact. Important harder fixes get deferred indefinitely.
|
||||
|
||||
**Triage without communication.** Internal triage happens but participants are not told. They feel ignored.
|
||||
|
||||
**Triage that absorbs feature requests.** Participants request features outside scope; the team adds them mid-beta; scope creeps; signal dilutes.
|
||||
|
||||
---
|
||||
|
||||
## Common iteration failures
|
||||
|
||||
**No iteration during the beta.** Feedback is collected; the team waits for end of beta; opportunities to address issues during the beta are missed.
|
||||
|
||||
**Excessive iteration.** Significant feature changes mid-beta. The beta becomes two different betas; neither validates the GA experience cleanly.
|
||||
|
||||
**Iteration without communication.** The team fixes issues; participants do not know; engagement decays.
|
||||
|
||||
**Iteration on participant requests outside scope.** Scope creep; the beta validates a different feature than the original.
|
||||
|
||||
**No closing the loop.** Iterations happen; participants are not told their feedback drove the change; the connection between feedback and improvement is invisible.
|
||||
|
||||
---
|
||||
|
||||
## Methodology-level choices that stay in the public skill
|
||||
|
||||
The triage cadence. The categorization scheme. What to fix during the beta vs defer. The iteration discipline. The "do not redesign mid-beta" rule. Communication with participants. The mid-beta health check. Mid-beta churn handling. Common failures.
|
||||
|
||||
## Implementation choices that stay internal
|
||||
|
||||
Specific triage tools and trackers. Specific communication templates. Specific health-check formats. The team's own conventions for what counts as critical vs friction. These vary by team and tooling.
|
||||
Vendored
+212
@@ -0,0 +1,212 @@
|
||||
# Participant selection criteria
|
||||
|
||||
Criteria that produce calibrated cohorts. Common selection failures. The cohort size question.
|
||||
|
||||
Participant selection determines what the beta can produce. Calibrated cohorts produce decision-grade signal; misaligned cohorts produce noise that does not represent the GA user. Selection is upstream of every other beta decision.
|
||||
|
||||
---
|
||||
|
||||
## Criteria that produce calibrated cohorts
|
||||
|
||||
**Match the post-launch user profile.** If the feature is for enterprise admins, beta participants should be enterprise admins, not curious individual users.
|
||||
|
||||
- Worked example: a feature for product managers at growth-stage SaaS companies. Beta participants should be PMs at growth-stage SaaS companies. Not designers, engineers, or PMs at very-early or very-late stage companies.
|
||||
- The matching dimensions depend on the feature: role, company size, industry, usage volume, tenure, technical sophistication.
|
||||
|
||||
**Variety across relevant dimensions.** Not all participants identical.
|
||||
|
||||
- If the feature has segment-specific behavior, the cohort spans segments.
|
||||
- If usage volume varies, the cohort includes high-volume and low-volume users.
|
||||
- If geography matters (compliance, latency, language), the cohort spans relevant geographies.
|
||||
- The variety should match the GA user diversity.
|
||||
|
||||
**Feedback willingness.** Participants who agree to provide feedback through structured channels.
|
||||
|
||||
- Soft commitment ("I will give feedback when I have time") is weaker than explicit commitment ("I will respond to weekly check-ins and complete the structured survey").
|
||||
- Recruiting should make the feedback expectation explicit. Participants who agree are more likely to engage; participants who decline are honest about their availability.
|
||||
|
||||
**Existing relationship strength.** Customers with strong existing relationships are more likely to engage substantively.
|
||||
|
||||
- Champion users, design partners, customers with active customer success relationships engage more.
|
||||
- Customers in churn-risk are less likely to engage; their feedback may also be less representative (the relationship is already strained).
|
||||
|
||||
**Real usage of the broader product.** Beta participants who use the broader product actively can give grounded feedback. Participants who signed up only for the beta and do not use the product otherwise often give surface-level feedback.
|
||||
|
||||
---
|
||||
|
||||
## Criteria that produce miscalibrated cohorts
|
||||
|
||||
**Self-selection only.** Open beta sign-ups skew toward enthusiasts and tinkerers.
|
||||
|
||||
- Skews toward users who try every new feature; their feedback may not represent the broader target user.
|
||||
- Misses users who would adopt at GA but who do not seek out beta sign-ups.
|
||||
|
||||
**Highest-paying customers only.** Skews toward enterprise patterns.
|
||||
|
||||
- Misses smaller-team and individual use cases.
|
||||
- Enterprise feedback may emphasize features that smaller customers do not need.
|
||||
|
||||
**Internal employees only.** Misses customer-context complexity.
|
||||
|
||||
- Employees experience features differently than customers (familiarity, infrastructure, motivations).
|
||||
- Internal-only validation produces "we tested" without "real customers tested."
|
||||
|
||||
**Whoever happens to be available.** No selection criteria; the cohort is whoever the team can recruit quickly.
|
||||
|
||||
- The cohort may not match the GA user; signal does not transfer to the GA decision.
|
||||
|
||||
**Champion users only.** All beta participants are existing strong advocates.
|
||||
|
||||
- Enthusiastic feedback may overstate readiness; missing the friction non-champion users would hit.
|
||||
|
||||
---
|
||||
|
||||
## Variety calibration
|
||||
|
||||
How to ensure the cohort spans the relevant dimensions.
|
||||
|
||||
**The dimension audit.**
|
||||
|
||||
- For the feature being beta'd, identify the dimensions that affect user experience.
|
||||
- Common dimensions: role, company size, industry vertical, usage volume, geographic region, technical sophistication, tenure with the product.
|
||||
- Decide which dimensions matter most for this feature.
|
||||
|
||||
**Cohort composition.**
|
||||
|
||||
- For each high-priority dimension, ensure the cohort includes representation across the values.
|
||||
- If role matters: cohort includes participants in each relevant role.
|
||||
- If usage volume matters: cohort includes high-volume, mid-volume, low-volume users.
|
||||
- If industry varies meaningfully: cohort spans industries.
|
||||
|
||||
**Worked example.** A feature for product managers using analytics tools.
|
||||
|
||||
- Role dimension: cohort is all PMs (no other roles).
|
||||
- Usage dimension: high-volume PMs (active daily users) + mid-volume PMs (weekly users). Skip low-volume because they likely will not use the feature meaningfully.
|
||||
- Company size dimension: 10-50 employee, 50-200 employee, 200-500 employee. Skip enterprise (different feature priorities).
|
||||
- Tenure dimension: PMs who have used the product 3+ months (so they have established workflows the new feature will integrate into). Skip new users.
|
||||
|
||||
The cohort composition is intentional; each participant fits multiple criteria.
|
||||
|
||||
---
|
||||
|
||||
## The cohort size question
|
||||
|
||||
How many participants are enough.
|
||||
|
||||
**The calibration is signal-need-driven.**
|
||||
|
||||
- Bug discovery saturates fast: 20-30 participants surface most critical issues in 2-4 weeks.
|
||||
- Behavioral signal saturates slower: 50-100 participants needed to see usage patterns clearly.
|
||||
- Edge case discovery: 100-500+ participants needed; some edge cases never surface in beta.
|
||||
|
||||
**Common cohort sizes by beta type.**
|
||||
|
||||
- Design partner program: 3-10 participants.
|
||||
- Closed alpha: 10-30 participants.
|
||||
- Closed beta: 50-200 participants.
|
||||
- Open beta: 500-5,000+ participants.
|
||||
- RC validation: 1,000-10,000+ participants.
|
||||
|
||||
**The "more is better" anti-pattern.** Teams default to large cohorts thinking volume produces signal. In practice, larger-than-needed cohorts produce volume without proportional signal increase, while making feedback synthesis harder.
|
||||
|
||||
**The "smaller produces calibrated" principle.** A 50-person calibrated cohort often produces stronger signal than a 5,000-person uncalibrated one. Pick the smallest cohort that produces the signal needed.
|
||||
|
||||
---
|
||||
|
||||
## The recruitment process
|
||||
|
||||
How participants get selected.
|
||||
|
||||
**Sources.**
|
||||
|
||||
- Existing customer base: customer success identifies candidates matching the criteria.
|
||||
- Sales pipeline: late-stage prospects who could become customers and provide feedback.
|
||||
- Past beta participants: customers who participated in prior betas and proved engaged.
|
||||
- Public sign-up forms (for open betas): with screening criteria applied to actual selection.
|
||||
- Partner referrals: customers who recommend other customers fitting the profile.
|
||||
|
||||
**The screening.**
|
||||
|
||||
- Define the criteria explicitly (role, dimension values, feedback willingness).
|
||||
- Apply the screening to candidates: who fits the criteria?
|
||||
- For closed betas, decide which subset of fitting candidates to invite (cohort sizing).
|
||||
- For open betas with screening, the sign-up form captures qualifying information; the team selects from sign-ups.
|
||||
|
||||
**The invitation.**
|
||||
|
||||
- Personalized invitations engage better than mass invitations.
|
||||
- The invitation explains: what the beta is, what is expected, what participants get, how long it runs.
|
||||
- Acceptance is opt-in; participants who decline are honest.
|
||||
|
||||
**The capacity.**
|
||||
|
||||
- Recruiting takes real time. A 50-participant closed beta may take 2-4 weeks of recruiting work depending on customer base and selection criteria.
|
||||
- Plan recruiting time as part of the beta timeline.
|
||||
|
||||
---
|
||||
|
||||
## The diversity-vs-control tradeoff
|
||||
|
||||
Calibrated cohorts can over-control diversity in ways that miss valuable signal.
|
||||
|
||||
**The tradeoff.**
|
||||
|
||||
- Tightly-defined selection criteria produce a cohort that is uniform along the criteria. Reduces variety; may miss signal from users who differ.
|
||||
- Loosely-defined criteria produce more diverse cohorts but make the cohort less calibrated to the GA user.
|
||||
|
||||
**The middle path.**
|
||||
|
||||
- Define the must-have criteria (role, key segment markers).
|
||||
- Allow variety in the optional dimensions (industry, geography, tenure).
|
||||
- The cohort is calibrated on what matters and varied on what does not.
|
||||
|
||||
---
|
||||
|
||||
## When recruitment fails
|
||||
|
||||
What to do when selection criteria cannot be met.
|
||||
|
||||
**Insufficient candidates fitting criteria.**
|
||||
|
||||
- Reconsider whether the criteria are too narrow.
|
||||
- Extend recruiting time if feasible.
|
||||
- Accept a smaller cohort that fully fits the criteria, rather than a larger cohort that includes mismatches.
|
||||
|
||||
**Candidates fitting criteria decline to participate.**
|
||||
|
||||
- Investigate why. Is the beta commitment too heavy? The compensation insufficient? The timing wrong?
|
||||
- Adjust the offer; re-invite.
|
||||
- If still insufficient, consider whether the beta plan is realistic given customer engagement willingness.
|
||||
|
||||
**Cohort skew despite intentional selection.**
|
||||
|
||||
- Some dimensions skew despite efforts (e.g., one industry over-represented because that industry is more receptive).
|
||||
- Acknowledge the skew explicitly in synthesis. Patterns from the over-represented dimension may not generalize.
|
||||
|
||||
---
|
||||
|
||||
## Common selection failures
|
||||
|
||||
**No criteria.** Whoever happens to be available joins. Cohort does not represent GA user.
|
||||
|
||||
**Self-selection only.** Open sign-ups skew the cohort.
|
||||
|
||||
**Only champions.** Cohort over-represents enthusiasts; misses friction non-champions hit.
|
||||
|
||||
**Internal employees only.** Misses customer-context complexity.
|
||||
|
||||
**Single-dimension calibration.** Cohort uniform on one dimension (role) but mismatched on others (usage, segment).
|
||||
|
||||
**Recruiting too late.** Beta starts before the cohort is calibrated; recruitment continues mid-beta; signal is muddled.
|
||||
|
||||
**Enterprise-only.** Cohort over-represents large customers; misses smaller use cases.
|
||||
|
||||
---
|
||||
|
||||
## Methodology-level choices that stay in the public skill
|
||||
|
||||
The criteria for calibrated cohorts. The criteria for miscalibrated cohorts. Variety calibration with worked example. The cohort size question. The recruitment process. The diversity-vs-control tradeoff. When recruitment fails. Common selection failures.
|
||||
|
||||
## Implementation choices that stay internal
|
||||
|
||||
Specific recruiting tools and CRM integration. Specific screening surveys. Specific outreach templates. Specific tracking of cohort composition. The team's own conventions for selection criteria within different beta types. These vary by team and customer base.
|
||||
@@ -0,0 +1,143 @@
|
||||
---
|
||||
name: brand-archetype-system
|
||||
description: "Apply pre-composed aesthetic archetype defaults to jumpstart brand design work covering color, typography, layout, voice, and imagery direction. Use this skill whenever the user wants a starting point for brand visual and verbal direction, references a brand they want to design near (for example 'something like Stripe' or 'editorial like Linear'), needs to converge faster from many directions to one, or wants known-good defaults for a specific industry vertical. Triggers on archetype, design archetype, brand archetype, near to (brand), in the style of, similar aesthetic, design starting point, brand template, vertical-typical, industry-typical. Also triggers when the user has a brief and wants to map it to a known aesthetic family rather than design from first principles."
|
||||
category: brand
|
||||
catalog_summary: "12 archetype defaults across 18 verticals: color, type, voice, imagery starters"
|
||||
display_order: 5
|
||||
---
|
||||
|
||||
# Brand Archetype System
|
||||
|
||||
Pre-composed aesthetic archetype defaults that jumpstart brand design work. Each archetype bundles color tendencies, type pairings, layout patterns, voice samples, and imagery direction for a recognizable aesthetic family. Stack-agnostic. Tool-agnostic.
|
||||
|
||||
This is a starting-point library, not a methodology library. The agent applies archetype defaults to a specific brief; the archetypes themselves provide anchor points, not endpoints.
|
||||
|
||||
---
|
||||
|
||||
## When to use
|
||||
|
||||
- The user wants a starting point rather than designing from first principles
|
||||
- The user references a brand or aesthetic family they want to design near
|
||||
- Need to converge faster from many directions to one
|
||||
- The user wants vertical-typical defaults (for example fintech consumer, B2B developer tools)
|
||||
- The user wants to test what a brief would look like in a different archetype
|
||||
|
||||
## When NOT to use
|
||||
|
||||
- The user wants pure methodology guidance (use `brand-identity`)
|
||||
- The user is in early ideation needing positioning territories (use `brand-ideation`)
|
||||
- Defining voice for an existing brand (use `brand-voice`)
|
||||
- Documenting a finished brand (use `brand-style-guide`)
|
||||
|
||||
---
|
||||
|
||||
## How this composes with other skills
|
||||
|
||||
This skill works upstream of `brand-identity` (provides starting defaults that brand-identity refines into a finished system) and parallel to `creative-direction` (archetypes can be located by position on the 4 creative-direction axes).
|
||||
|
||||
Typical flow when this skill is invoked:
|
||||
1. User provides a brief or references a target archetype
|
||||
2. Agent picks the most relevant core archetype, or composes from 2 adjacent archetypes
|
||||
3. Agent adapts the archetype's defaults to the brief (color tokens shift, type swaps to vertical-appropriate fonts, voice samples rewrite for the brand)
|
||||
4. Agent flags adaptation choices made
|
||||
|
||||
Direct verbatim copying of an archetype's default palette into a new brand is a failure mode. Archetypes constrain the design space; the brief specifies the point within that space.
|
||||
|
||||
---
|
||||
|
||||
## The framework: 12 core archetypes plus 18 vertical applications
|
||||
|
||||
Two layers of content in `references/`:
|
||||
|
||||
### Core archetypes (12 files)
|
||||
|
||||
Located in `references/core-archetypes/`. Each is an aesthetic family with:
|
||||
- Aesthetic summary
|
||||
- Position on the 4 `creative-direction` axes
|
||||
- Color palette starter (4 to 6 hex values with token names and rationale)
|
||||
- Type pairing starter (Google Fonts pairing with size scale)
|
||||
- Layout and composition patterns
|
||||
- Voice samples (5 to 10 representative lines)
|
||||
- Component pattern descriptions (heroes, buttons, cards, tables)
|
||||
- Imagery direction
|
||||
- When to pick and when to avoid
|
||||
- Adaptation guidance
|
||||
- Exemplar brands with attribution language
|
||||
|
||||
### Vertical applications (18 files)
|
||||
|
||||
Located in `references/by-vertical/`. Each maps named brands to core archetypes in that vertical with:
|
||||
- Vertical summary
|
||||
- Common archetypes
|
||||
- Brand-to-archetype mapping (5 to 10 brands per vertical)
|
||||
- Vertical-specific adaptation notes
|
||||
- Common archetype evolution patterns as brands mature
|
||||
|
||||
### Two overview files
|
||||
|
||||
- `00-archetype-system-overview.md`: how the system works, the taxonomy
|
||||
- `01-how-to-apply-an-archetype.md`: the adaptation discipline, the failure modes
|
||||
|
||||
---
|
||||
|
||||
## The 12 core archetypes
|
||||
|
||||
| # | Archetype | Single-line summary |
|
||||
|---|---|---|
|
||||
| 01 | Editorial Restrained | Low-saturation, type-led, generous whitespace, considered |
|
||||
| 02 | Technical Precise | Monospace and grid prominent, data-dense, system-feeling |
|
||||
| 03 | Warm Conversational | Human imagery, mid-saturation, friendly type, approachable |
|
||||
| 04 | Bold Confident | High-contrast, large display type, saturated, direct |
|
||||
| 05 | Playful Energetic | Bright colors, illustration-led, dynamic, character-driven |
|
||||
| 06 | Luxe Considered | Serif-led, generous spacing, restrained palette, premium |
|
||||
| 07 | Clinical Trustworthy | Cool palette, sans-serif, clean medical or financial register |
|
||||
| 08 | Rugged Utilitarian | Earth tones, workwear influence, no-nonsense type |
|
||||
| 09 | Retro Nostalgic | Period-specific palette and type, intentional vintage reference |
|
||||
| 10 | Minimal Essentialist | Black, white, single accent, sans-serif only, sparse |
|
||||
| 11 | Vibrant Saturated | High-saturation across full palette, color as character |
|
||||
| 12 | Documentary Honest | Photography-led, real people, low-touched imagery |
|
||||
|
||||
## The 18 vertical applications
|
||||
|
||||
- B2B SaaS: Developer Tools, Business Productivity, Marketing and Sales, Data and Analytics
|
||||
- Fintech: Consumer, Enterprise
|
||||
- DTC: Fashion, Beauty, Home and Lifestyle, Food and Beverage
|
||||
- Consumer Health and Wellness
|
||||
- Hospitality and Travel
|
||||
- Media and Publishing
|
||||
- EdTech
|
||||
- Gaming and Entertainment
|
||||
- Marketplace
|
||||
- Crypto and Web3
|
||||
- Real Estate and Proptech
|
||||
|
||||
---
|
||||
|
||||
## Trademark and attribution
|
||||
|
||||
Archetypes are NAMED for aesthetic families, NOT for brands. "Editorial Restrained" not "Stripe-like." Brands are referenced as exemplars in description text using attribution language: "exemplified by [brands]", "common among [brands]", "characteristic of [brands]".
|
||||
|
||||
This is descriptive and nominative fair use territory, durable across brand redesigns. A brand that pivots its identity does not invalidate the archetype it once exemplified.
|
||||
|
||||
---
|
||||
|
||||
## The four creative-direction axes (reference)
|
||||
|
||||
Each archetype positions on the 4 axes defined in the `creative-direction` skill. Brief summary for cross-reference:
|
||||
|
||||
- **Tone register**: Professional, Conversational, Playful
|
||||
- **Aesthetic register**: Restrained, Considered, Expressive, Maximal
|
||||
- **Audience relationship**: Authority, Peer, Companion, Performer
|
||||
- **Sensory ambition**: Functional, Considered, Immersive, Theatrical
|
||||
|
||||
Each core archetype file specifies its position on each axis.
|
||||
|
||||
---
|
||||
|
||||
## Reference files
|
||||
|
||||
- [`references/00-archetype-system-overview.md`](references/00-archetype-system-overview.md) - How the two-layer system fits together, entry patterns, when archetypes compose, and the recurring failure modes.
|
||||
- [`references/01-how-to-apply-an-archetype.md`](references/01-how-to-apply-an-archetype.md) - The 5-step adaptation process: locate the design space, map the brief to adjustable dimensions, adapt color, adapt type, write voice samples. Includes the cross-archetype coherence check.
|
||||
|
||||
The 12 core archetype files live in the `core-archetypes/` subdirectory under references, numbered 01 (Editorial Restrained) through 12 (Documentary Honest). The 18 vertical application files live in the `by-vertical/` subdirectory under references, numbered 01 (B2B SaaS Developer Tools) through 18 (Real Estate and Proptech). Load the relevant core archetype file plus the relevant vertical file together for any brief that names both an aesthetic family and an industry.
|
||||
|
||||
+40
@@ -0,0 +1,40 @@
|
||||
# Archetype system overview
|
||||
|
||||
This document explains the taxonomy and how the layers fit together. Read this first when working with the archetype system for the first time.
|
||||
|
||||
## The two layers
|
||||
|
||||
**Core archetypes** (12 files) are the aesthetic families themselves. They span verticals; an archetype like Editorial Restrained appears in B2B SaaS, in media publishing, in DTC fashion. The core archetype files describe the family in pure form: what makes it recognizable, the color tendencies, the type pairings, the voice character.
|
||||
|
||||
**Vertical applications** (18 files) describe how the archetypes manifest in specific industries with named brands. They are discovery surfaces: a user working on a fintech brand should be able to find their vertical, see which archetypes are common, see specific brand-to-archetype mappings, and decide which core archetype to start from.
|
||||
|
||||
## How the agent should use the system
|
||||
|
||||
Two entry patterns:
|
||||
|
||||
**Entry by archetype** (user references an aesthetic family): "I want something Editorial Restrained for my analytics product." Agent loads the Editorial Restrained core archetype file, plus the B2B SaaS Data and Analytics vertical file for context. Composes defaults adapted to the brief.
|
||||
|
||||
**Entry by vertical** (user references their industry): "I'm designing a consumer fintech app, what archetypes work here?" Agent loads the Fintech Consumer vertical file first, sees the brand-to-archetype mappings, picks the most relevant core archetype, then loads that for full defaults.
|
||||
|
||||
## What this system is and is not
|
||||
|
||||
**It is**: a library of pre-composed defaults that accelerate brand work by providing known-good starting points with documented rationale.
|
||||
|
||||
**It is not**: a substitute for design judgment. The defaults are anchor points; the brief specifies where to land within the archetype's design space.
|
||||
|
||||
**It is not**: a comprehensive theory of brand aesthetics. The 12 archetypes capture the most recognizable contemporary Western brand aesthetics. They are not exhaustive. Regional, cultural, and historical archetypes are deferred to future expansions of the catalog.
|
||||
|
||||
## When archetypes compose
|
||||
|
||||
Two archetypes can blend. Linear is Editorial Restrained with Technical Precise undertones. Stripe is Technical Precise with Editorial Restrained surfaces. Glossier is Vibrant Saturated with Minimal Essentialist composition.
|
||||
|
||||
When the brief calls for blending, the agent picks two core archetypes and notes which contributes which dimension (for example "Editorial Restrained for type and whitespace, Technical Precise for color and density").
|
||||
|
||||
## The failure modes
|
||||
|
||||
1. **Verbatim copying**: pulling the exact starter palette into a new brand without adaptation. Produces generic output.
|
||||
2. **Archetype mismatch with audience**: picking an archetype because the user likes its exemplars rather than because it fits the audience.
|
||||
3. **Cross-archetype tokens**: pulling a color from one archetype and type from another without considering coherence. Often produces incoherent output.
|
||||
4. **Stale exemplars**: assuming a brand still exemplifies an archetype after a redesign. The archetype is durable; the brand is not.
|
||||
|
||||
Each core archetype file's "Adaptation guidance" section addresses these.
|
||||
+69
@@ -0,0 +1,69 @@
|
||||
# How to apply an archetype
|
||||
|
||||
This document is the operating manual. Once an archetype is picked, follow this process to adapt it to the specific brief.
|
||||
|
||||
## The 5-step adaptation process
|
||||
|
||||
### Step 1: Locate the archetype's design space
|
||||
|
||||
Read the core archetype file. Understand:
|
||||
- Position on the 4 creative-direction axes
|
||||
- The non-negotiable structural choices (for example "single accent" for Editorial Restrained, "monospace prominent" for Technical Precise)
|
||||
- The adjustable dimensions (specific hue of the accent, specific serif, specific density)
|
||||
|
||||
The structural choices are what make the archetype recognizable. The adjustable dimensions are where the brief lands.
|
||||
|
||||
### Step 2: Map the brief to adjustable dimensions
|
||||
|
||||
For each adjustable dimension, ask: what does the brief specify or imply?
|
||||
|
||||
- **Audience character**: Younger audience usually wants warmer accent; older wants cooler. Technical audience tolerates more density; consumer audience needs more whitespace.
|
||||
- **Category context**: Crowded categories need stronger contrast; quiet categories can be more restrained.
|
||||
- **Emotional direction**: Trust-needing brands lean cooler; warmth-needing brands lean warmer.
|
||||
- **Competitive position**: If the closest competitor is in the same archetype, shift one adjustable dimension hard to differentiate.
|
||||
|
||||
### Step 3: Adapt the color palette
|
||||
|
||||
The starter palette is a relationship between values, not absolute hex codes. Preserve the relationship; shift the values.
|
||||
|
||||
Example with Editorial Restrained:
|
||||
- Default: ink #0F1B2D (navy), accent #5B8B85 (muted teal)
|
||||
- Adaptation for a finance brief: ink #1A1F2E (deeper navy), accent #4A5D6E (slate blue), reads more institutional
|
||||
- Adaptation for a consumer wellness brief: ink #2A2520 (warm dark brown), accent #7A9B7C (sage green), reads more grounded and warm
|
||||
|
||||
Preserve: low saturation, single accent, paper-not-white background, ink-not-black text. Shift: specific hues to match emotional direction.
|
||||
|
||||
### Step 4: Adapt the type pairing
|
||||
|
||||
The starter pairing is a relationship between display and body, not specific fonts. Preserve the relationship; shift the fonts.
|
||||
|
||||
Example with Editorial Restrained:
|
||||
- Default: IBM Plex Serif (display) plus Inter (body)
|
||||
- Adaptation for luxe-leaning brief: Tiempos Display (display) plus Inter (body) preserves the pairing, shifts the serif character
|
||||
- Adaptation for technical-leaning brief: IBM Plex Serif (display) plus IBM Plex Sans (body) keeps within one family, reads more system-like
|
||||
|
||||
Preserve: serif display plus sans body, modular scale, single weight per role. Shift: specific font choices to match register.
|
||||
|
||||
### Step 5: Write voice samples for the specific brand
|
||||
|
||||
The voice samples in the core archetype show character; they are not copy to lift directly. Write 5 to 10 new voice samples for the specific brand using the archetype's cadence and register.
|
||||
|
||||
## The cross-archetype check
|
||||
|
||||
Before finalizing, verify the output reads as coherent within the archetype:
|
||||
|
||||
- Color: matches the archetype's saturation and contrast character?
|
||||
- Type: matches the archetype's display and body relationship?
|
||||
- Voice: matches the archetype's cadence and register?
|
||||
- Layout: matches the archetype's density and whitespace tendency?
|
||||
|
||||
If two of the four diverge from the archetype, either pick a different archetype or accept that the brand is a blend (and document which archetype contributes which dimension).
|
||||
|
||||
## When to abandon an archetype mid-flow
|
||||
|
||||
The archetype is wrong if:
|
||||
- Three or more dimensions resist adaptation to the brief
|
||||
- The audience signals reject the archetype's defaults (for example picking Editorial Restrained for a children's app)
|
||||
- Direct competitors all live in the same archetype and your brief needs differentiation
|
||||
|
||||
When abandoning, return to the vertical file for that industry and pick a different starting archetype. Do not try to retrofit an archetype that does not fit.
|
||||
Vendored
+44
@@ -0,0 +1,44 @@
|
||||
# B2B SaaS: Developer Tools
|
||||
|
||||
## Vertical summary
|
||||
|
||||
Brands serving developers building software. Audience values: technical precision, documentation depth, time-to-first-API-call. Brands compete on developer experience, primitive quality, observability, and composition. The category is mature with established archetypes.
|
||||
|
||||
## Common archetypes in this vertical
|
||||
|
||||
The dominant archetype is **Technical Precise** (Stripe docs, Sentry, Datadog). **Editorial Restrained** is the rising adjacent archetype (Linear, Vercel, Resend). **Bold Confident** appears at the consumer-edge (Loom, formerly Heroku). Other archetypes are rare in this space; warmth and play do not read as credibility to developers building production systems.
|
||||
|
||||
## Brand-to-archetype mapping
|
||||
|
||||
| Brand | Archetype | What's distinctive |
|
||||
|---|---|---|
|
||||
| Stripe | Technical Precise with Editorial undertones | Best-in-category documentation aesthetic; navy and violet accents; serif display creeping into marketing |
|
||||
| Linear | Editorial Restrained | Single-accent restraint; brutal type hierarchy; muted palette |
|
||||
| Vercel | Editorial Restrained leaning Technical Precise | Black and white; Geist font system; minimal accents |
|
||||
| Sentry | Technical Precise | Dark mode dominant; purple accent; data-dense |
|
||||
| Datadog | Technical Precise | Cool palette; UI-led marketing; dense |
|
||||
| Resend | Editorial Restrained | New entrant; serif display; warm paper background |
|
||||
| Cloudflare | Bold Confident | Orange brand color; energetic; consumer-tilted |
|
||||
| GitHub | Editorial Restrained adjacent | Octocat character softens the precision |
|
||||
| Supabase | Bold Confident leaning Technical Precise | Green primary; recently more restrained |
|
||||
| Cursor | Technical Precise | Dark-mode-first; tool-focused; understated |
|
||||
|
||||
## Vertical-specific adaptation notes
|
||||
|
||||
- **Documentation surfaces are first-class**: developer brands need documentation as part of the brand surface, not an afterthought. The type system must scale to long-form technical reading.
|
||||
- **Code samples are brand assets**: how code renders (syntax highlighting palette, line numbers, copy buttons) is brand expression.
|
||||
- **Dark mode is required**, not optional. Most developers spend their day in dark interfaces.
|
||||
- **Performance signals as brand signals**: page load time, animation frame rate, perceived speed are part of how developers judge developer brands.
|
||||
- **Density tolerance**: developers tolerate (and often prefer) higher information density than other B2B audiences.
|
||||
|
||||
## Common archetype evolution
|
||||
|
||||
Developer brands frequently start Technical Precise and add Editorial Restrained as they mature. Stripe's evolution from pure technical to editorial-influenced marketing is the canonical example. Conversely, brands that start Bold Confident (Cloudflare, Supabase) sometimes retreat toward restraint as they target enterprise.
|
||||
|
||||
The early-stage developer brand archetype shift is almost always: drop the consumer-tinted color, add a serif, lean into restraint. The mature-stage shift is sometimes: re-introduce a careful illustration system to soften pure restraint (GitHub's Octocat-era is the canonical case).
|
||||
|
||||
## Vertical anti-patterns
|
||||
|
||||
- **Playful Energetic in developer tools**: reads as unserious. Developers building production systems do not want a mascot taking up screen real estate in their dashboard.
|
||||
- **Luxe Considered in developer tools**: reads as out-of-touch. Developer tools differentiate on substance, not premium feel.
|
||||
- **Vibrant Saturated in developer tools**: rare and risky; works only when the brand is consumer-tilted (Cloudflare manages it with discipline).
|
||||
+43
@@ -0,0 +1,43 @@
|
||||
# B2B SaaS: Business Productivity
|
||||
|
||||
## Vertical summary
|
||||
|
||||
Brands serving teams getting work done across documents, projects, communications, and design. Audience is prosumer-tilted: knowledge workers who self-serve, evaluate based on demos and free trials, and bring tools into their organizations from the bottom up. Brands compete on approachability, integration depth, and brand likeability alongside functional differentiation.
|
||||
|
||||
## Common archetypes in this vertical
|
||||
|
||||
The dominant archetypes are **Warm Conversational** (Slack, Mailchimp, Figma in marketing) and **Bold Confident** (Notion, Linear in launches). **Playful Energetic** appears at the edges (Asana classic era). **Editorial Restrained** is rising (Coda, Notion's recent surfaces). The category rewards personality more than developer tools but less than consumer apps.
|
||||
|
||||
## Brand-to-archetype mapping
|
||||
|
||||
| Brand | Archetype | What's distinctive |
|
||||
|---|---|---|
|
||||
| Notion | Bold Confident leaning Warm Conversational | Black on white plus illustration character; emoji-rich; oversized type |
|
||||
| Figma | Warm Conversational | Multi-hue creative palette; illustration-led; community-driven |
|
||||
| Loom | Bold Confident | Recent rebrand bold-purple-and-black; high contrast |
|
||||
| Slack | Warm Conversational | Multi-hue saturated brand colors; hands-and-objects illustration era |
|
||||
| Airtable | Warm Conversational | Multi-color brand; spreadsheet-meets-database approachable |
|
||||
| Coda | Editorial Restrained | Type-led; restrained palette; document-first feeling |
|
||||
| Asana | Playful Energetic moving to Warm Conversational | Mascot-era to recent considered warmth |
|
||||
| ClickUp | Vibrant Saturated | Multi-hue palette; expressive; consumer-tilted |
|
||||
| Monday.com | Vibrant Saturated | Saturated multi-hue; bold UI; high energy |
|
||||
| Dropbox | Vibrant Saturated leaning Editorial Restrained | 2017 rebrand era is the canonical example of the shift |
|
||||
|
||||
## Vertical-specific adaptation notes
|
||||
|
||||
- **Illustration budget matters**: brands without illustration capacity should pick Editorial Restrained or Bold Confident rather than Warm Conversational or Playful Energetic. Bad illustration kills the warm archetypes immediately.
|
||||
- **Onboarding surface as brand surface**: in productivity, onboarding flows are heavily branded and high-impact. The archetype must extend cleanly into product chrome.
|
||||
- **Self-serve discovery**: pricing pages, signup flows, and product tours carry brand weight. Restraint in these surfaces signals trust; warmth signals approachability.
|
||||
- **Bottom-up adoption pattern**: brands are evaluated by individual users before procurement. The archetype should not require enterprise sign-off to feel right.
|
||||
|
||||
## Common archetype evolution
|
||||
|
||||
Productivity brands often start Warm Conversational with heavy illustration and pull back toward Editorial Restrained or Bold Confident as they scale into enterprise. Slack's evolution shows this: early Slack was warm-illustration-heavy; current Slack reads more restrained while retaining color personality. Notion's evolution is similar.
|
||||
|
||||
The mature-stage shift is frequently: keep the personality in voice and color, remove decorative illustration from primary surfaces, lean into typographic hierarchy.
|
||||
|
||||
## Vertical anti-patterns
|
||||
|
||||
- **Pure Technical Precise in productivity**: reads as developer tool rather than productivity tool. Audience expects warmth.
|
||||
- **Luxe Considered in productivity**: reads as enterprise theatre. Self-serve audiences read restraint as remote.
|
||||
- **Rugged Utilitarian**: completely incompatible with the audience.
|
||||
Vendored
+43
@@ -0,0 +1,43 @@
|
||||
# B2B SaaS: Marketing and Sales
|
||||
|
||||
## Vertical summary
|
||||
|
||||
Brands serving marketers, sales teams, growth professionals, and revenue operations. Audience is mixed prosumer and enterprise: bottom-up adoption among individual marketers, top-down evaluation by RevOps and procurement. Brands compete on platform breadth, integration ecosystems, attribution claims, and trust signals to budget-holders.
|
||||
|
||||
## Common archetypes in this vertical
|
||||
|
||||
The dominant archetypes split by audience tier. **Warm Conversational** dominates SMB and prosumer (Mailchimp, Intercom, ConvertKit). **Bold Confident** appears at the growth-energy edge (Drift, Mutiny). **Clinical Trustworthy** dominates enterprise (Salesforce, Marketo). **Editorial Restrained** is the rising adjacent archetype (Webflow's marketing surfaces).
|
||||
|
||||
## Brand-to-archetype mapping
|
||||
|
||||
| Brand | Archetype | What's distinctive |
|
||||
|---|---|---|
|
||||
| Mailchimp | Warm Conversational | Multi-hue brand; mascot-era illustration; SMB-focused |
|
||||
| Webflow | Editorial Restrained | Serif-led marketing; typographic hierarchy; designer audience |
|
||||
| HubSpot | Warm Conversational | Orange and white; rounded illustration; inbound voice |
|
||||
| Intercom | Warm Conversational | Friendly conversational brand; chat-first UX |
|
||||
| Drift | Bold Confident | Bold colors; conversational-AI positioning |
|
||||
| Marketo | Clinical Trustworthy | Cool palette; enterprise-trust signals; B2B authority |
|
||||
| Salesforce | Clinical Trustworthy at enterprise edge | Cloud iconography; trust-blue; enterprise authority |
|
||||
| ConvertKit (Kit) | Warm Conversational | Creator-focused warmth; muted palette |
|
||||
| Mutiny | Bold Confident | Saturated personalization-as-brand |
|
||||
| Apollo | Editorial Restrained leaning Bold Confident | Recent restrained typography redesign |
|
||||
|
||||
## Vertical-specific adaptation notes
|
||||
|
||||
- **Enterprise versus prosumer split is wide**: prosumer leans warm and friendly; enterprise leans clinical and authoritative. The brand should pick a lane and commit; trying to do both produces neither.
|
||||
- **Trust signals matter**: customer logo strips, peer-reviewed comparison tables, security certifications carry brand weight in this vertical.
|
||||
- **Demo and trial flows**: a high portion of brand perception forms during the demo or free trial. The archetype must extend cleanly into in-product surfaces.
|
||||
- **AI-positioning surge**: many brands in this category have recent AI-features positioning that affects archetype choice; AI features tend to pull brands toward Technical Precise or Bold Confident.
|
||||
|
||||
## Common archetype evolution
|
||||
|
||||
Marketing and sales brands frequently start Warm Conversational at SMB and evolve toward Clinical Trustworthy or Editorial Restrained as they target upmarket. Mailchimp's evolution from playful-illustration to more restrained type-led marketing reflects this. HubSpot's evolution from friendly orange to a more institutional brand presence is another example.
|
||||
|
||||
The mature-stage shift is frequently: drop heavy illustration, narrow the palette, lean into customer evidence rather than personality.
|
||||
|
||||
## Vertical anti-patterns
|
||||
|
||||
- **Playful Energetic in enterprise marketing tools**: reads as unserious to budget-holders.
|
||||
- **Luxe Considered in mass-market marketing tools**: reads as out-of-touch with the SMB user base.
|
||||
- **Pure Technical Precise**: works for some categories (analytics, attribution) but feels wrong for relationship-building tools (CRM, email).
|
||||
Vendored
+43
@@ -0,0 +1,43 @@
|
||||
# B2B SaaS: Data and Analytics
|
||||
|
||||
## Vertical summary
|
||||
|
||||
Brands serving data teams, analysts, product managers, and engineers working with data infrastructure, business intelligence, and product analytics. Audience values: query power, schema clarity, time-to-first-insight, and trust in numbers. The category overlaps with developer tools at the infrastructure end and with marketing analytics at the application end.
|
||||
|
||||
## Common archetypes in this vertical
|
||||
|
||||
The dominant archetypes are **Technical Precise** (Mixpanel, Amplitude, Snowflake) and **Editorial Restrained** (dbt, Hex, Threshold the fictional reference build). The category rewards precision; **Clinical Trustworthy** appears at the enterprise BI edge (Tableau historically); **Bold Confident** appears at the new-entrant edge (Hex at launch).
|
||||
|
||||
## Brand-to-archetype mapping
|
||||
|
||||
| Brand | Archetype | What's distinctive |
|
||||
|---|---|---|
|
||||
| Mixpanel | Technical Precise | Cool palette; product analytics rigor; chart-as-hero |
|
||||
| Amplitude | Technical Precise | Blue and white; data-density tolerant; PLG positioning |
|
||||
| Looker | Technical Precise | Enterprise BI restraint; Google acquired |
|
||||
| Snowflake | Editorial Restrained adjacent | Restrained type; cloud-native confidence |
|
||||
| Tableau | Clinical Trustworthy historically, Editorial Restrained recently | Recent rebrand pulled toward typographic restraint |
|
||||
| dbt | Editorial Restrained | Type-led; community-driven; restraint as differentiator |
|
||||
| Hex | Bold Confident | Saturated brand; modern data workspace positioning |
|
||||
| Census | Editorial Restrained | Recent shift toward type-led restraint |
|
||||
| Hightouch | Bold Confident | Strong brand colors; reverse ETL positioning |
|
||||
| Threshold (fictional reference) | Editorial Restrained | Catalog reference build; PLG onboarding analytics |
|
||||
|
||||
## Vertical-specific adaptation notes
|
||||
|
||||
- **Chart and table rendering as brand**: how a chart looks, how table cells align, how numbers format are core brand expression. The archetype must extend cleanly into data visualization conventions.
|
||||
- **Documentation depth**: data tools live and die on documentation. Long-form technical reading is core to the brand surface, not auxiliary.
|
||||
- **Trust through precision**: vague claims undermine the archetype. Specific numbers, specific schemas, specific examples carry the brand.
|
||||
- **SQL and code as content**: query examples, schema definitions, and code samples are first-class brand assets.
|
||||
|
||||
## Common archetype evolution
|
||||
|
||||
Data brands frequently start Technical Precise and add Editorial Restrained as they mature into prosumer territory. Snowflake's evolution from pure technical to restrained editorial is the canonical case. Conversely, brands that start Bold Confident (Hex, Hightouch) often pull back toward restraint as they target enterprise.
|
||||
|
||||
The early-stage shift is usually: keep the technical precision in product surfaces, add editorial restraint to marketing.
|
||||
|
||||
## Vertical anti-patterns
|
||||
|
||||
- **Playful Energetic in data tools**: reads as untrustworthy with numbers. Audiences expecting analytical rigor reject playful brand expression.
|
||||
- **Luxe Considered in data tools**: reads as marketing rather than substance.
|
||||
- **Rugged Utilitarian**: completely incompatible with the audience and the category.
|
||||
Some files were not shown because too many files have changed in this diff Show More
Reference in New Issue
Block a user