# Ranking Page Design

## Philosophy

Investibook is a powerful platform, but capability alone doesn't guarantee good outcomes — users need to know *what's available and how to use it well*. The Ranking page addresses this gap.

The core insight: **don't rank users, rank tools and techniques**. A leaderboard that surfaces the most effective skills, the most reliable tools, and the most successful workflows acts as a passive, judgment-free guide. When a user opens this page, they aren't being evaluated — they're being shown what works.

This matters because:
- Users may not know a skill exists that directly solves their problem
- Even if they know a tool exists, they may not know the most effective invocation pattern
- Seeing "this technique was used 500 times this week with a 94% success rate" creates trust and lowers the activation barrier to trying something new

The north star: **help every user use the platform at the level of the best users**, without requiring mentorship or documentation spelunking.

## Overview

The Ranking page provides a curated, **tool/skill-oriented leaderboard** that helps users discover the most effective diagnostic techniques, popular skills, and recommended workflows. The focus is on **surfacing useful capabilities** rather than ranking individual users.

Inspired by OpenRouter's model ranking UI, the page uses a clean card/table layout with weekly trend data and usage statistics.

## Navigation Changes

- **Homepage top-right**: Add a "Rankings" navigation link beside the user avatar
- **User dropdown**: Consolidate "Settings" and "Sign out" into a dropdown menu triggered by clicking the user avatar/email area
- **Ranking page**: Accessible at `/ranking`

## Page Sections

Each section answers a different question a user might have when they don't know where to start or suspect they're not getting the most out of the platform.

### 1. Hero — Weekly Usage Trends (Stacked Bar Chart)

> *"What's the platform doing this week?"* — gives newcomers a live pulse and shows which skills are in active use.

| Field | Description | Source |
|-------|-------------|--------|
| Time-series data | Weekly aggregated usage of top skills/tools across all users | Backend: `chat_events` table aggregation |
| Skill categories | Color-coded by skill name | Backend: skill metadata |

**Mock phase**: Hardcoded 12-week trend data for 8 skills.

### 2. 🏆 Skill Leaderboard

> *"Which skills should I actually use?"* — a ranked view of the most-invoked skills, helping users discover capabilities they may not know exist.

A ranked list (top 10) of the most-used AI diagnostic skills, ordered by total invocations this week.

| Column | Description | Source |
|--------|-------------|--------|
| Rank | 1–10 position | Computed |
| Icon + Name | Skill display name | `nutshell-skills/skills/*/SKILL.md` metadata |
| Provider | Skill author/category (e.g. "TiDB Cloud", "O11Y") | Skill metadata |
| Weekly tokens/calls | Number of invocations this week | Backend: aggregate `tool` events |
| Trend | ↑/↓ percentage vs last week | Backend: week-over-week diff |

**Skills to rank** (from `nutshell-skills/skills/`):
1. `tidb-perf-diagnosis` — TiDB Performance Diagnosis
2. `grafana-screenshot` — Grafana Dashboard Screenshot
3. `grafana-panel-finder` — Grafana Panel Finder
4. `clinic-api` — Clinic API
5. `o11y-data` — O11Y Data Retrieval
6. `o11y-data-export` — O11Y Data Export
7. `o11y-metrics-api` — O11Y Metrics API
8. `tikv-fast-tune` — TiKV Fast Tune
9. `openclaw` — OpenClaw Integration
10. `tidbcloud-api` — TiDB Cloud API
11. `tidbcloud-http` — TiDB Cloud HTTP
12. `autoscaler-dashboard` — Autoscaler Dashboard
13. `db9` — DB9 Tool
14. `security` — Security Analysis
15. `o11y-auth` — O11Y Auth

### 3. 🔧 Most Effective Diagnostic Tools

> *"Which tools actually work?"* — ranked by success rate so users lean on proven tools rather than discovering failures by trial and error.

Ranked by **success rate** (completion without error) — highlights tools that most reliably produce actionable results.

| Column | Description | Source |
|--------|-------------|--------|
| Rank | Position by success rate | Computed |
| Tool name | MCP tool function name | Backend: `tool` SSE events |
| Success rate | % of calls completed without error | Backend: tool event status analysis |
| Avg response time | Average duration | Backend: tool event timestamps |
| Total calls | Volume indicator | Backend: count |

