# Analyze Customer Feedback

> analyzes customer feedback across Email, GitHub, NPS, and churn cancellations.

- Skill: `warpdotdev/analyze-customer-feedback` (Agent Skill, multi-file: 8 files)
- Install (CLI): `npx skillmds@latest add warpdotdev/analyze-customer-feedback`
- Raw SKILL.md: https://api.skillmd.com/api/skills/warpdotdev/analyze-customer-feedback/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: warpdotdev (https://skillmd.com/u/warpdotdev)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/warpdotdev/analyze-customer-feedback

---


# Customer Feedback Analysis Skill

Use this skill to analyze and summarize customer feedback from multiple sources over the last 7 days (or a custom time period). The skill fetches raw data from GitHub issues, NPS survey responses, email feedback, and subscription cancellation comments for you to analyze.

**Important:** For all tasks in this skill, use `METABASE_API_KEY` from the environment for NPS data (Metabase API) and `GOOGLE_OAUTH_TOKEN` for Gmail.

## Instructions for the Agent

This skill fetches raw feedback data. You (the agent) are responsible for organizing it into a factual report. Your job is to identify themes, count their frequency, and cite specific sources. Do NOT editorialize, speculate on root causes, assign severity/priority, or make recommendations.

1. **Filter out noise** — Ignore feedback that is not substantive:
   - Auto-reply/out-of-office messages (e.g., "自动回复", "This is an automated response")
   - Spam or promotional content
   - Internal test messages
   - Bounce-back emails
   - Generic "thank you" acknowledgments without substance

2. **Identify themes** — Scan all four channels (GitHub issues, NPS comments, emails, churn cancellations) and group feedback items that describe the same topic into themes. A theme is any topic mentioned by 2+ users or across 2+ channels. Single-mention items should be listed under "Other" at the end.

3. **Count frequency** — For each theme, report:
   - Total number of mentions across all channels
   - Breakdown by channel (e.g., "3 GitHub issues, 2 NPS comments, 1 email")
   - Order themes by total mention count, highest first

4. **Cite sources** — For every item in a theme:
   - GitHub issues: include issue number as a link (e.g., `[#123](https://github.com/YOUR_ORG/YOUR_REPO/issues/123)`) and the issue title
   - NPS comments: quote the comment verbatim and include the score
   - Emails: include the sender name and a brief description of the content
   - Churn cancellations: quote the comment verbatim and include the plan type, e.g., `Cancellation (build): "[verbatim quote]"`

5. **Note cross-channel convergence** — When a theme appears in 2+ channels, state that as a fact (e.g., "This theme appeared in 3 GitHub issues and 2 NPS detractor comments"). Do not interpret what the convergence means.

6. **Track week-over-week changes** — Read the most recent previous report from `reports/customer_feedback_summaries/` and compare:
   - Which themes are new (not in the previous report)
   - Which themes from the previous report recurred (with updated counts)
   - Which themes from the previous report did not recur
   - Report counts only. Do not use trend arrows, severity labels, or words like "improving," "worsening," or "resolved."

7. **Format your report** — Structure your output as described in the Output Format section below. Do not add sections beyond what is specified. Do not use emoji severity markers (🔴🟡🟢). Do not include sections titled "Recommended Actions," "Risks," "Open Questions," "Interpretation," or "Key Insight."

## When to Use

Use this skill when you need to:
- Get a weekly summary of customer feedback
- Identify trending issues or complaints
- Track NPS scores and sentiment over time
- Understand why users are canceling subscriptions
- Prepare for product reviews or planning sessions
- Understand customer pain points across multiple channels

## Data Sources

1. **GitHub Issues** (YOUR_ORG/YOUR_REPO) - Bug reports and feature requests from public users
2. **NPS Survey Responses** (Metabase API) - Net Promoter Score data with user comments
3. **Email Feedback** (Gmail) - Emails sent to your feedback address (set `FEEDBACK_EMAIL`)
4. **Subscription Cancellations** (Metabase API) - Cancellation comments from `prod.your_subscriptions_table`, grouped by plan type. Uses the same `METABASE_API_KEY` as NPS.

## Prerequisites

### 1. GitHub CLI
The `gh` CLI must be authenticated with access to `YOUR_ORG/YOUR_REPO`.

```bash
# Check authentication status
gh auth status

# Login if needed
gh auth login
```

### 2. Metabase API (for NPS data)

The `METABASE_API_KEY` environment variable should be set in your ennvironment.

The script queries `your-gcp-project-id.prod.your_nps_survey_responses_table` via the Metabase API at `https://your-metabase-instance.metabaseapp.com`.

### 3. Gmail API

Gmail uses `GOOGLE_OAUTH_TOKEN`. The token needs `gmail.readonly` scope.

### 4. Install Dependencies

```bash
pip install -r requirements.txt
```

Note: The NPS fetcher uses only Python standard library (`urllib.request`), so no additional packages are needed for NPS data.

## Usage

### Basic Usage (analyze last 7 days)

```bash
cd skills/analyze_customer_feedback
python analyze_feedback.py
```

### Custom Time Period

```bash
python analyze_feedback.py --days 14    # Last 14 days
python analyze_feedback.py --days 30    # Last 30 days
```

### JSON Output (for programmatic use)

```bash
python analyze_feedback.py --json
```

### Skip Sources (if not configured)

```bash
python analyze_feedback.py --skip-gmail     # Skip Gmail if not set up
python analyze_feedback.py --skip-nps       # Skip NPS if BigQuery not configured
python analyze_feedback.py --skip-github    # Skip GitHub issues
python analyze_feedback.py --skip-churn     # Skip churn cancellation comments
```

