<!--
  BRIEF template = the shared header + table sections, ending at 'Trend Analysis'.
  The shared header/tables below are identical to report_template_detailed.md (lines 7-41).
  Keep them in sync; for the canonical full layout, see report_template_detailed.md.
-->
# GitHub Trending Report - {date}

> Generated: {date}
> Source: github.com/trending?since={since}
> Baseline: {baseline_date}

## 🔥 New Entries

| Rank | Project | Language | ⭐ Stars | 📈 Today | One-liner |
|------|---------|----------|---------|---------|-----------|
| 1 | [org/repo](url) | Python | 12.3k | +500 | What it does |

## ⭐ Sustained Hot

| Project | Language | ⭐ Stars | 📈 Today | Why notable |
|---------|----------|---------|---------|-------------|
| [org/repo](url) | Go | 8.5k | +300 | What makes it special |

## 📉 Dropped Off

| Project | What it might mean |
|---------|-------------------|
| org/repo | Hype cycle cooling |

## 🎯 Theme Breakdown

**🤖 AI/LLM** (5 projects): org/repo1(+600), org/repo2(+450), ...

**🛠️ Dev Tools** (3 projects): org/tool1(+200), org/tool2(+150), ...

## 💡 Trend Analysis

{trend_insight_paragraph}

Current wave: {dominant_theme} projects surge due to {driver}. Notable shift from {previous_trend}.

<!--
  Boundary marker: brief mode ends here. Do not append per-project
  blocks; for the detailed mode use report_template_detailed.md.
-->

<!--
  Detailed report = the full brief report (report_template_brief.md,
  through "Trend Analysis") FOLLOWED BY the per-project blocks below.
  Do NOT emit the detailed blocks without the brief header above them.
-->

# GitHub Trending Report - {date}

> Generated: {date}
> Source: github.com/trending?since={since}
> Baseline: {baseline_date}

## 🔥 New Entries

| Rank | Project | Language | ⭐ Stars | 📈 Today | One-liner |
|------|---------|----------|---------|---------|-----------|
| 1 | [org/repo](url) | Python | 12.3k | +500 | What it does |

## ⭐ Sustained Hot

| Project | Language | ⭐ Stars | 📈 Today | Why notable |
|---------|----------|---------|---------|-------------|
| [org/repo](url) | Go | 8.5k | +300 | What makes it special |

## 📉 Dropped Off

| Project | What it might mean |
|---------|-------------------|
| org/repo | Hype cycle cooling |

## 🎯 Theme Breakdown

**🤖 AI/LLM** (5 projects): org/repo1(+600), org/repo2(+450), ...

**🛠️ Dev Tools** (3 projects): org/tool1(+200), org/tool2(+150), ...

## 💡 Trend Analysis

{trend_insight_paragraph}

Current wave: {dominant_theme} projects surge due to {driver}. Notable shift from {previous_trend}.

---

## 📋 Project Details

### {Project Name}

**Stars**: {total_stars} (+{today_increment})
**Language**: {primary_language}
**URL**: {github_url}

#### 这是什么
{what_description}

#### 生活化类比
{analogy_sentence}

#### 它能帮你做什么
1. {help_point_1}
2. {help_point_2}
3. {help_point_3}

#### 谁需要它
{who_description}

---

<!-- Repeat the block above for each project. In deep mode, help may
     carry 3 items; otherwise use the first 2. Field labels stay Chinese
     to match the SKILL.md 4-field analysis schema (what/analogy/help/who). -->

---
name: github-trending-analyzer
description: Crawl GitHub trending repositories, analyze with LLM for Chinese insights, categorize by themes, compute diffs against history, and generate Markdown reports. Default brief mode stops at trend analysis; optional detailed mode appends per-project analysis. Supports incremental gap-filling and selective re-analysis with caching.
---

# GitHub Trending Analyzer

A workflow protocol for tracking GitHub trending repositories with LLM-powered analysis. Fetches trending projects, enriches each with structured Chinese insights (what/analogy/help/who), classifies by themes, compares against historical snapshots, and generates reports in two modes — a compact brief (default) or a detailed report with per-project analysis (opt-in).

## Trigger Signals

- GitHub trending analysis
- Weekly tech trend report
- Repository discovery automation
- Incremental analysis refresh
- Theme-based repo categorization

## Preconditions

