email-intelligence

通过天气隐喻、垃圾邮件/信号分类、电子邮件债务评分和幽灵检测来分析电子邮件收件箱的健康状况。当用户询问收件箱状态、电子邮件过多、他们的幽灵是谁或电子邮件时间成本时使用。需要使用 IMAP 配置的喜马拉雅 CLI。

# Email Intelligence

Analyze your email inbox health using creative weather metaphors, intelligent classification, debt scoring, and ghost detection. Transform overwhelming inbox analysis into clear, actionable insights.

## When to Use

Use this skill when the user asks about:
- Inbox status or health
- Email overwhelm or management
- Who they're "ghosting" (ignoring responses to)
- Time cost of processing their inbox
- Signal vs noise in their email
- Email debt or backlog

## Requirements

- **himalaya CLI** configured with IMAP access
- Python 3.6+
- The configured email account should have standard folder names (INBOX, Archive)

## Quick Usage

```bash
# Basic analysis (last 7 days)
python3 scripts/email_classify.py

# Extended analysis (last 14 days)
python3 scripts/email_classify.py --days 14

# JSON output for integration
python3 scripts/email_classify.py --format json
```

## Weather System

The inbox "weather" is determined by the number of human emails in your INBOX that need responses:

- **🌊 Calm Seas** (0-2): Inbox is peaceful and manageable
- **🍃 Light Breeze** (3-5): A few emails need attention, nothing urgent
- **🌬️ Choppy Waters** (6-10): Multiple emails require responses  
- **⛵ Small Craft Advisory** (11-20): Many people waiting for replies
- **⛈️ Storm Warning** (21+): Inbox is overwhelming, needs immediate attention

## Email Classification

Emails are automatically classified into four categories:

### 🤖 Automated
- Sender contains: noreply, no-reply, donotreply, notifications@, alerts@
- Subject contains: unsubscribe, automatic, auto-generated
- Time cost: 0 minutes (can be safely ignored)

### 📰 Newsletter
- From domains: substack.com, email.*, marketing.*, updates@
- Subject contains: newsletter, digest, weekly, monthly, roundup
- Time cost: 1 minute each (skim or archive)

### 🔔 Notification  
- From services: github, slack, jira, linear, aws, google, microsoft, etc.
- Time cost: 30 seconds each (quick action/acknowledgment)

### 👥 Human
- Everything else (actual people writing)
- Time cost: 3 minutes each (requires thoughtful response)

## Metrics Explained

### Email Debt Score (0-100)
Calculated based on unseen human emails in your INBOX, weighted by age:
- < 1 day old: 1 point each
- 1-3 days old: 3 points each  
- 3-7 days old: 5 points each
- 7+ days old: 10 points each

**Score meanings:**
- 0-30: 🟢 Great job! Inbox under control
- 31-60: 🟡 Getting busy. Consider tackling some replies
- 61-100: 🔴 High debt! Many emails waiting for responses

### Signal-to-Noise Ratio
Percentage of emails that are from humans (signal) vs automated/newsletter/notification (noise).

Higher ratio = more meaningful email, less spam/clutter.

### Ghost Report
Shows up to 5 people you're "ghosting" (human emails you haven't read), sorted by how long they've been waiting. Helps prioritize who needs responses most urgently.

### Time Investment
Estimates how much time you'll need to process your current inbox based on email types and their typical processing times.

## Output Formats

### Text Format (Default)
Human-readable report with weather, debt score, signal/noise analysis, ghost report, and time estimates. Perfect for quick status updates or daily reviews.

### JSON Format
Structured data for integration with other tools, APIs, or dashboards:

```json
{
  "weather": {
    "level": "breeze",
    "emoji": "🍃", 
    "description": "Light Breeze - A few emails need attention...",
    "humanCount": 4
  },
  "categories": {
    "automated": 15,
    "newsletter": 8,
    "notification": 12,
    "human": 4
  },
  "debtScore": 18,
  "ghostReport": [...],
  "signalNoiseRatio": {
    "ratio": 0.103,
    "percentage": "10%"
  },
  "timeCost": {
    "minutes": 18,
    "formatted": "18 minutes"
  }
}
```

## Integration Tips

### Dashboard Integration
The JSON output is designed for easy integration into dashboards or status displays. The weather metaphor makes it intuitive for users to understand their inbox state at a glance.

### Automation
Run periodically (via cron) to track inbox health trends over time. The debt score is particularly useful for identifying when inbox maintenance is needed.

### Alerts
Set up alerts when:
- Weather reaches "Storm Warning" level
- Debt score exceeds 60
- Ghost report shows people waiting >5 days

## Troubleshooting

### No emails found
- Verify himalaya CLI is configured: `himalaya envelope list -f INBOX --page-size 1`
- Check folder names match your email provider (some use "Inbox" vs "INBOX")

### Classification seems wrong
The classification uses heuristics based on sender patterns and subject lines. You can modify the patterns in the script for your specific needs.

### Slow performance
- Reduce the `--days` parameter to analyze fewer emails
- The script fetches up to 200 emails from Archive - adjust `page_size` in the code if needed

