Fewshot Attempt 01

ApexCloud Retention Operations API — CRM Analytics Skill

Overview

This skill covers tasks that consume the ApexCloud Retention Operations API (http://127.0.0.1:8074) to produce structured CRM analytics deliverables for Customer Success, Finance, and Data Science teams. The API returns account profiles, billing snapshots, support health, NPS, receivables, product usage, expansion opportunities, HR/event context, and churn-model exports.

The prompt determines the deliverable type. Always read input/payloads/answer_template.json to confirm the exact output schema.

API Base and Endpoint Families

• Base URL: http://127.0.0.1:8074
• Account endpoints: /api/accounts/{account_id} plus sub-resources:
  • /api/accounts/{account_id}/profile
  • /api/accounts/{account_id}/billing_snapshot
  • /api/accounts/{account_id}/support_health
  • /api/accounts/{account_id}/nps
  • /api/accounts/{account_id}/receivables
  • /api/accounts/{account_id}/product_usage
  • /api/accounts/{account_id}/expansion_opportunities
  • /api/accounts/{account_id}/metrics?start=YYYY-MM&end=YYYY-MM
  • /api/accounts/{account_id}/tickets?start=YYYY-MM-DD&end=YYYY-MM-DD
• Finance: /api/finance/ar-aging
• CRM: /api/accounts, /api/opportunities
• Operations: /api/hr/summary, /api/events/performance
• Exports: /exports/churn/train.csv, /exports/churn/validation.csv, /exports/churn/candidates.csv

Habit: When a task lists specific account_ids, call the relevant per-account endpoints for every listed ID. When a task asks for a rollup (collections board, churn validation), start with the rollup endpoint (/api/finance/ar-aging, /exports/churn/candidates.csv) and link downstream.

Deliverable Types and Routing Rules

Rule: The prompt explicitly names the deliverable. Always match the output schema to answer_template.json; do not assume one template fits all tasks.

Global Output Conventions

Apply these precision rules across all deliverables unless the prompt overrides:

Controlled Vocabularies

Risk Levels

critical, high, medium, low

Primary Actions

collections_followup, technical_recovery, renewal_save, executive_qbr, nurture_monitor, no_action

Reason Codes

overdue_receivable, nps_drop, sla_degradation, usage_decline, renewal_window, expansion_offset, clean_billings, low_tenure_high_churn

Link Status (Collections)

linked, unlinked

Ticket Trend

improving, worsening, flat

Metric Sources

crm_closed_won, support_export, sla_report, nps_survey, billing_snapshot, ar_aging, pipeline_crm, event_dashboard, hr_report

Review Owners

solutions_engineering, customer_success, finance_ops

Agenda Topics (QBR)

partnership_overview, q2_metrics, performance_highlights, q3_initiatives, technical_recovery, commercial_expansion

Accuracy Bands (Churn)

below_70, 70_to_79, 80_to_89, 90_plus

Tenure Coefficient Direction

negative, positive, zero

1. Retention Action Board Workflow

Output Schema

{
  "action_board": [...],
  "segment_summary": {...},
  "followup_calendar": {...},
  "policy_codes": {...}
}

Action Board Entry Fields

Risk Scoring Heuristics

• critical: 4+ risk factors, or a severe combination such as renewal_window + nps_drop + sla_degradation + usage_decline.
• high: 3–4 risk factors including at least one high-severity factor (overdue_receivable, renewal_window, usage_decline, nps_drop).
• medium: 1–2 risk factors, or renewal_window / overdue_receivable without enough severity for high.
• low: 0–1 minor factors (e.g., only sla_degradation or only expansion_offset).

Action Priority (highest wins)

1. collections_followup — if overdue_receivable is present.
2. technical_recovery — if nps_drop + sla_degradation + usage_decline are present together, or if technical health is severely degraded.
3. renewal_save — if renewal_window is present and not overridden by collections or technical recovery.
4. executive_qbr — reserved for strategic escalations (rarely primary).
5. nurture_monitor — for low-risk accounts with minor flags.
6. no_action — when risk level is low and no urgent factor exists.

Ranking Rules

1. Sort by risk_level descending: critical → high → medium → low.
2. Within the same risk level, sort by current_arr descending.
3. Assign rank sequentially starting at 1.

Segment Summary

Follow-Up Calendar

The prompt provides due dates by action. Map them exactly:

{
  "collections_followup": "2026-07-15",
  "technical_recovery": "2026-07-18",
  "renewal_save": "2026-07-22",
  "executive_qbr": "2026-07-29",
  "nurture_monitor": "2026-08-05"
}

If the prompt omits an action, omit it from the calendar.

Policy Codes

Policy codes are predefined sets that correspond to the analysis-period type. Use the set that matches the prompt's period:

Map keys:

• risk_model_code → RS-*
• arr_source_code → REV-*
• support_hygiene_code → SUP-*
• action_priority_code → ACT-*
• board_sort_code → BORD-*
• exposure_formula_code → EXP-*
• calendar_policy_code → CAL-*

2. QBR Metrics Packet Workflow

Output Schema

{
  "qbr_metrics": [...],
  "highlights": {...},
  "metric_sources": {...},
  "review_plan": {...},
  "agenda_topics": [...]
}

QBR Metrics (monthly)

For each month in the quarter (3 entries):

• month: YYYY-MM
• revenue: monthly revenue from crm_closed_won or billing metrics
• support_tickets: ticket count for the month
• sla_compliance_pct: SLA compliance percentage
• nps_score: integer NPS score (can be null if missing)

Highlights

Metric Sources

Populate with the canonical source enum values:

{
  "revenue": "crm_closed_won",
  "support_tickets": "support_export",
  "sla_compliance": "sla_report",
  "nps": "nps_survey"
}

Review Plan

• review_owner: customer_success for standard QBRs; escalate to solutions_engineering if significant technical flags exist.
• review_due_date: Use the date given in the prompt.
• needs_technical_signoff: true if the account has sla_degradation, usage_decline, or technical_recovery flagged; otherwise false.

Agenda Topics

Select exactly four ordered topics from the enum. Common ordering:

1. partnership_overview
2. q2_metrics (or quarter-appropriate metrics topic)
3. technical_recovery (if technical issues exist) or performance_highlights
4. q3_initiatives (or next-quarter topic)

3. Collections Operations Board Workflow

Output Schema

{
  "financial_summary": {...},
  "pipeline_summary": {...},
  "overdue_followups": [...],
  "ops_context": {...},
  "policy_codes": {...}
}

Workflow

1. Query /api/finance/ar-aging as-of the prompt's A/R date.
2. Filter to customers with overdue balances in older aging buckets.
3. Attempt to link each A/R customer to a CRM account via /api/accounts.
4. Query /api/opportunities for the quarter to build pipeline summary.
5. Query /api/hr/summary and /api/events/performance for ops context.

Financial Summary

Pipeline Summary (Quarter scope)

Overdue Follow-Ups

Each entry:

• customer_name: from A/R record
• link_status: linked if account_id is resolved, else unlinked
• account_id: CRM account ID or null
• overdue_balance: from A/R
• due_date: the collections follow-up date given in the prompt
• primary_action: collections_followup

Sort: ascending by customer_name.

Ops Context

Include HR and event data exactly as returned by /api/hr/summary and /api/events/performance for the requested quarter/event:

• hr_headcount
• unpaid_claims_total
• event_orders
• event_revenue

Policy Codes (Collections)

Use the set that matches the quarter:

• Q2 collections: RCP-7, CM-5, PW-6, FS-4
• Keys: receivable_trigger_code, crm_match_code, pipeline_window_code, followup_scope_code

4. Churn Model Validation Workflow

Output Schema

{
  "model_validation": {...},
  "risk_ranking": [...],
  "cohort_checks": {...},
  "model_policy_codes": {...}
}

Workflow

1. Read /exports/churn/train.csv and /exports/churn/validation.csv.
2. Compute row counts, feature count, and accuracy.
3. Read /exports/churn/candidates.csv.
4. Filter to the account_ids specified in the prompt.
5. Sort by predicted_churn_probability descending.
6. Return the top N candidates (the prompt specifies the count, e.g., top 5).

Model Validation

Risk Ranking

Cohort Checks

Model Policy Codes

Select the set matching the analysis period:

• Standard Q2 validation: MOD-7, PRB-4, DEP-5, OUT-2
• Keys: model_protocol_code, probability_scale_code, deployment_rule_code, outreach_mapping_code

Common Pitfalls

1. Ignoring the template. Always read answer_template.json; deliverable shapes differ significantly across task types.
2. Wrong date granularity. Retention boards use YYYY-MM-DD; QBR metrics use YYYY-MM for month labels.
3. Precision errors. Currency must be exactly 2 decimals; probabilities exactly 3. Do not round prematurely.
4. Omitting nulls. next_touch_due_date is null for no_action accounts. account_id is null for unlinked collections customers.
5. Sorting mistakes. Retention boards sort by risk then ARR descending. Collections follow-ups sort by customer_name ascending. Churn rankings sort by probability descending.
6. Hard-coding policy codes. Policy codes are not universal; they map to the quarter or period length stated in the prompt.
7. Mixing action priorities. Collections always beats technical recovery, which beats renewal save, when multiple reason codes are present.
8. Missing expansion in exposure. net_revenue_exposure = arr_at_risk - open_expansion_pipeline. Do not subtract only for at-risk accounts; use the total open pipeline.
9. QBR agenda length. Must be exactly four topics, ordered logically.
10. Collections linkage. An A/R customer may match a CRM account by name but not by exact ID; resolve linkage carefully and set link_status accordingly.

Example Policy-Code Mapping Summary

If the prompt uses a different quarter or window, carry the numeric suffix pattern forward proportionally (e.g., Q3 3-month retention likely uses the next sequential set in the same family).