- HTTP access to github.com/trending (no auth required for public trending)
- LLM backend capable of JSON-structured output (for the 4-field analysis schema)
- File system access for memory cache and report output
- HTML parsing capability (regex or DOM parser)

## Strategy

Run the five-step pipeline in order.

### Step 1: Fetch trending HTML

Construct the URL with time range and optional language filter:
```
https://github.com/trending[/{language}]?since={daily|weekly|monthly}
```

Fetch with a browser User-Agent to avoid bot detection. Parse the HTML to extract:
- `name` (org/repo)
- `url` (full GitHub link)
- `desc` (one-line description from the page)
- `lang` (primary language)
- `stars` (total stargazers count)
- `today_stars` (increment for this period)

**Regex patterns** (reference from source):
- Project name: `<h2[^>]*>.*?<a href="/([^"]+)"`
- Description: `<p class="[^"]*col-9[^"]*"[^>]*>\s*(.*?)\s*</p>`
- Language: `<span itemprop="programmingLanguage">([^<]+)</span>`
- Stars: parse from `/stargazers` link text after stripping HTML tags
- Today increment: `([\d,]+)\s*stars?\s*(?:this|today)` (case-insensitive)

### Step 2: Batch LLM analysis

For each batch of 5 projects (to avoid token limits), send this prompt to your LLM:

```
Analyze the following {N} GitHub Trending projects. Output strict JSON array.
Each project needs 4 fields:
- what: What it is (≤30 Chinese characters)
- analogy: Life analogy (one sentence)
- help: What it helps you do (2 items, each ≤40 chars, array)
- who: Who needs it (one sentence, ≤30 chars)

Project list:
1. org/repo (Language) — description...
2. ...

Output ONLY the JSON array, no other text. Example:
[{"name":"org/repo","what":"...","analogy":"...","help":["...","..."],"who":"..."}]
```

**Parse the response**:
1. Strip markdown code fences (` ```json ` / ` ``` `)
2. Clean trailing commas: `,\s*([\]}])` → `\1`
3. Extract the JSON array via regex: `\[.*\]` (DOTALL)
4. Decode with `json.loads()` or equivalent
5. Match results back to projects by name suffix (case-insensitive)

**Fallback**: If array parsing fails, extract individual objects via bracket-counting and parse one by one.

**Deep mode** (optional): Use longer limits (what ≤50 chars, help 3 items) for richer analysis.

### Step 3: Theme classification

Load the bundled `theme_rules.json`. For each project:
1. Concatenate `name + " " + desc` and lowercase
2. Iterate themes by priority order
3. Check if any keyword from the theme appears in the text
4. Assign to first matching theme
5. Default to "🌐 其他" if no match

Result: `{theme_name: [projects...]}` dictionary.

### Step 4: Compute diff (optional)

Load `memory.json` from the workspace root (see Output Protocol). Schema:
```json
[
  {
    "date": "2026-06-19",
    "since": "weekly",
    "lang": "python",
    "repos": [{"name":"...", "url":"...", "desc":"...", "lang":"...", "stars":..., "today_stars":..., "analysis":{...}}]
  }
]
```

Compare current repos against the latest entry with the same `since` (and same `lang` filter):
- **new**: projects in current but not in last
- **hot**: projects in both
- **dropped**: projects in last but not in current
- **last_date**: baseline timestamp

### Step 5: Generate reports

Two report modes, driven by the bundled templates:

- **Brief (default)**: `report_template_brief.md` — stops at "💡 Trend Analysis". Always emitted.
- **Detailed (opt-in)**: `report_template_detailed.md` — the brief content plus a per-project "📋 Project Details" section with the 4-field analysis. Emitted only when the user asks for detail (or when `deep` analysis was run).

**Trend insight prompt** (used in the "Trend Analysis" section of both modes):
```
基于以下GitHub Trending项目摘要，用3-5句话分析当前最强技术趋势和驱动力：
{list of "name: what" for all projects}
```

Save under `reports/YYYY-MM-DD/` with a `{since}` suffix (`daily` / `weekly` / `monthly`), e.g. `trending_briefing_weekly.md`. Same-day re-runs of the same `since`+`lang` overwrite that report.

**Empty tables**: when a section (new/hot/dropped) has no rows, render the table header followed by a single `*none*` row; keep "Theme Breakdown" and "Trend Analysis" only if there are classified projects. On a first run (no memory baseline), omit the "Dropped Off" section rather than showing it empty.

