Frontier · Prompt library

Copilot Adoption Segmentation and Churn Prompt

Copilot Adoption Segmentation and Churn

← Back to Prompt Library

📋 Review the schema first. Before running this prompt, confirm your column names and the Copilot/agent action taxonomy against the Schema Documentation.

🗂️DataPerson Query 📅Min data8–12+ weeks 💻LanguageR or Python 📦OutputHTML report / notebook 🎯LevelIntermediate

✓Last validated June 2, 2026 against vivainsights R 0.7.2 / Python 0.4.2.

Purpose

Classify Copilot users by usage intensity, track movement between segments and quantify churn. Churn measures disengagement after initial adoption.

Audience

People analytics leads, Copilot program managers, digital adoption teams

When to use

After collecting at least 8–12 weeks of Person Query data, when you need to understand how Copilot usage patterns change over time.

Required inputs

• Person query CSV with columns: PersonId, MetricDate, Copilot metrics (e.g., Copilot_Actions, Copilot_Assisted_Hours), and optional HR attributes (e.g., FunctionType, Area, Country or Organization)
• At least 8 weeks of data (12+ weeks recommended for meaningful churn analysis)
• A Copilot enabled-days field or another confirmed source of weekly licence status

Assumptions

• Data is at person-week granularity
• PersonId is a consistent anonymized identifier
• MetricDate is a date field representing the start of each week
• Licence status can be established for the person-weeks included in the analysis
• The vivainsights R or Python package is available in the environment

Recommended output

An HTML report or Jupyter/R notebook containing segment distribution charts, transition matrices, churn curves, and at-risk group analysis.

Quick prompt (short version)

Use this shorter prompt for a fast first pass that adapts to your data.

Help me create a segmentation and churn analysis for Copilot usage that classifies licensed users, tracks movement between segments over time, and highlights at-risk groups.
Start by loading the actual CSV and printing row count, column names, data types, date range, and unique people so you can map the real activity and HR fields.
Do not assume exact column names, and ask me for the file path, the main activity metric, or any unclear field mapping before you continue.
Prefer Copilot Enabled User or Total Copilot enabled days to establish licensing. For native licensed-only M365 Copilot metrics, null means unlicensed and zero activity means licensed but inactive. A verified metric with these semantics is a valid fallback without explicit licence fields.
Use `identify_usage_segments()` (vivainsights) to compute the five weekly usage segments. If it is unavailable, clearly label any alternative segmentation and print its thresholds.
Include both week-level segment trends and a stable user segment for group breakdowns, then build a week-to-week transition matrix only for users present in consecutive weeks.
If no suitable HR attribute is available, skip group summaries and focus on overall segment and churn results.
Independently of the rolling segments, define weekly activity from the observed action count. Churn means at least two consecutive active weeks followed by at least two consecutive inactive weeks; date it to the first inactive week once the second confirms it.
Identify currently at-risk users separately: they have one inactive week immediately after at least two active weeks and have not yet met the churn definition. Do not treat unknown or unlicensed weeks as inactive.
Flag if the time span is too short for reliable churn analysis.
Suppress below max(the organisational requirement, 5 distinct people), using floor 10 for dashboard/joined outputs. Protect complementary cells and embedded data, and never publish individual rankings.
Read configured weekly grouping and measurement windows, not date spacing. Within a supplied complete query's configured scope, absent activity rows contribute zero. Failed joins, out-of-scope periods and known coverage failures remain unresolved. Keep unlicensed weeks in the calendar so they break streaks and rolling eligibility windows.
End by listing any assumptions you made about thresholds, churn rules, or field mappings.

Use the detailed prompt below for a reproducible, exact-structure output. Use the quick prompt above for a faster first pass that you refine through follow-up turns.

Prompt

You are a behavioral analytics specialist. Your task is to perform a user segmentation and churn analysis on Microsoft Copilot usage data from a Viva Insights person query export. The goal is to classify users into usage-based segments, track transitions between segments, and quantify churn.

LANGUAGE CHOICE
Choose R or Python based on what is already installed in your environment to minimize setup.

DATA LOADING AND PREPARATION
1. Load the person query CSV using `import_query()` from the `vivainsights` library (R or Python). This handles variable name cleaning and type parsing automatically.
2. Identify Copilot metric columns by checking for columns containing the word "Copilot" in their name. Reference the taxonomy at https://github.com/microsoft/viva-insights-sample-code/blob/main/examples/example-data/copilot-metrics-taxonomy.csv to classify and validate the detected metrics. Use `Total_Copilot_actions_taken` as the primary activity metric. Print detected columns and the date range.
3. Identify HR / organizational attribute columns with `extract_hr(df, return = "names")` in R or `vi.extract_hr(df, return_type="suggestion")` in Python. Use the returned names for all segmentation breakdowns instead of hard-coding column names.
4. Classify person-weeks using the shared eligibility policy. Prefer explicit enablement or dated licence evidence, then a verified native licensed-only M365 metric. Keep unresolved eligibility separate.
5. Restrict segment and churn denominators to confirmed licensed person-weeks. Report the count with unknown licence status.
6. Read configured grouping, week start and measurement windows before calendar alignment. For licensed weeks, positive actions mean active and zero means inactive. Keep unlicensed or unresolved weeks in the calendar as breaks in segment windows and activity streaks.

