# Churn signals analysis (ds-churn-signals) Human Guide

## What This Is For
Use this skill when the user wants to identify accounts at risk of churning, understand why users are cancelling, or find early warning signals before churn happens. It gives the agent a clearer input/output frame for go-to-market work: what context to ask for, what decisions to make, and what usable artifact to return.

Use this as a human-readable version of the Churn signals analysis (ds-churn-signals) agent skill. It is meant for marketers, operators, founders, and other non-coders who want the workflow without reading agent-specific implementation instructions.

## When To Use This
- Use this when you need a repeatable process for churn signals analysis (ds-churn-signals).
- Use this when the task needs judgment, examples, constraints, or a clear output format rather than a one-off prompt.
- Use this when you want to hand an AI assistant enough context to produce a usable marketing artifact.

## When Not To Use This
- Do not use this when you only need a quick factual answer.
- Do not use this when the work depends on private data you cannot share with the assistant.
- Do not use this as a replacement for legal, compliance, financial, or medical review.

## What You Need Before Starting
- The goal or business outcome you want.
- The audience, customer segment, or market context.
- Any source material the assistant should respect, such as notes, briefs, examples, URLs, or brand guidance.
- Constraints such as tone, length, channel, deadline, region, or approval requirements.
- A clear definition of what a good final answer should look like.

## Step-By-Step Workflow
1. State the job clearly: "Use the Churn signals analysis (ds-churn-signals) guide to help me with..."
2. Add context: audience, goal, offer, channel, source material, and constraints.
3. Ask the assistant to identify missing inputs before producing the final output.
4. Have the assistant follow the skill-specific guidance below.
5. Review the result against the final checklist and ask for revisions where needed.

## Skill-Specific Guidance
- Plan types and their expected usage patterns
- The primary product features (what does "active usage" look like?)
- Any known churn reasons from past analysis
- Subscription status (active, trialing, cancelled)
- Revenue by date (last 90 days, for trend detection)
- MRR from active subscriptions (yearly amounts ÷ 12 handled automatically)
- Churn rate: use the active count from step 1 + cancellation count
- Payment failure rate and repeat offenders: from step 2
- Revenue at risk: `mrr_at_risk` from step 2
- Payment failure: 3+ failed charges in the period (card is dead)
- Payment failure on a high-value account (plan amount > $100/month)
- Subscription set to cancel_at_period_end = true (they already decided)

## Decision Points And Nuance
The original skill emphasizes: Step 1 — Read context, Step 2 — Get the data, Path A — Dataslayer MCP is connected (automatic), Path B — No MCP detected (manual data), Process data with ds_utils, Step 3 — Score accounts by churn risk, Step 4 — Write the report, Churn signals report — [date], Red accounts — intervene this week, Cancellations last 30 days.

Use these questions to steer the work:
- What is the intended audience or buyer?
- What source material must be preserved?
- What should the assistant optimize for: clarity, persuasion, accuracy, speed, creativity, or conversion?
- What examples represent the desired quality bar?
- What should the assistant avoid?

## Common Mistakes
- **Important: Stripe dimension combinations can fail.** Some combinations
- **Important: use `subscription_plan_amount` (base currency), not
- **Important: `subscription_cancellation_feedback` causes 502 errors
- Required — Active subscriptions:
- Required — Payment failures (for involuntary churn):
- After the MCP returns data, process through ds_utils. **Do not write inline
- Do not write a generic "reach out to them" recommendation.
- sequence starting today. Do not wait for manual outreach."

## Copy-And-Paste Prompt
```text
Use the Churn signals analysis (ds-churn-signals) human guide.

My goal:
[Describe the business outcome]

Audience:
[Describe who this is for]

Context and source material:
[Paste notes, examples, links, or existing copy]

Constraints:
[Tone, length, channel, timeline, must-include items, must-avoid items]

Before producing the final output, ask me for any missing information that would materially improve the result.
```

## Final Checklist
- [ ] The output matches the original goal.
- [ ] The audience and context are reflected in the answer.
- [ ] Important constraints and source material were preserved.
- [ ] The assistant made the relevant decisions explicit.
- [ ] The final artifact is ready to use, review, or hand to the next person.

## Source
This guide was generated from the dataslayer-ai/marketing-skills skill entry for `ds-churn-signals`.

## Source Skill Notes
These notes preserve the nuance from the original skill. Use them as supporting reference when the workflow above feels too generic.

# Churn signals analysis (ds-churn-signals)

You are a retention analyst who understands that churn is almost always
predictable in hindsight — and often preventable in real time. Your job is
to surface the accounts that are quietly disengaging before they hit the
cancel button, and give the team enough lead time to intervene. You treat
"unused service" not as a cancellation reason but as a product and
onboarding failure that started weeks earlier.

---

## Step 1 — Read context

Business context (auto-loaded):
!`cat .agents/product-marketing-context.md 2>/dev/null || echo "No context file found."`

Pay particular attention to:
- Plan types and their expected usage patterns
- The primary product features (what does "active usage" look like?)
- Any known churn reasons from past analysis

If no context was loaded above, ask one question:
> "What does healthy usage look like for your product —
> how many queries or actions per week should an active account run?"

If the user passed a risk tier filter as argument, focus on: $ARGUMENTS

---

## Step 2 — Get the data

First, check if a Dataslayer MCP is available by looking for any tool
matching `*__natural_to_data` in the available tools (the server name
varies per installation — it may be a UUID or a custom name).

### Path A — Dataslayer MCP is connected (automatic)

**Primary data source: Stripe** (subscription and payment data).
If a database connection is also available, use it for product usage data.
GA4 can supplement with engagement patterns but is not the primary source.

**Important: Stripe dimension combinations can fail.** Some combinations
(e.g., product + balanceTransaction) are invalid and return errors.
If a query fails, simplify by removing dimensions and retrying.

**Important: use `subscription_plan_amount` (base currency), not
`subscription_plan_amount_eur`.** Accounts may have mixed currencies
(USD, EUR, GBP) and forcing EUR conversion causes errors.

**Important: `subscription_cancellation_feedback` causes 502 errors
on large queries.** Use `subscription_cancellation_reason` only as
the dimension — it is more reliable.

Fetch in parallel:

```
Stripe — Active subscriptions:
  - subscription_status, subscription_plan_name,
    subscription_plan_interval, subscription_count,
    subscription_plan_amount
    Group by: subscription_status, subscription_plan_name,
    subscription_plan_interval
    Date range: current month

Stripe — Cancellations:
  - subscription_cancellation_reason, subscription_plan_name,
    subscription_count, subscription_plan_amount
    Group by: subscription_cancellation_reason, subscription_plan_name
    Date range: last 60 days (to capture full churn cycle)

Stripe — Failed charges:
  - charge_status, charge_failure_code, charge_failure_message,
    charge_amount, customer_id, customer_email, date
    Date range: last 30 days
    → Filter locally for failed charges (charge_failure_code != "--")
    → Group by customer to find repeat failures

Stripe — Revenue trend (if time allows):
  - date, charge_amount (successful only)
    Date range: last 90 days