## Constraints

### Core rules

1. **Batch size = 5** for LLM calls to avoid truncation. For 20 repos, make 4 separate calls.
2. **JSON-only LLM output**. The prompt explicitly forbids explanatory text. Parse defensively (strip fences, clean commas).
3. **Name matching is fuzzy**. Match by suffix (`org/repo` vs `repo`) and case-insensitive substring.
4. **Theme priority matters**. A project matching both "AI" and "Dev Tools" gets classified as "AI" (priority 1 < 4).
5. **Memory and daily repo JSON are upserted, not blindly overwritten or appended.** Key is `(date, since, lang)`. Same-key re-runs merge; other keys are added. Retain the 30 most recent distinct dates.

### Incremental modes (optional)

- **Gap-fill mode**: Load the matching memory entry (same `date`+`since`+`lang`, else latest with same `since`+`lang`) → detect repos without `analysis` → re-run LLM only for those → merge back into both `memory.json` and `repos/YYYY-MM-DD_repos.json` → regenerate reports.
- **Selective re-analysis**: User specifies project names (comma-separated, partial match) → find matching repos in memory → re-run LLM with optional deep mode → merge into memory and the day's repos JSON → regenerate reports.

Implementation hint: `detect_gaps(repos)` returns `[r for r in repos if not r.get('analysis')]`.

### Error handling

- **HTML fetch fails**: Retry once with 5s delay, then abort with clear error message.
- **LLM returns non-JSON**: Log warning, continue with raw description as fallback for that batch.
- **Memory file missing**: Treat as first run (no diff section in reports).

## Output Protocol

Write all artifacts under the **current working directory** (the consuming workspace). Never write into the skill package.

```
<cwd>/
├── repos/YYYY-MM-DD_repos.json
├── reports/YYYY-MM-DD/trending_briefing_{since}[_{lang}].md
├── reports/YYYY-MM-DD/trending_detailed_{since}[_{lang}].md   # opt-in
└── memory.json
```

`{since}` is `daily` | `weekly` | `monthly`. Append `_{lang}` only when a language filter was used (`python`, `go`, …). Date lives in the reports folder — do not repeat it in the report filename.

Create `repos/` and `reports/YYYY-MM-DD/` if missing. Same-day re-runs of the same `since`+`lang` overwrite that report file.

### `repos/YYYY-MM-DD_repos.json`

Day-level crawl cache. Incremental merge on every run:

```json
{
  "date": "2026-08-19",
  "updated_at": "2026-08-19T16:45:00+08:00",
  "snapshots": [
    {
      "since": "daily",
      "lang": "",
      "fetched_at": "2026-08-19T16:45:00+08:00",
      "repos": [{"name":"...","url":"...","desc":"...","lang":"...","stars":0,"today_stars":0,"analysis":{}}]
    }
  ]
}
```

Merge rules:
1. Load the file if it exists; otherwise start `{date, updated_at, snapshots: []}`.
2. Upsert the snapshot whose `(since, lang)` matches this run (`lang` is `""` when unfiltered).
3. Matching repos (case-insensitive `name`): overwrite crawl fields (`url`, `desc`, `lang`, `stars`, `today_stars`); keep existing `analysis` unless this run produced a new one.
4. Repos only in the new fetch are appended; repos only in the old snapshot are kept (a later `since` on the same day must not wipe another window).
5. Write atomically (temp file in the same directory, then replace).

### `memory.json`

Workspace-root history used by Step 4 diffs and gap-fill. Incremental merge:

1. Load the array if the file exists; missing or empty → first run (no diff / no Dropped Off).
2. Upsert by `(date, since, lang)`. Same key: apply the same per-repo merge as the day cache. New key: append.
3. After upsert, keep entries whose `date` is among the 30 most recent distinct dates (so one day with daily+weekly+monthly does not evict history).
4. Write atomically.

### Reports

1. **Brief (default)** (`reports/{date}/trending_briefing_{since}[_{lang}].md`): new/hot/dropped/themes + trend insight. Stops at "Trend Analysis" — no per-project blocks.
2. **Detailed (opt-in)** (`reports/{date}/trending_detailed_{since}[_{lang}].md`): brief content followed by one "📋 Project Details" block per project with the 4-field analysis. Only when the user requests detail.