USER SEGMENTATION
6. Use `identify_usage_segments()` from the `vivainsights` library to classify users into segments. This function uses `Total_Copilot_actions_taken` and classifies users based on both usage volume and consistency (habit formation over 12 weeks). Its canonical, mutually exclusive ladder is Power Users → Habitual Users → Novice Users → Low Users → Non-users (see the [Copilot Usage Segments definitions](https://microsoft.github.io/viva-insights-sample-code/copilot-usage-segments/#formal-definitions)). It is preferred over manual percentile-based segmentation. Use these exact segment names consistently throughout the report. Do not use the rolling segment as the weekly activity flag. Require a full contiguous licensed history with known activity for each rolling window. Withhold only affected windows when unlicensed weeks or unresolved evidence occur, without aborting other people's valid histories or recoding unlicensed people as licensed Non-users.

7. Also compute a "stable segment" for each user based on their most frequent weekly segment over the entire period (mode). This gives a single label per person.

SEGMENT DISTRIBUTION OVER TIME
8. For each week, count the number of users in each segment. Create:
   a. A stacked area chart showing the five segments over time (absolute counts).
   b. A stacked area chart showing the five segments as percentages of licensed users with an available segment. Report how many licensed users could not be classified.
   c. A summary table of the latest week's segment distribution.

SEGMENT BREAKDOWN BY HR ATTRIBUTES
9. For each available HR attribute, compute the segment distribution using the "stable segment" label. Create:
   a. A stacked bar chart showing segment proportions by each HR attribute value.
   b. Only publish groups with max(the organisational requirement, 5 distinct licensed people), using floor 10 for dashboard/joined outputs. Protect complementary cells and embedded data, and never publish individual rankings.
   If no suitable attribute is available, omit group charts and continue with the overall segment trends.
10. If group attributes are available, identify groups with the highest proportions of Power Users and Non-users. Label these as segment distributions, not as the separate at-risk churn definition below.

TRANSITION ANALYSIS
11. Build a week-over-week transition matrix. For each consecutive pair of weeks, count how many users moved from each segment to every other segment. Aggregate across all week transitions.
12. Normalize the matrix to show transition probabilities: given a user is in segment X this week, what is the probability they are in segment Y next week?
13. Visualize the transition matrix as a heatmap with annotations showing the probabilities.
14. Highlight key transitions of interest:
    - "Entering use": Non-user → any higher segment
    - "Returning to non-use": any higher segment → Non-user
    - "Deepening": a move up the ladder, e.g. Low User → Novice User, Novice User → Habitual User, or Habitual User → Power User
    - "Declining": a move down the ladder, e.g. Power User → Habitual User, Habitual User → Novice User, or Novice User → Low User

CHURN ANALYSIS
15. Define "churn" from the weekly activity flag, independently of the rolling segment: at least 2 consecutive active weeks immediately followed by at least 2 consecutive inactive weeks. The churn date is the first inactive week, confirmed only after the second. Unknown, missing or unlicensed weeks break the streak. A user may churn again after reactivation.
16. For each week, calculate:
    a. The number of users whose confirmed churn began that week.
    b. The churn rate: confirmed churn onsets / users with at least 2 consecutive active weeks immediately before that week who are licensed and have known activity in both that week and the following week. Do not report a rate for a week without the following week's observation.
17. Create a line chart of weekly churn rate over time.
18. Build a "time to churn" distribution: for users who churned, how many weeks were they active before churning? Show as a histogram.
19. Compute overall churn statistics:
    a. Total users who ever churned
    b. Percentage of ever-active users who churned
    c. Median active weeks before churn
    d. Re-activation rate: among those who churned and have subsequent known licensed weeks, what percentage became active again later? Note incomplete follow-up.

AT-RISK USER IDENTIFICATION
20. Identify currently at-risk users: licensed users with exactly 1 inactive week immediately after at least 2 consecutive active weeks. They have not yet met the churn definition.
21. If an HR attribute is available, summarise at-risk users by a selected field, such as FunctionType, Area, Country or Organization.
22. Create a table of at-risk user counts by available HR attributes. If no suitable field exists, omit group summaries and state why.

REPORT GENERATION
23. Compile all outputs into an intermediary document first, then export to HTML:
    - R: Create an RMarkdown file (.Rmd), then knit to a self-contained HTML file.
    - Python: Create a Jupyter notebook (.ipynb), then export to a self-contained HTML file. Keep the intermediary file alongside the HTML output for troubleshooting. The report should contain these sections:
    a. "Segment Definitions": explain the five segments and thresholds used.
    b. "Segment Distribution": charts from step 8 and summary table.
    c. "Segment Breakdown by Group" (if suitable HR attributes are available): charts and segment-distribution callouts from steps 9 and 10.
    d. "Transition Analysis": heatmap from step 13, key transition highlights from step 14.
    e. "Churn Analysis": churn rate trend, time-to-churn histogram, summary statistics.
    f. "At-Risk Users": overall summary and, if available, the group table from step 22.
    g. "Key Takeaways": 3-5 bullet points synthesising the most important findings.
    h. "Methodology": brief description of data source, segment definitions, churn definition.

24. Use static charts (matplotlib/seaborn for Python or ggplot2 for R).
25. Save the report and intermediary file with descriptive filenames like "copilot_segmentation_churn_YYYYMMDD.html".

IMPORTANT NOTES
- Segments are assigned by `identify_usage_segments()` based on both usage volume and consistency (habit formation over 12 weeks). Print the segment definitions used so the reader can interpret them.
- Use at least 10 distinct people for dashboard or joined-query breakdowns, or the stricter organisational minimum. Suppress complementary cells.
- Build transitions only for users observed in both consecutive weeks.
- If the dataset has fewer than 8 weeks, note that churn analysis may not be reliable; do not silently change the churn definition.

<!-- analysis-policy:start -->
Use product-specific licence evidence. For documented native licensed-only M365 Copilot metrics, null means unlicensed and zero activity means licensed but inactive. Prefer Copilot Enabled User or Total Copilot enabled days. Do not extend these semantics to unlicensed Copilot Chat or Consumption credits.
Investigate conflicting licence evidence. Keep affected eligibility or activity unresolved, and withhold affected rates or estimates until resolved.
Within a supplied complete query's configured scope, absent activity rows contribute zero. Keep failed joins, unavailable sources, out-of-scope periods and known coverage failures unresolved with reasons.
Use configured grouping, week start and metric windows; date gaps do not establish cadence. State grain, units and estimand. Count distinct people; do not sum stocks or overlapping windows.
Use max(organisation requirement, workflow floor): 5 distinct people for general analysis and 10 for joined-query, dashboard, causal or process workflows. Protect complementary cells and embedded data; never publish individual rankings.
Use only HR attributes present in the export. If none suit a requested breakdown, omit it, explain why, and continue with supported overall results.
Treat low-activity flags as review candidates, not verified holidays, employment status or job classifications. Value scenarios require explicit conversion and realisation assumptions.
Default to association. Make causal claims only with a supported design and compatible estimators. Record unavailable checks and label synthetic data.
Check installed API versions, signatures and return types. Separate executed results from expectations and do not silently fork upstream bugs.
<!-- analysis-policy:end -->

Adaptation notes

• The identify_usage_segments() function provides default thresholds. If the segments do not produce meaningful groupings for your data, consult its documentation for customization parameters and report any changes.
• If your organization has a specific definition of “churn” (e.g., 4 weeks of inactivity instead of 2), modify the churn definition in step 15.
• For organizations with multiple Copilot products, consider segmenting by product (e.g., Copilot in Teams vs. Copilot in Word) by using product-specific metrics.
• Add a “New User” segment by tracking each user’s first active week and analyzing the onboarding trajectory separately.
• If you want to predict future churn, add a note requesting a logistic regression or survival analysis model.

Common failure modes

• Agent uses rolling segments as weekly activity. A user may remain Habitual after two inactive weeks. Compute the churn flag from observed weekly activity instead.
• Agent treats missing or unlicensed weeks as inactive. Only a confirmed licensed week with known zero activity is inactive for churn.
• Transition matrix includes users who appear in only one week. Ensure the matrix only counts users present in both the “from” and “to” weeks.
• Agent conflates week-level segments with user-level segments. The report uses both: per-week segments for trends and a “stable segment” (mode) for HR attribute breakdowns. Ensure both are present.
• Churn definition is too aggressive. Two weeks of inactivity may include holidays or vacation. Consider extending to 3–4 weeks for more conservative churn estimates.

🔒 Responsible use & data privacy

• Suppress small groups. Apply the stricter of your organisation's minimum group size and the selected workflow's privacy floor to every breakdown, segment and chart.
• Never expose individuals. Do not print raw UPNs or email addresses. Hash, truncate or report only aggregates. Person Query PersonId is already de-identified, but Purview UserId is not.
• Report group patterns. Use these outputs to understand cohorts and trends. Do not evaluate, rank or monitor named employees.
• Keep data in approved environments. Follow your organisation's policies when choosing an agent and deciding which data it may access. Validate every agent output before sharing.

← Previous: Executive Summary Next: ROI Estimation →