## Philosophy

Email Intelligence treats your inbox as a living system with its own weather patterns and health metrics. Rather than just counting unread emails, it helps you understand:

- What actually needs your attention (humans vs bots)
- How "behind" you are (debt score)  
- Who you might be accidentally ignoring (ghost report)
- How much time you're really looking at (time cost)

The weather metaphor makes inbox status intuitive and actionable - you know to "batten down the hatches" when a storm is brewing, but you can relax when the seas are calm.

Use this skill to transform inbox anxiety into clear, prioritized action plans.

---

## 中文说明

# Email Intelligence

使用富有创意的天气隐喻、智能分类、债务评分和幽灵检测来分析你的电子邮件收件箱健康状况。将令人不堪重负的收件箱分析转化为清晰、可执行的洞察。

## When to Use（何时使用）

当用户询问以下内容时使用本技能：
- 收件箱状态或健康状况
- 电子邮件过载或管理
- 他们正在“冷落”谁（忽略了谁的回复需求）
- 处理收件箱的时间成本
- 邮件中的信号与噪声
- 电子邮件债务或积压

## Requirements（要求）

- 配置了 IMAP 访问的 **himalaya CLI**
- Python 3.6+
- 配置的电子邮件帐户应使用标准文件夹名称（INBOX、Archive）

## Quick Usage（快速使用）

```bash
# Basic analysis (last 7 days)
python3 scripts/email_classify.py

# Extended analysis (last 14 days)
python3 scripts/email_classify.py --days 14

# JSON output for integration
python3 scripts/email_classify.py --format json
```

## Weather System（天气系统）

收件箱“天气”由你 INBOX 中需要回复的真人邮件数量决定：

- **🌊 Calm Seas（风平浪静）**（0-2）：收件箱平静且易于管理
- **🍃 Light Breeze（微风轻拂）**（3-5）：有几封邮件需要关注，但不紧急
- **🌬️ Choppy Waters（波涛起伏）**（6-10）：多封邮件需要回复
- **⛵ Small Craft Advisory（小型船只警示）**（11-20）：许多人在等待回复
- **⛈️ Storm Warning（暴风预警）**（21+）：收件箱不堪重负，需立即处理

## Email Classification（邮件分类）

邮件会被自动分为四类：

### 🤖 Automated（自动化）
- 发件人包含：noreply、no-reply、donotreply、notifications@、alerts@
- 主题包含：unsubscribe、automatic、auto-generated
- 时间成本：0 分钟（可安全忽略）

### 📰 Newsletter（资讯简报）
- 来自域名：substack.com、email.*、marketing.*、updates@
- 主题包含：newsletter、digest、weekly、monthly、roundup
- 时间成本：每封 1 分钟（略读或归档）

### 🔔 Notification（通知）
- 来自服务：github、slack、jira、linear、aws、google、microsoft 等
- 时间成本：每封 30 秒（快速操作/确认）

### 👥 Human（真人）
- 其余所有（实际有人在写信）
- 时间成本：每封 3 分钟（需要深思熟虑的回复）

## Metrics Explained（指标说明）

### Email Debt Score（电子邮件债务评分，0-100）
根据你 INBOX 中未读的真人邮件计算，并按时间长短加权：
- 不足 1 天：每封 1 分
- 1-3 天：每封 3 分
- 3-7 天：每封 5 分
- 7 天以上：每封 10 分

**评分含义：**
- 0-30：🟢 干得漂亮！收件箱尽在掌控
- 31-60：🟡 开始忙碌。考虑处理一些回复
- 61-100：🔴 高债务！许多邮件正在等待回复

### Signal-to-Noise Ratio（信噪比）
来自真人（信号）的邮件占自动化/简报/通知（噪声）的百分比。

比例越高 = 越有意义的邮件，越少垃圾/杂乱。

### Ghost Report（幽灵报告）
显示最多 5 位你正在“冷落”的人（你尚未阅读的真人邮件），按等待时长排序。帮助优先确定最急需回复的对象。

### Time Investment（时间投入）
根据邮件类型及其典型处理时间，估算你处理当前收件箱所需的时间。

## Output Formats（输出格式）

### Text Format（文本格式，默认）
人类可读的报告，包含天气、债务评分、信噪比分析、幽灵报告和时间估算。适合快速状态更新或每日回顾。

### JSON Format（JSON 格式）
用于与其他工具、API 或仪表板集成的结构化数据：

```json
{
  "weather": {
    "level": "breeze",
    "emoji": "🍃", 
    "description": "Light Breeze - A few emails need attention...",
    "humanCount": 4
  },
  "categories": {
    "automated": 15,
    "newsletter": 8,
    "notification": 12,
    "human": 4
  },
  "debtScore": 18,
  "ghostReport": [...],
  "signalNoiseRatio": {
    "ratio": 0.103,
    "percentage": "10%"
  },
  "timeCost": {
    "minutes": 18,
    "formatted": "18 minutes"
  }
}
```

## Integra