**Console output** during execution:
- "Fetching {since} trending..." → "Got {N} projects"
- "LLM batch {i}/{total}..." → "✅ Batch complete: {n} items"
- "💾 Repos merged: {path}"
- "💾 Memory merged: {path}"
- "📄 Brief saved: {path}"
- "📄 Detailed saved: {path}" (only when detailed mode runs)
- (Gap-fill) "Coverage: {covered}/{total} ({pct}%)"

## Validation

Before emitting reports, confirm:

- All repos have `name`, `url`, `desc`, `lang`, `stars`, `today_stars` fields.
- At least one theme contains projects (not all "其他").
- LLM analysis covers ≥50% of projects (log warning if lower).
- Emitted report files are valid UTF-8 Markdown at the paths above.
- `YYYY-MM-DD_repos.json` and `memory.json` reload without error after the merge.

## Adapting and Extending

### Custom themes

Edit the bundled `theme_rules.json`:
- Add new themes with emoji prefix and priority
- Extend keyword lists for existing themes
- Adjust priority order to prefer certain classifications

### Alternative LLM schemas

The 4-field schema (what/analogy/help/who) is optimized for Chinese tech audiences. Adapt for other contexts:
- **English reports**: Change field names and prompt language
- **Different insights**: Replace "analogy" with "use cases" or "risks"
- **Richer detail**: Increase char limits in deep mode

### Different trending sources

The HTML parsing patterns are GitHub-specific. To adapt for other platforms (Hacker News, Product Hunt):
- Replace Step 1 fetch logic
- Adjust regex patterns for that site's DOM structure
- Keep Steps 2-5 unchanged (LLM + themes + diff + reports)

### Memory backends

The reference uses local JSON. For multi-agent or cloud deployments:
- Swap `load_memory()` / `save_memory()` with a DB or object storage client
- Maintain the same list-of-dicts schema
- Add concurrency locks if multiple agents run in parallel

{
  "themes": {
    "🤖 AI/LLM": {
      "priority": 1,
      "keywords": [
        "ai", "llm", "gpt", "agent", "rag", "embedding", "model", "ml",
        "deep learning", "transformer", "inference", "token", "prompt",
        "voice", "tts", "vtuber", "lmm", "chatbot", "neural", "openai"
      ]
    },
    "📊 数据/分析": {
      "priority": 2,
      "keywords": [
        "data", "sql", "database", "analytics", "dashboard", "chart",
        "visuali", "jupyter", "notebook", "trading", "finance", "etl",
        "warehouse", "pipeline", "postgres", "mysql", "redis"
      ]
    },
    "🔒 安全": {
      "priority": 3,
      "keywords": [
        "security", "vuln", "hack", "pentest", "encrypt", "auth",
        "firewall", "exploit", "malware", "password", "cert", "ssl",
        "tls", "zero-trust", "sso", "oauth"
      ]
    },
    "🛠️ 开发工具": {
      "priority": 4,
      "keywords": [
        "cli", "terminal", "editor", "vscode", "git", "debug", "lint",
        "format", "build", "deploy", "ci", "cd", "scrape", "crawl",
        "convert", "markdown", "devtool", "compiler", "bundler"
      ]
    },
    "🎮 前端/UI": {
      "priority": 5,
      "keywords": [
        "ui", "react", "vue", "css", "tailwind", "component", "web",
        "frontend", "app", "svelte", "angular", "nextjs", "responsive",
        "animation", "theme", "design system"
      ]
    },
    "📚 教育/学习": {
      "priority": 6,
      "keywords": [
        "course", "learn", "tutorial", "education", "book", "awesome",
        "guide", "roadmap", "interview", "example", "study", "practice"
      ]
    },
    "☁️ 基础设施": {
      "priority": 7,
      "keywords": [
        "kubernetes", "docker", "cloud", "server", "infra", "monitor",
        "deploy", "aws", "k8s", "container", "orchestration", "terraform",
        "ansible", "prometheus", "grafana", "nginx"
      ]
    },
    "🌐 其他": {
      "priority": 99,
      "keywords": []
    }
  },
  "classification_rules": [
    "Match project name and description against keywords (case-insensitive)",
    "First matching theme by priority wins",
    "If no match, assign to '🌐 其他'"
  ]
}