define-events — Claude Code command: what it does, how to install
define-events creates an analytics instrumentation specification with event schemas, owners, and QA steps. Useful when aligning tracking plans across CDPs, product analytics, and warehouses.
Apache-2.0 ★ 450 updated 2026-04-03
.claude/commands/define-events.mdWhat define-events does
The command guides telemetry design through five stages: gathering requirements, cataloging event payloads, mapping governance rules, preparing QA steps, and release planning. The result includes a tracking plan formatted as CSV, JSON, or YAML alongside testing checklists and dashboard verification requirements.
Execution context and audit logs get saved directly to .claude/plans/plan-<timestamp>.json. The orchestrator applies a default limit of two retries on testing failures and routes stubborn blockers through an escalation path ending at RevOps.
The workflow relies on the analytics-data-strategist agent alongside instrumentation and quality-gates skills. If these supporting components are missing from your setup, schema validation and governance checks cannot complete.
What it helps with
- create tracking specifications for CDPs and warehouses
- catalog event properties, payload formats, and owners
- define QA verification steps using logs and test replays
- log audit trails and dependencies in
.claude/plans
Example prompts for the agent
- /analytics-pipeline-orchestration:define-events --use_case "pipeline velocity" --sources "product,crm" --tools "Segment,dbt"
- /analytics-pipeline-orchestration:define-events --use_case "checkout funnel" --sources "web,billing" --tools "Segment,Snowflake"
- /analytics-pipeline-orchestration:define-events --use_case "retention tracking" --sources "product" --tools "Mixpanel"
How to install define-events
Manually: put the files in place
.claude/commands/define-events.mdCall it with /define-events. For all projects use ~/.claude/commands/
Manually: put the files in place
~/.codex/prompts/define-events.mdCall it with /prompts:define-events. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.github/prompts/define-events.prompt.mdManually: put the files in place
.gemini/commands/define-events.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
Questions about define-events
How to install define-events in Claude Code?
Add the command file to .claude/commands/define-events.md. Once saved, the command is ready to run in Claude Code.
What does define-events produce?
It outputs an instrumentation spec, a tracking plan in CSV, JSON, or YAML, a QA verification checklist, and an execution plan saved in .claude/plans.
How does the command handle QA failures?
It enforces a default retry limit of 2 failures. Persistent blockers trigger an escalation ladder from Analytics Data Strategist to Data Engineering Lead and RevOps.
Source text
define-events.md · Apache-2.0
--- name: define-events description: Produces instrumentation specification with events, properties, owners, and QA steps. usage: /analytics-pipeline-orchestration:define-events --use_case "pipeline velocity" --sources "product,crm" --tools "Segment,dbt" --- # Command: define-events ## Inputs - **use_case** – business question or KPI the events support. - **sources** – data sources involved (product, web, CRM, MAP, billing). - **tools** – instrumentation stack (CDP, product analytics, warehouse, dbt). - **constraints** – optional legal/compliance requirements. - **timeline** – optional delivery date. ### GTM Agents Pattern & Plan Checklist > Mirrors GTM Agents orchestrator blueprint @puerto/plugins/orchestrator/README.md#112-325. - **Pattern selection**: Instrumentation typically runs **pipeline** (requirements → catalog → governance → QA → change mgmt). If governance + QA can run parallel, log a **diamond** segment with merge gate in the plan header. - **Plan schema**: Save `.claude/plans/plan-<timestamp>.json` capturing objective, data sources, task IDs, dependencies, context passing (schemas, privacy notes), error handling, and success metrics (coverage %, defect ceiling). - **Tool hooks**: Reference `docs/gtm-essentials.md` stack (Serena for repo diffs, Context7 for platform/legal docs, Sequential Thinking for review flows, Playwright for front-end event QA when applicable). - **Guardrails**: Default retry limit = 2 for QA failures; escalation ladder = Analytics Data Strategist → Data Engineering Lead → RevOps. - **Review**: Run `docs/usage-guide.md#orchestration-best-practices-puerto-parity` before execution to confirm agents, dependencies, deliverables. ## Workflow 1. **Requirement Gathering** – clarify KPIs, dimensions, and downstream consumers. 2. **Event Cataloging** – list events, payloads, properties, IDs, sampling rate, ownership. 3. **Governance Mapping** – document naming conventions, consent handling, retention policies. 4. **QA Plan** – outline testing methods (unit tests, replay, observability dashboards). 5. **Change Management** – define review/approval steps, rollout plan, and version control. ## Outputs - Instrumentation spec (event name, description, properties, source, owner, status). - Tracking plan (CSV/JSON/YAML) aligned with CDP or analytics tool requirements. - QA checklist + evidence plan (logs, dashboards, sample payloads). - Plan JSON entry stored/updated in `.claude/plans` for audit trail. ## Agent/Skill Invocations - `analytics-data-strategist` – leads requirements + governance. - `instrumentation` skill – enforces schema + consent rules. - `quality-gates` skill – defines QA expectations. ## GTM Agents Safeguards - **Fallback agents**: document substitutes (e.g., BI Publisher covering QA) if specialists unavailable. - **Escalation triggers**: if instrumentation defects or compliance blockers breach guardrails twice in 48h, escalate to Data + Legal leadership, triggering GTM Agents-style rip-cord. - **Plan maintenance**: update plan JSON/change log whenever events, schemas, or governance rules change to keep analytics audit-ready. ---
© gtmagents · Apache-2.0 · gtmagents/gtm-agents