### Run Individual Fetchers

```bash
# GitHub issues only
python fetch_github_issues.py --days 7 --json

# NPS data only
python fetch_nps_data.py --days 7 --json

# Gmail feedback only
python fetch_gmail_feedback.py --days 7 --json

# Churn cancellations only
python fetch_churn_data.py --days 7 --json
```

## Script Output

The script outputs raw feedback data in a structured format:

1. **Summary** - Counts of feedback items from each source
2. **GitHub Issues** - Full issue data (title, body, labels, comments, URL)
3. **NPS Comments** - Score, OS, date, and verbatim comment for responses that included a comment
4. **Email Feedback** - Subject, sender, date, and full content
5. **Churn Cancellation Comments** - Plan type and verbatim cancellation comment, grouped by plan type

You (the agent) should organize this data into the report format below.

## Report Output Format

Your report must follow this structure exactly. Do not add extra sections.

```
# Customer Feedback Report — [Date Range]

**Period:** [time period]
**Generated:** [date]

---

## Summary

- GitHub issues filed: [N]
- NPS responses with comments: [N] out of [N] total
- Emails received: [N] ([N] after filtering noise)
- Churn cancellations with comments: [N]

---

## Themes (ordered by total mention count)

### 1. [Theme Name] — [N] mentions
**Channels:** [N] GitHub issues, [N] NPS comments, [N] emails
**Previous report:** [Yes — N mentions / No]

- [#NNNN](link): [issue title] ([N] comments)
- [#NNNN](link): [issue title]
- NPS (score [N]): "[verbatim quote]"
- Email from [sender]: [brief description]
- Cancellation ([plan_type]): "[verbatim quote]"

### 2. [Theme Name] — [N] mentions
...

### Other (single-mention items)
- [#NNNN](link): [issue title]
- NPS (score [N]): "[verbatim quote]"
- ...

---

## NPS Comments

List all NPS responses that included a written comment, grouped by score band. Only include responses with non-empty comments. Include the score for context but do not calculate or report the NPS score itself.

### Scores 9-10
- (Score [N]): "[verbatim quote]"
- (Score [N]): "[verbatim quote]"

### Scores 7-8
- (Score [N]): "[verbatim quote]"

### Scores 0-6
- (Score [N]): "[verbatim quote]"
- (Score [N]): "[verbatim quote]"

---

## Churn Cancellation Comments

List all cancellation comments, grouped by plan type. Include only subscriptions canceled in the reporting period that have a non-empty comment.

### [plan_type] ([N] cancellations)
- "[verbatim quote]"
- "[verbatim quote]"

### [plan_type] ([N] cancellations)
- "[verbatim quote]"

---

## Email Summary

[N] emails received. [N] after filtering auto-replies, spam, and non-substantive messages.

1. **[sender name]** — [brief factual description of content]
2. **[sender name]** — [brief factual description of content]
...

---

## Week-over-Week

### New themes (not in previous report)
- [Theme Name] — [N] mentions
- [Theme Name] — [N] mentions

### Recurring themes (also in previous report)
- [Theme Name] — [N] mentions this week, [N] last week
- [Theme Name] — [N] mentions this week, [N] last week

### Themes from previous report that did not recur
- [Theme Name] — [N] mentions last week, 0 this week
```

## Integration with Other Skills

After generating the report, you can:

## Troubleshooting

### Metabase API Errors
```bash
# Verify METABASE_API_KEY is set
echo $METABASE_API_KEY | head -c 10

# Test the API connection
curl -s -w "\nHTTP_CODE:%{http_code}" -H "x-api-key: $METABASE_API_KEY" "https://your-metabase-instance.metabaseapp.com/api/user/current"
```

### GitHub CLI Errors
```bash
# Check token scopes
gh auth status

# Re-authenticate with required scopes
gh auth login --scopes read:org,repo
```

## Example Script Output

The script outputs raw structured data like this (you then organize it into the Report Output Format above):

```markdown
# Customer Feedback Data
**Period:** Last 7 days
**Generated:** 2026-02-02 17:30 UTC

## Summary
- GitHub Issues: 23
- NPS Responses: 89
- Email Feedback: 30
- Churn Cancellations: 144

## GitHub Issues
### #21234: Agent mode freezes on large files
- **URL:** https://github.com/YOUR_ORG/YOUR_REPO/issues/21234
- **State:** open
- **Created:** 2026-02-01T10:30:00Z
- **Comments:** 8
- **Labels:** bug, agent-mode
- **Body:**
```
When I open a file larger than 10MB, the agent freezes...
```

## NPS Survey Responses
### Score: 10
- **OS:** macOS
- **Date:** 2026-02-01
- **Comment:** Love the new agent mode! Makes coding so much faster.

### Score: 4
- **OS:** Windows
- **Date:** 2026-02-01
- **Comment:** SSH keeps disconnecting after a few minutes.
...

## Churn Cancellation Comments
144 cancellations with comments.

### build (72 cancellations)
- [example comment about usage frequency vs. cost]
- [example comment about switching to another tool]
...

### pro (48 cancellations)
- [example comment about pricing vs. feature usage]
...
```

## Notes

- The script outputs progress to stderr and the data to stdout, allowing easy piping
- Full feedback comments are displayed without truncation for complete context
- The Gmail module filters for emails to/from the address in `FEEDBACK_EMAIL`