**Tools to rank** (from MCP servers):
- `diagnostic_screenshot` — Grafana screenshot capture
- `clinic_get_alert_detail` — Alert detail retrieval
- `o11y_query_metrics` — Metrics query
- `o11y_export_data` — Data export
- `resource_worker_analysis` — Resource worker insight
- `cluster_topology` — Cluster topology info

### 4. 📈 Trending Techniques

> *"How do power users actually approach this?"* — surfaces multi-step workflows so users can adopt proven diagnostic patterns rather than inventing their own from scratch.

User-facing "tip cards" that highlight popular diagnostic **workflows** (multi-step patterns) observed this week. These are editorial/curated in v1 and data-driven in v2.

| Field | Description | Source |
|-------|-------------|--------|
| Technique title | e.g. "CPU Spike Root Cause Analysis" | Curated / Backend pattern matching |
| Steps | Ordered list of skills/tools used | Curated |
| Usage count | How many times this workflow appeared | Backend: session pattern analysis |
| Effectiveness | User satisfaction or resolution signal | Future: user feedback |

**v1 (mock)**: 4–6 curated technique cards.

### 5. ⭐ Community Favorites

> *"What do experienced users keep coming back to?"* — repeat usage is a strong signal that something delivers lasting value, not just novelty.

Skills that received explicit positive signals (future: thumbs-up, "save to favorites").  
In v1, this is based on **repeat usage** — skills used repeatedly by the same user indicate preference.

| Field | Description | Source |
|-------|-------------|--------|
| Skill name | Display name | Skill metadata |
| Repeat users | Count of users who used it 3+ times | Backend: user-skill frequency |
| Rating | Future: explicit star rating | Future: user feedback |

### 6. 🆕 Recently Added

> *"What's new that I might be missing?"* — closes the discovery gap for users who haven't revisited the platform's capabilities recently.

New skills/tools added to the platform, so users discover new capabilities.

| Field | Description | Source |
|-------|-------------|--------|
| Skill name | Display name | Skill metadata |
| Added date | When the skill was introduced | Skill metadata / Git history |
| Description | Brief summary | `SKILL.md` description field |

## Data Sources Summary

| Source Type | Description | Phase |
|-------------|-------------|-------|
| **Backend analytics** | Aggregated from SSE `tool` events and chat sessions stored in SQLite | Phase 2 |
| **Skill metadata** | Parsed from `nutshell-skills/skills/*/SKILL.md` frontmatter | Phase 1 (static) |
| **Mock data** | Hardcoded in `lib/mockRankingData.ts` for UI development | Phase 1 |
| **User behavior tracking** | Frontend event tracking (skill views, clicks, favorites) | Phase 3 |

## Implementation Phases

### Phase 1 — Mock UI (Current)
- Create `/ranking` route with all 6 sections
- Mock data in `lib/mockRankingData.ts`
- Responsive layout matching OpenRouter style
- Navigation changes (user dropdown + Rankings link)

### Phase 2 — Backend Analytics
- Add `skill_usage` and `tool_usage` tables to SQLite
- Log tool calls from SSE events
- API endpoints: `GET /api/ranking/skills`, `GET /api/ranking/tools`, `GET /api/ranking/trends`
- Connect frontend to real data

### Phase 3 — User Behavior Tracking
- Frontend event tracking (view, click, favorite)
- User preference signals
- Personalized recommendations based on each user's current skill gaps

## Non-Goals

- **No user leaderboards.** Never surface who used what most. Ranking users creates competitive pressure and privacy concerns that work against the page's core purpose.
- **No punitive signals.** Don't highlight skills that failed or tools with low success rates in a way that discourages use — frame everything as positive discovery.
- **No paywalling discovery.** All ranking data should be visible to any authenticated user regardless of workspace tier.

## Technical Notes

- **UI Library**: `@tidbcloud/uikit` (Mantine-based) for layout primitives
- **Charts**: Simple SVG bar charts (no external charting library needed for v1)
- **Styling**: Inline styles per project convention
- **Route**: `app/ranking/page.tsx` — client component (`'use client'`)
- **Mock data**: `lib/mockRankingData.ts`