howamiprompting 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Avijit Sarkar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,124 @@
-# Temporary Holding Version
+<div align="center">
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# how am i prompting? 🤔
+
+**Spotify Wrapped for your AI coding prompts.**
+Find out how well you *really* talk to Claude Code, Codex, Cursor & friends — and get coached to do it better.
+
+```bash
+npx howamiprompting
+```
+
+100% local · no sign-up · free & open source · uses the AI you already have
+
+<img src="https://raw.githubusercontent.com/theavijitsarkar/howamiprompting/main/docs/wrapped-persona.png" width="49%" alt="Your prompting personality"> <img src="https://raw.githubusercontent.com/theavijitsarkar/howamiprompting/main/docs/wrapped-score.png" width="49%" alt="Your prompting score">
+
+</div>
+
+---
+
+## What it does
+
+One command scans every AI coding chat on your machine, keeps **only what you typed**, and opens a beautiful local report:
+
+- 🎬 **Your Wrapped** — prompts written, your AI crew, prime-time hour, catchphrases, rage moments, and your **prompting personality** (The Architect? The Yes-Machine? The Paste-and-Pray?)
+- 📐 **A score across 6 skills** — Clarity · Context · Specificity · Structure · Efficiency · English
+- ✨ **Makeovers of your real prompts** — your worst prompts, rewritten the way a senior engineer would write them
+- ✍️ **Honest English feedback** — your actual grammar mistakes, corrected, with an estimated CEFR level (judged on your prose, never your code)
+- 📌 **Stop repeating yourself** — finds instructions you type in every session ("use pnpm", "don't add comments") and turns them into a ready-to-paste `CLAUDE.md` / `AGENTS.md` / `.cursor/rules` / `GEMINI.md` / Copilot file
+- 🗓️ **A personal prompt template + 7-day plan**
+- 🎮 **Practice mode** — four timed mini-games generated from *your* weak spots (no paste, no spell-check)
+- 📈 **Progress over time** — run it again next month and see your score move
+- 🚀 **Share card** — a PNG with your score and persona (no prompts in it). Optional public leaderboard.
+
+<img src="https://raw.githubusercontent.com/theavijitsarkar/howamiprompting/main/docs/report.png" alt="The report">
+
+<img src="https://raw.githubusercontent.com/theavijitsarkar/howamiprompting/main/docs/makeovers.png" alt="Prompt makeovers">
+
+## Supported tools
+
+| Tool | Where we look |
+|---|---|
+| **Claude Code** | `~/.claude/projects/**.jsonl` |
+| **OpenAI Codex CLI** | `~/.codex/sessions/**.jsonl` |
+| **Gemini CLI** | `~/.gemini/tmp/*/logs.json`, `chats/` |
+| **Cursor** (Chat, Composer, Agent) | Cursor's `state.vscdb` (read from a temp copy) |
+| **VS Code Copilot Chat** | `workspaceStorage/*/chatSessions` |
+| **Windsurf · Antigravity · Trae · Kiro · VSCodium** | same VS Code–family locations |
+| **Cline · Roo Code · Kilo Code** | extension task histories |
+| **Continue** | `~/.continue/sessions` |
+| **OpenCode** | `~/.local/share/opencode/storage` |
+| **Aider** | `.aider.chat.history.md` in your projects |
+| **SpecStory** | `.specstory/history/*.md` |
+| **Anything else** | `npx howamiprompting --include export.md` (Markdown, JSON, JSONL, text) |
+
+Missing your tool? [Open an issue](https://github.com/theavijitsarkar/howamiprompting/issues) — or add a 30-line collector in [`cli/src/collect/`](https://github.com/theavijitsarkar/howamiprompting/tree/main/cli/src/collect) and send a PR.
+
+## How the analysis works
+
+1. **Collect** — read-only scan of the locations above. Assistant replies, tool output, sub-agent traffic and system messages are dropped; pasted code and logs are replaced with markers like `[pasted log: 40 lines]`.
+2. **Redact** — API keys, tokens, JWTs, private keys, passwords and DB URLs are stripped before anything else happens.
+3. **Measure locally** — dozens of stats (length, timing, acknowledgements, frustration, context-giving, repeated instructions, English mechanics) computed on your machine. This alone gives you the Wrapped story and a heuristic score.
+4. **Coach with your own AI** — a stratified sample (~180 prompts) goes to the agent **you already use**, in batches, then a synthesis pass writes the report. We auto-detect, in order:
+   `claude` (Claude Code) → `codex` → `gemini` → `ANTHROPIC_API_KEY` → `OPENROUTER_API_KEY` → `OPENAI_API_KEY` → **Ollama** (fully offline)
+
+You'll be asked before anything is sent. Use `--no-ai` for a stats-only report where nothing leaves your machine at all.
+
+## Privacy
+
+- No account, no telemetry, no analytics in the CLI or the report.
+- Your prompts are **never** sent to us. With an agent, the sample goes through *your own* Claude Code / Codex / Gemini / API key / local Ollama.
+- The report runs on `127.0.0.1` with a random per-run token.
+- History lives in `~/.howamiprompting/` — delete it any time.
+- The leaderboard is opt-in and only receives a nickname, scores, persona, tool names and prompt count.
+
+## Options
+
+```
+npx howamiprompting [options]
+
+--agent <id>      claude | codex | gemini | anthropic | openrouter | openai | ollama
+--model <name>    model override for that agent (e.g. haiku, sonnet)
+--no-ai           local stats only — nothing leaves your machine
+--sample <n>      prompts sent for deep analysis (default 180)
+--since <days>    only look at the last N days
+--include <file>  also import a chat export (repeatable)
+--roots <dir>     extra folder to search for Aider / SpecStory histories
+--last            re-open your last report without rescanning
+--json <file>     also write the report as JSON
+--no-open         don't open the browser
+-y, --yes         no questions
+```
+
+Requires Node.js 18.17+. Cursor history needs Node 22.5+ (built-in SQLite) **or** the `sqlite3` command (pre-installed on macOS).
+
+## The six skills
+
+| Skill | What great looks like |
+|---|---|
+| **Clarity** | One unambiguous goal. No "fix it", no "make it better". |
+| **Context** | Current vs expected behaviour, relevant files, the *why*, errors with one line of your theory. |
+| **Specificity** | Constraints, scope ("only touch X"), acceptance criteria, examples. |
+| **Structure** | One task at a time, or numbered steps. Key info first. |
+| **Efficiency** | Results without "still not working" loops and five rounds of "no, not like that". |
+| **English** | Clear sentences, correct tense, real punctuation. Small grammar slips become ambiguous instructions. |
+
+## Contributing
+
+```bash
+git clone https://github.com/theavijitsarkar/howamiprompting && cd howamiprompting/cli
+node test/make-fixtures.js /tmp/fakehome          # fake histories for every tool
+HOME=/tmp/fakehome node bin/howamiprompting.js --no-ai
+```
+
+Ideas that would be awesome: more collectors, better persona rules, translations of the report, more practice games.
+
+## Who made this
+
+Hi, I'm **[Avijit Sarkar](https://avijitsarkar.com)** — a founder from Kolkata building SaaS products like [GoDial](https://godial.cc) and [HyperScreenshot](https://hyperscreenshot.com). I talk to Claude Code and Codex all day, and wanted to know if I was any good at it. This is the tool I wished existed.
+
+Say hi: [avijitsarkar.com](https://avijitsarkar.com)
+
+## License
+
+MIT © [Avijit Sarkar](https://avijitsarkar.com). If it helped you, a ⭐ helps other developers find it.

package/bin/howamiprompting.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+const [major, minor] = process.versions.node.split('.').map(Number);
+if (major < 18 || (major === 18 && minor < 17)) {
+  console.error('howamiprompting needs Node.js 18.17 or newer (you have ' + process.versions.node + ').');
+  process.exit(1);
+}
+import('../src/cli.js').then(m => m.main(process.argv.slice(2))).catch(e => {
+  console.error('\n  Something went wrong:', e && e.message ? e.message : e);
+  console.error('  Please report it: https://github.com/theavijitsarkar/howamiprompting/issues\n');
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,48 @@
 {
   "name": "howamiprompting",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Spotify Wrapped for your AI coding prompts. Scans your Claude Code, Codex, Cursor, Gemini CLI, Copilot, Cline, Aider\u2026 chats locally, scores how you prompt (and your English), and shows you how to get better.",
+  "keywords": [
+    "prompt",
+    "prompting",
+    "claude-code",
+    "codex",
+    "cursor",
+    "gemini-cli",
+    "copilot",
+    "ai",
+    "llm",
+    "developer-tools",
+    "wrapped",
+    "cli"
+  ],
+  "homepage": "https://howamiprompting.com",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/theavijitsarkar/howamiprompting.git"
+  },
+  "bugs": "https://github.com/theavijitsarkar/howamiprompting/issues",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "howamiprompting": "bin/howamiprompting.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "ui",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18.17"
+  },
+  "scripts": {
+    "start": "node bin/howamiprompting.js",
+    "fixtures": "node test/make-fixtures.js /tmp/hap-fakehome"
+  },
+  "author": {
+    "name": "Avijit Sarkar",
+    "url": "https://avijitsarkar.com"
+  }
+}

package/src/agents.js

@@ -0,0 +1,160 @@
+// Use whatever AI the developer already has: Claude Code, Codex, Gemini CLI, an API key, or Ollama.
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn } from 'node:child_process';
+import { which } from './util.js';
+
+const CLI_TIMEOUT = 6 * 60 * 1000;
+
+function run(cmd, args, input, { cwd, timeout = CLI_TIMEOUT } = {}) {
+  return new Promise((resolve, reject) => {
+    if (process.platform === 'win32') args = args.map(a => /[\s"]/.test(a) ? `"${a.replace(/"/g, '\\"')}"` : a); // shell:true on Windows
+    const p = spawn(cmd, args, { cwd, env: { ...process.env, NO_COLOR: '1', CI: '1' }, stdio: ['pipe', 'pipe', 'pipe'], shell: process.platform === 'win32' });
+    let out = '', err = '';
+    const t = setTimeout(() => { p.kill('SIGKILL'); reject(new Error(`${cmd} timed out`)); }, timeout);
+    p.stdout.on('data', d => out += d);
+    p.stderr.on('data', d => err += d);
+    p.on('error', e => { clearTimeout(t); reject(e); });
+    p.on('close', code => { clearTimeout(t); code === 0 ? resolve(out) : reject(new Error(`${cmd} exited ${code}: ${(err || out).slice(-400)}`)); });
+    p.stdin.on('error', () => {}); // agent may exit before reading stdin (EPIPE)
+    p.stdin.end(input);
+  });
+}
+
+const sandbox = () => fs.mkdtempSync(path.join(os.tmpdir(), 'hap-agent-'));
+
+async function postJSON(url, headers, body, timeout = 180000) {
+  const ctl = new AbortController();
+  const t = setTimeout(() => ctl.abort(), timeout);
+  try {
+    const r = await fetch(url, { method: 'POST', headers: { 'content-type': 'application/json', ...headers }, body: JSON.stringify(body), signal: ctl.signal });
+    const j = await r.json().catch(() => ({}));
+    if (!r.ok) throw new Error(j.error?.message || j.error || `HTTP ${r.status}`);
+    return j;
+  } finally { clearTimeout(t); }
+}
+
+export const AGENTS = {
+  claude: {
+    label: 'Claude Code', kind: 'cli', privacy: 'Anthropic (via your Claude Code login)',
+    detect: () => which('claude'),
+    async ask(prompt, o = {}) {
+      const dir = sandbox();
+      try {
+        const args = ['-p', '--output-format', 'json'];
+        if (o.model) args.push('--model', o.model);
+        const raw = await run('claude', args, prompt, { cwd: dir });
+        try { const j = JSON.parse(raw); if (j.is_error) throw new Error(j.result || 'Claude Code error'); return j.result ?? raw; } catch (e) { if (/Claude Code error/.test(e.message)) throw e; return raw; }
+      } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+    },
+  },
+  codex: {
+    label: 'Codex CLI', kind: 'cli', privacy: 'OpenAI (via your Codex login)',
+    detect: () => which('codex'),
+    async ask(prompt, o = {}) {
+      const dir = sandbox();
+      const outFile = path.join(dir, 'last.txt');
+      try {
+        const args = ['exec', '--skip-git-repo-check', '-s', 'read-only', '--color', 'never', '--output-last-message', outFile];
+        if (o.model) args.push('-m', o.model);
+        args.push('-');
+        const raw = await run('codex', args, prompt, { cwd: dir });
+        return fs.existsSync(outFile) ? fs.readFileSync(outFile, 'utf8') : raw;
+      } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+    },
+  },
+  gemini: {
+    label: 'Gemini CLI', kind: 'cli', privacy: 'Google (via your Gemini CLI login)',
+    detect: () => which('gemini'),
+    async ask(prompt, o = {}) {
+      const dir = sandbox();
+      try {
+        const args = ['-p', 'Follow the instructions in the input above. Reply with the JSON only.'];
+        if (o.model) args.push('-m', o.model);
+        return await run('gemini', args, prompt, { cwd: dir });
+      } finally { fs.rmSync(dir, { recursive: true, force: true }); }
+    },
+  },
+  anthropic: {
+    label: 'Anthropic API', kind: 'api', privacy: 'Anthropic (your ANTHROPIC_API_KEY)',
+    detect: () => process.env.ANTHROPIC_API_KEY ? 'ANTHROPIC_API_KEY' : null,
+    async ask(prompt, o = {}) {
+      const j = await postJSON('https://api.anthropic.com/v1/messages', { 'x-api-key': process.env.ANTHROPIC_API_KEY, 'anthropic-version': '2023-06-01' },
+        { model: o.model || 'claude-haiku-4-5', max_tokens: 8000, messages: [{ role: 'user', content: prompt }] });
+      return (j.content || []).map(c => c.text || '').join('');
+    },
+  },
+  openai: {
+    label: 'OpenAI API', kind: 'api', privacy: 'OpenAI (your OPENAI_API_KEY)',
+    detect: () => process.env.OPENAI_API_KEY ? 'OPENAI_API_KEY' : null,
+    async ask(prompt, o = {}) {
+      const j = await postJSON('https://api.openai.com/v1/chat/completions', { authorization: 'Bearer ' + process.env.OPENAI_API_KEY },
+        { model: o.model || 'gpt-4.1-mini', response_format: { type: 'json_object' }, messages: [{ role: 'user', content: prompt }] });
+      return j.choices?.[0]?.message?.content || '';
+    },
+  },
+  openrouter: {
+    label: 'OpenRouter API', kind: 'api', privacy: 'OpenRouter (your OPENROUTER_API_KEY)',
+    detect: () => process.env.OPENROUTER_API_KEY ? 'OPENROUTER_API_KEY' : null,
+    async ask(prompt, o = {}) {
+      const j = await postJSON('https://openrouter.ai/api/v1/chat/completions', { authorization: 'Bearer ' + process.env.OPENROUTER_API_KEY, 'X-Title': 'howamiprompting' },
+        { model: o.model || 'anthropic/claude-haiku-4.5', messages: [{ role: 'user', content: prompt }] });
+      return j.choices?.[0]?.message?.content || '';
+    },
+  },
+  ollama: {
+    label: 'Ollama (local)', kind: 'local', privacy: 'nobody — runs on this machine',
+    _model: null,
+    async detectAsync() {
+      try {
+        const r = await fetch((process.env.OLLAMA_HOST || 'http://127.0.0.1:11434') + '/api/tags', { signal: AbortSignal.timeout(1500) });
+        const j = await r.json();
+        const names = (j.models || []).map(m => m.name);
+        const pref = ['qwen3', 'qwen2.5', 'llama3.3', 'llama3.1', 'gemma3', 'mistral-small', 'mistral', 'phi4'];
+        this._model = names.find(n => pref.some(p => n.startsWith(p))) || names[0] || null;
+        return this._model ? 'model ' + this._model : null;
+      } catch { return null; }
+    },
+    async ask(prompt, o = {}) {
+      const j = await postJSON((process.env.OLLAMA_HOST || 'http://127.0.0.1:11434') + '/api/generate', {},
+        { model: o.model || this._model, prompt, format: 'json', stream: false, options: { num_ctx: 32768, temperature: 0.3 } }, 15 * 60 * 1000);
+      return j.response || '';
+    },
+  },
+};
+
+export const ORDER = ['claude', 'codex', 'gemini', 'anthropic', 'openrouter', 'openai', 'ollama'];
+
+export async function detectAgents() {
+  const found = [];
+  for (const id of ORDER) {
+    const a = AGENTS[id];
+    const d = a.detectAsync ? await a.detectAsync() : a.detect();
+    if (d) found.push({ id, label: a.label, detail: d, privacy: a.privacy, kind: a.kind });
+  }
+  return found;
+}
+
+export function extractJSON(text) {
+  let t = String(text || '').trim().replace(/^```(?:json)?\s*/i, '').replace(/\s*```\s*$/, '');
+  try { return JSON.parse(t); } catch {}
+  const s = t.indexOf('{'), e = t.lastIndexOf('}');
+  if (s >= 0 && e > s) { try { return JSON.parse(t.slice(s, e + 1)); } catch {} }
+  throw new Error('The agent did not return valid JSON');
+}
+
+/** Ask the agent and parse JSON, retrying once. */
+export async function askJSON(agentId, prompt, { model, validate = () => {} } = {}) {
+  const a = AGENTS[agentId];
+  let last;
+  for (let i = 0; i < 2; i++) {
+    try {
+      const txt = await a.ask(prompt + (i ? '\n\nIMPORTANT: your previous reply was not valid JSON. Reply with ONE JSON object and nothing else.' : ''), { model });
+      const j = extractJSON(txt);
+      validate(j);
+      return j;
+    } catch (e) { last = e; }
+  }
+  throw last;
+}

package/src/analyze.js

@@ -0,0 +1,167 @@
+// Deep analysis with the developer's own AI agent. Map (chunks) → reduce (synthesis).
+import { askJSON } from './agents.js';
+
+export const DIMENSIONS = {
+  clarity: 'Clarity — is the ask unambiguous? One clear goal, plain words, no guessing needed.',
+  context: 'Context — does the AI get what it needs: relevant files, current vs expected behaviour, why, error output with explanation.',
+  specificity: 'Specificity — constraints, acceptance criteria, examples, scope limits ("only touch X", "keep the API the same").',
+  structure: 'Structure — one task at a time or clearly numbered steps; important info first; not a wall of text.',
+  efficiency: 'Efficiency — gets results without long correction loops, repeated asks, frustration or "still not working" spirals.',
+  english: 'English — grammar, tense, sentence boundaries, punctuation, spelling. Judge the prose only, never code.',
+};
+const WEIGHTS = { clarity: 0.2, context: 0.22, specificity: 0.18, structure: 0.12, efficiency: 0.13, english: 0.15 };
+export const overallFrom = s => Math.round(Object.entries(WEIGHTS).reduce((a, [k, w]) => a + w * (Number(s[k]) || 0), 0));
+
+const COACH = `You are the world's best coach for developers who prompt AI coding agents (Claude Code, Codex, Cursor, Copilot, Gemini CLI). You are also an expert English writing coach for non-native speakers. You are specific, honest, funny when it fits, never generic. Every claim must point at the developer's real prompts. You only judge HOW they prompt and their written English — never their code.`;
+
+/** Pick a representative sample: spread across tools and time, skip trivial one-word acks (we already count those). */
+export function sample(prompts, max = 180) {
+  const useful = prompts.filter(p => p.words >= 3 || p.logLines || p.codeLines);
+  if (useful.length <= max) return useful;
+  const byTool = new Map();
+  for (const p of useful) { if (!byTool.has(p.tool)) byTool.set(p.tool, []); byTool.get(p.tool).push(p); }
+  const out = [];
+  const tools = [...byTool.values()];
+  const base = Math.floor(max / tools.length);
+  let spare = max - base * tools.length;
+  // proportional with a floor so small tools are represented
+  const total = useful.length;
+  const quota = tools.map(arr => Math.max(Math.min(arr.length, 8), Math.round(max * arr.length / total)));
+  let sum = quota.reduce((a, b) => a + b, 0);
+  while (sum > max) { const i = quota.indexOf(Math.max(...quota)); quota[i]--; sum--; }
+  tools.forEach((arr, ti) => {
+    const k = Math.min(arr.length, quota[ti] + (spare-- > 0 ? 0 : 0));
+    // 60% recent half, 40% older half, evenly spaced within each
+    const recent = arr.slice(Math.floor(arr.length / 2)), older = arr.slice(0, Math.floor(arr.length / 2));
+    const kr = Math.min(recent.length, Math.ceil(k * 0.6)), ko = Math.min(older.length, k - kr);
+    for (const [src, kk] of [[older, ko], [recent, kr]]) for (let i = 0; i < kk; i++) out.push(src[Math.floor(i * src.length / kk)]);
+  });
+  return out.sort((a, b) => a.id - b.id);
+}
+
+function fmt(p) {
+  const ctx = p.context ? `\n   ↳ (AI had just said: "${p.context.slice(-160).replace(/\s+/g, ' ')}")` : '';
+  return `[${p.id}] (${p.tool}${p.project ? ', ' + p.project : ''}) ${p.text.slice(0, 700).replace(/\n{2,}/g, '\n')}${ctx}`;
+}
+
+function chunkPrompt(chunk) {
+  return `${COACH}
+
+TASK: analyze_prompt_batch
+Below are ${chunk.length} prompts one developer typed to AI coding assistants. Each starts with [id] and the tool. Pasted code/logs were replaced by markers like [pasted log: 40 lines]. Secrets were redacted.
+
+Score each dimension 0-100 for THIS batch (60 = average developer, 80 = strong, 90+ = exceptional):
+${Object.entries(DIMENSIONS).map(([k, v]) => `- ${k}: ${v}`).join('\n')}
+
+PROMPTS:
+${chunk.map(fmt).join('\n')}
+
+Return ONE JSON object, no prose:
+{
+ "scores": {"clarity":0,"context":0,"specificity":0,"structure":0,"efficiency":0,"english":0},
+ "strengths": [{"point":"what they do well","id":123,"quote":"exact short quote"}],
+ "issues": [{"issue":"short label","category":"clarity|context|specificity|structure|efficiency|english","severity":"high|medium|low","ids":[1,2],"quote":"exact short quote (max 25 words)","why":"why this costs them","rewrite":"how that prompt should have been written"}],
+ "english_errors": [{"quote":"exact words","fix":"corrected","rule":"short rule"}],
+ "worst_ids": [ids of the 3 most improvable MEANINGFUL prompts — not one-word acks],
+ "best_ids": [ids of the 2 best prompts],
+ "notes": "2 sentences on this developer's style"
+}
+Limits: strengths 2-4, issues 3-6, english_errors up to 8 (empty if their English is clean).`;
+}
+
+function synthPrompt(stats, batches, sampleById, heuristic) {
+  const avg = {};
+  for (const k of Object.keys(DIMENSIONS)) {
+    const v = batches.map(b => Number(b.scores?.[k])).filter(n => !isNaN(n));
+    avg[k] = v.length ? Math.round(v.reduce((a, b) => a + b, 0) / v.length) : heuristic[k] ?? 60;
+  }
+  const worst = [...new Set(batches.flatMap(b => b.worst_ids || []))].map(id => sampleById.get(Number(id))).filter(Boolean).slice(0, 6);
+  const best = [...new Set(batches.flatMap(b => b.best_ids || []))].map(id => sampleById.get(Number(id))).filter(Boolean).slice(0, 3);
+  const s = stats;
+  const facts = {
+    prompts: s.totals.prompts, sessions: s.totals.sessions, tools: s.tools.map(t => `${t.name} (${t.count})`).join(', '),
+    median_words: s.length.median, avg_words: s.length.avg,
+    one_word_acks_pct: s.habits.confirmPct, vague_pct: s.habits.vaguePct, frustration_pct: s.habits.frustrationPct,
+    pushback_pct: s.habits.pushbackPct, gives_context_pct: s.habits.contextPct, paste_error_without_explanation_pct: s.habits.pastePrayPct,
+    multi_ask_pct: s.habits.multiAskPct, please_pct: s.habits.pleasePct, swears: s.habits.swears, interrupts: s.totals.interrupts,
+    lowercase_start_pct: s.english.lowerStartPct, no_final_punctuation_pct: s.english.noEndPunctPct, run_on_pct: s.english.runOnPct,
+    night_owl_pct: s.time.nightPct, persona: s.persona.name,
+    detected_english_patterns: s.english.patterns.slice(0, 6).map(p => `${p.label} ×${p.count}`).join(', '),
+  };
+  return `${COACH}
+
+TASK: synthesize_report
+You analysed a developer's prompts in ${batches.length} batches. Merge everything into ONE final report. Be concrete, quote their real words, keep it encouraging but honest.
+
+BATCH SCORES (average): ${JSON.stringify(avg)}
+BATCH FINDINGS:
+${batches.map((b, i) => `--- batch ${i + 1}\nnotes: ${b.notes || ''}\nstrengths: ${JSON.stringify(b.strengths || [])}\nissues: ${JSON.stringify(b.issues || [])}\nenglish_errors: ${JSON.stringify(b.english_errors || [])}`).join('\n')}
+
+MEASURED FACTS FROM ALL ${s.totals.prompts} PROMPTS: ${JSON.stringify(facts)}
+
+INSTRUCTIONS THEY REPEAT ACROSS SESSIONS (candidates for a rules file): ${JSON.stringify(s.repeated.map(r => r.text + ` (${r.sessions} sessions)`))}
+
+THEIR MOST IMPROVABLE PROMPTS:
+${worst.map(fmt).join('\n')}
+
+THEIR BEST PROMPTS:
+${best.map(fmt).join('\n')}
+
+Return ONE JSON object:
+{
+ "headline": "a punchy 5-10 word verdict, second person",
+ "summary": "3-4 sentences, second person, specific",
+ "scores": {"clarity":0,"context":0,"specificity":0,"structure":0,"efficiency":0,"english":0},
+ "level": "Beginner|Developing|Proficient|Advanced|Expert",
+ "strengths": [{"title":"...","detail":"1-2 sentences","example":"exact quote"}],
+ "weaknesses": [{"title":"...","category":"clarity|context|specificity|structure|efficiency|english","detail":"why it hurts their results","example":"exact quote","better":"the same prompt rewritten well","impact":"high|medium|low"}],
+ "makeovers": [{"id":123,"original":"their prompt verbatim (may shorten)","rewritten":"an excellent version of the same request","why":["3 short reasons"]}],
+ "english": {"score":0,"cefr":"A2|B1|B2|C1|C2","summary":"2 sentences","errors":[{"quote":"exact words","fix":"corrected","rule":"short rule","frequency":"often|sometimes|once"}],"tips":["3 specific tips"]},
+ "habits": [{"start":"a habit to start","stop":"the habit it replaces"}],
+ "rules_file": ["5-10 one-line rules they keep repeating or should set once in CLAUDE.md / AGENTS.md / .cursorrules"],
+ "template": "a personal fill-in-the-blanks prompt template tailored to their weaknesses (use \\n for new lines)",
+ "plan": ["7 short daily drills, one per day"],
+ "fun_facts": ["3 witty, true observations from the facts"],
+ "persona_note": "one witty line about them as '${s.persona.name}'"
+}
+Counts: strengths 3, weaknesses 4-5, makeovers 3 (only from the 'most improvable' list), english.errors up to 8, habits 4-5.`;
+}
+
+/**
+ * Run the full analysis. onStep(label, i, total) for progress.
+ */
+export async function analyze(prompts, stats, { agent, model, sampleSize = 180, batchSize = 60, concurrency = 2, onStep = () => {} } = {}) {
+  const smp = sample(prompts, sampleSize);
+  const byId = new Map(smp.map(p => [p.id, p]));
+  const chunks = [];
+  for (let i = 0; i < smp.length; i += batchSize) chunks.push(smp.slice(i, i + batchSize));
+  if (!chunks.length) throw new Error('No prompts to analyse');
+  const total = chunks.length + 1;
+  let done = 0;
+  const batches = new Array(chunks.length);
+  const errors = [];
+  let next = 0;
+  async function worker() {
+    while (next < chunks.length) {
+      const i = next++;
+      try {
+        batches[i] = await askJSON(agent, chunkPrompt(chunks[i]), { model, validate: j => { if (!j.scores) throw new Error('missing scores'); } });
+      } catch (e) { errors.push(e.message); batches[i] = null; }
+      onStep(`Read batch ${++done} of ${chunks.length}`, done, total);
+    }
+  }
+  await Promise.all(Array.from({ length: Math.min(concurrency, chunks.length) }, worker));
+  const ok = batches.filter(Boolean);
+  if (!ok.length) throw new Error('Every batch failed: ' + errors[0]);
+
+  onStep('Writing your report', done, total);
+  const report = await askJSON(agent, synthPrompt(stats, ok, byId, stats.heuristic), {
+    model, validate: j => { if (!j.scores || !j.headline) throw new Error('incomplete report'); },
+  });
+  for (const k of Object.keys(DIMENSIONS)) report.scores[k] = Math.max(0, Math.min(100, Math.round(Number(report.scores[k]) || stats.heuristic[k] || 60)));
+  report.scores.overall = overallFrom(report.scores);
+  report.sampled = smp.length;
+  report.batchErrors = errors.length;
+  onStep('Done', total, total);
+  return report;
+}