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
.claude/commands/optimize-referrals.mdWhat 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.mdCall it with /optimize-referrals. For all projects use ~/.claude/commands/
Manually: put the files in place
~/.codex/prompts/optimize-referrals.mdCall it with /prompts:optimize-referrals. Codex marks this format deprecated in favour of skills
Manually: put the files in place
.github/prompts/optimize-referrals.prompt.mdManually: put the files in place
.gemini/commands/optimize-referrals.tomlGemini stores commands as TOML: the prompt text goes into the prompt field
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