Skip to main content
command CX Codex

optimize-referrals — Claude Code command: setup and workflow

optimize-referrals analyzes referral conversion funnels, fraud patterns, and partner health to generate structured optimization plans in Claude Code.

Apache-2.0 ★ 450 updated 2026-04-03

Install into Claude Code · Manually: put the files in place All methods and platforms ↓
.claude/commands/optimize-referrals.md
Open on GitHub

What optimize-referrals does

This command audits referral programs through a structured five-stage pipeline: data refresh, funnel diagnostics, risk review, partner engagement checks, and playbook creation. The command accepts inputs for the analysis window (7d, 30d, 90d), detail level (summary or full), and breakdown dimensions such as channels or partner tiers.

Execution details are written directly to .claude/plans/plan-<timestamp>.json. This plan JSON tracks dependency graphs across data sources, success metrics like conversion lift and fraud reduction, plus error logs. The workflow coordinates with referral-architect, lifecycle-ops, and the fraud-detection and partner-ops skills.

Guardrails restrict failed data fetches or fraud model runs to two retries. If an alert threshold is breached twice, the workflow triggers an escalation ladder leading from Partner Ops to the executive sponsor.

What it helps with

  • Audit referral conversion from invites to closed revenue
  • Detect suspicious cohorts with fraud heuristics
  • Measure incentive efficiency across partner tiers
  • Build an optimization backlog with owners and projected impact

Example prompts for the agent

  • /referral-program-orchestration:optimize-referrals --window 30d --detail full --dimensions "channel,partner-tier"
  • /referral-program-orchestration:optimize-referrals --window 90d --detail summary --alert_threshold 0.05
  • /referral-program-orchestration:optimize-referrals --window 7d --experiments "tier-boost,instant-payout"

How to install optimize-referrals

Manually: put the files in place

.claude/commands/optimize-referrals.md

Call it with /optimize-referrals. For all projects use ~/.claude/commands/

Questions about optimize-referrals

How do I install optimize-referrals in Claude Code?

Add the command file to .claude/commands/optimize-referrals.md in your project repository. Claude Code will recognize the command automatically.

What does optimize-referrals do?

It evaluates referral conversion funnels, flags fraud risks through the fraud-detection skill, and generates an experiment backlog with projected impact.

Where are the audit plans stored?

The command saves its audit trail and task dependency graph to .claude/plans/plan-<timestamp>.json.

Source text

optimize-referrals.md · Apache-2.0
---
name: optimize-referrals
description: Analyzes referral performance, fraud risk, and partner health to recommend improvements.
usage: /referral-program-orchestration:optimize-referrals --window 30d --detail full --dimensions "channel,partner-tier"
---

# Command: optimize-referrals

## Inputs
- **window** – analysis horizon (7d, 30d, 90d).
- **detail** – summary | full to control output length.
- **dimensions** – optional breakdowns (channel, persona, partner-tier, region).
- **experiments** – optional list of tests to evaluate.
- **alert_threshold** – optional KPI threshold for escalations.

### GTM Agents Pattern & Plan Checklist
> Mirrors GTM Agents orchestrator blueprint @puerto/plugins/orchestrator/README.md#112-325.

- **Pattern selection**: Optimization review typically runs **pipeline** (data refresh → diagnostics → risk review → partner health → action plan). If diagnostics + risk review can run concurrently, note a **diamond** block with merge gate in the plan header.
- **Plan schema**: Save `.claude/plans/plan-<timestamp>.json` capturing window, datasets, task IDs, dependency graph (BI, fraud, partner ops), error handling, and success metrics (conversion lift, fraud reduction, partner NPS).
- **Tool hooks**: Reference `docs/gtm-essentials.md` stack—Serena for schema diffs, Context7 for referral SOPs/partner comms, Sequential Thinking for retro cadence, Playwright for offer flows or portal QA.
- **Guardrails**: Default retry limit = 2 for failed data pulls or fraud model runs; escalation ladder = Referral Architect → Partner Ops → Exec sponsor.
- **Review**: Run `docs/usage-guide.md#orchestration-best-practices-puerto-parity` before distributing recommendations to confirm dependencies and approvals.

## Workflow
1. **Data Refresh** – pull referral submissions, conversions, payouts, fraud flags, and NPS per dimension.
2. **Performance Diagnostics** – inspect funnel (invites → referrals → pipeline → revenue) and incentive efficiency.
3. **Risk Review** – run fraud heuristics, identify suspicious cohorts, confirm compliance logs.
4. **Partner Health** – evaluate top/bottom partners, share-of-voice, and engagement levels.
5. **Playbook Output** – recommend experiments (incentive tweaks, messaging, partner enablement) with expected impact.

## Outputs
- Performance dashboard snapshot with annotated insights.
- Fraud/risk summary referencing `fraud-detection` skill outputs.
- Optimization backlog with owners, ETA, and projected lift.
- Plan JSON entry stored/updated in `.claude/plans` for audit trail.

## Agent/Skill Invocations
- `referral-architect` – prioritizes experiments + approvals.
- `lifecycle-ops` – implements tooling or messaging changes.
- `fraud-detection` skill – validates risk findings.
- `partner-ops` skill – coordinates partner communications.

## GTM Agents Safeguards
- **Fallback agents**: document substitutes (e.g., Lifecycle Ops covering Architect) when leads unavailable.
- **Escalation triggers**: if alert_threshold breached twice or fraud risk spikes, trigger GTM Agents rip-cord escalation and record actions in plan JSON.
- **Plan maintenance**: update plan JSON/change log whenever metrics, thresholds, or partner tiers change to maintain audit continuity.

---

© gtmagents · Apache-2.0 · gtmagents/gtm-agents

Similar slash commands

All slash commands for Marketing and content →

From the same set224

The whole set →
run-standups run-standups runs a daily MQL→SQL pipeline standup, pulling routing metrics, logging blockers and assigning follow-up actions. CX Codex +1 ★ 450repo stars connect-signals connect-signals sets up data connections, schema alignment, and monitoring for B2B intent, product, and engagement feeds. CX Codex +1 ★ 450repo stars track-source track-source combines partner campaign data and produces attribution reporting with revenue contributions and suggested changes. Use it to review co-marketing results. CX Codex +1 ★ 450repo stars manage-assets manage-assets — a command for orchestrating co-branded asset production, approvals, and distribution across partner teams. Tracks asset inventory, routes review workflows, and packages deliverables for activation. CX Codex +1 ★ 450repo stars synthesize-feedback The synthesize-feedback command turns customer signals into ranked themes and estimates their impact. Use it to prepare evidence and follow-up priorities from feedback. CX Codex +1 ★ 450repo stars define-handoff define-handoff — a command to design lead-to-sales handoff: sets routing rules, response SLAs, and enablement requirements for each sales pod or segment. CX Codex +1 ★ 450repo stars monitor-personalization monitor-personalization audits personalization campaigns, tracks experiment outcomes, and flags consent violations across user segments. CX Codex +1 ★ 450repo stars editorial-ops editorial-ops is a Claude Code skill that plans multi-channel editorial calendars and coordinates GTM content production from ideation through distribution, with KPI guardrails set before assets ship. CX Codex +1 ★ 450repo stars

Project sponsors

Companies that keep this analytics open