git-impact 0.3.0 → 0.6.2

package/skill/SKILL.md

@@ -1,278 +1,198 @@
 ---
 name: git-impact
 description: >
-  Translates git commits into plain-English business impact bullets — ideal for
-  daily standups, manager updates, and end-of-quarter performance reviews.
-  Use this skill whenever the user says anything like: "do my standup",
-  "what did I work on today", "translate my commits", "summarize my git activity",
-  "write my standup update", "what should I say in standup", "git-impact",
-  "/git-impact", "show my impact", "translate today's work", "what did I ship",
-  "generate a performance review", "what have I done this week/month/quarter",
-  "review my commits". Also trigger for "since yesterday", "last 3 days commits",
-  or any request to turn technical git output into something a manager can read.
+  Translates git commits into plain-English business impact bullets. Use this
+  skill when the user says any of: "do my standup", "/git-impact", "what did I
+  ship today", "what did I work on", "translate my commits", "summarize my
+  git activity", "write my standup update", "what should I say in standup",
+  "show my impact", "since yesterday", "since 3d", "since last standup",
+  "what have I done this week / month / quarter", "generate a performance
+  review", "performance review prep", "review my commits", "what's blocked",
+  "weekly summary". Trigger on any request to turn raw git output into
+  something a non-technical manager can read. The skill orchestrates MCP
+  tools (get_git_activity, save_impact_entry, get_history, etc.) — it does
+  not run sqlite3 or other DB commands directly.
 ---
 
 # git-impact
 
-Translate git commits into plain-English business impact for standups, manager
-updates, and performance reviews — without an API key. You do the translation
-inline using bash to read git data and a per-repo context file for personalization.
+You translate git commits into plain-English business impact for standups,
+manager updates, and performance review prep. Your job is **orchestration**:
+call the MCP tools provided by the `git-impact` server, apply the translation
+rules, and produce the output. The MCP server owns all data access (git, DB).
+You own the language.
 
----
-
-## Sub-commands
-
-Parse the user's message to determine which mode to run:
-
-| What the user says | Mode |
-|---|---|
-| `do my standup`, `today`, `/git-impact`, no args | **today** |
-| `since yesterday`, `since 3d`, `since 2026-05-01` | **since \<when\>** |
-| `review`, `performance review`, `last 30 days`, `Q2 review` | **review** |
-| `init`, `set up context`, `configure for this repo` | **init** |
+If the `git-impact` MCP server is not available in this conversation, fall
+back to the bash steps in `references/fallback-bash.md` — but the MCP path
+is preferred everywhere it works.
 
 ---
 
-## Step 1 — Find the repo root
+## Pick a mode from the user's message
 
-Run this to find the git root from wherever you are:
-
-```bash
-git rev-parse --show-toplevel 2>/dev/null
-```
+| User says | Mode |
+|---|---|
+| "do my standup", "today", "/git-impact", no args | **standup** (default) |
+| "since yesterday", "since 3d", "since 2026-05-01" | **standup** with explicit `since_iso` |
+| "review", "performance review", "last 90 days", "Q2 review" | **review** |
+| "init", "set up context", "configure for this repo" | **init** |
+| "make a presentation", "make a slide", "make me a shareable" | **standup** + **bespoke HTML** (extra step) |
 
-If it fails, tell the user: *"No git repository found in the current directory. Open
-a project folder first, or `cd` into a repo."* Stop there.
+The default standup writes to the rolling HTML dashboard at
+`.git-impact/result.html` (regenerated by the report renderer the user
+opens with `git-impact view`). The per-day bespoke HTML is only created
+when the user explicitly asks for a presentation — don't write one by
+default; it's expensive and most days don't need it.
 
-Store the result as `REPO_ROOT`.
+If the message is ambiguous, default to **standup**.
 
 ---
 
-## Step 2 — Load context (if it exists)
+## Mode: standup
 
-```bash
-cat "$REPO_ROOT/.git-impact/context.json" 2>/dev/null || echo "NONE"
-```
+### 1. Resolve the lookback window
 
-If the file exists, parse it. It looks like:
+- If the user said an explicit "since X", convert to an ISO timestamp and use it.
+- Otherwise call **`get_last_standup_date`**. If it returns a date, use the
+  start of the day after that date as `since_iso`. If it returns null,
+  default to start-of-today.
 
-```json
-{
-  "companyDescription": "B2B SaaS for workforce analytics",
-  "managerPriorities": "Shipping on time, not breaking prod",
-  "glossary": {
-    "RLS": "data security layer",
-    "TabPFN": "AI predictions",
-    "MFA": "login security"
-  }
-}
-```
+This is the "since last standup" default — it survives weekends and days off.
 
-Use this to personalise your translation — apply the glossary and frame impact
-around what the manager cares about. If the file doesn't exist, use general
-technical language and suggest running `init` at the end.
+### 2. Fetch git activity
 
----
+Call **`get_git_activity`** with `since_iso` and (optionally) `until_iso`.
+You'll get back commits, file stats, branch, and the resolved repo path.
 
-## Mode: today / since \<when\>
+If there are no commits in the window: tell the user clearly and stop. Do
+NOT save an empty entry.
 
-### Fetch commits
+### 3. Optional: enrich with GitHub PR data
 
-For **today**:
-```bash
-git -C "$REPO_ROOT" log \
-  --since="$(date '+%Y-%m-%d') 00:00:00" \
-  --format="%h|%s|%b|%an|%ad" \
-  --date=short \
-  HEAD
-```
-
-For **since \<when\>** — convert the user's input to a git `--since` value:
-- `yesterday` → `--since="yesterday 00:00:00"`
-- `3d` → `--since="3 days ago 00:00:00"`
-- `2026-05-01` → `--since="2026-05-01 00:00:00"`
-
-### Fetch files changed
-
-```bash
-FIRST=$(git -C "$REPO_ROOT" log --since="..." --format="%h" HEAD | tail -1)
-git -C "$REPO_ROOT" diff --stat "$FIRST"^ HEAD 2>/dev/null || \
-  git -C "$REPO_ROOT" show --stat "$FIRST" 2>/dev/null
-```
+If the user has a `github_token` saved in their context (the
+`get_git_activity` response or a prior `get_github_activity` call will tell
+you), call **`get_github_activity`** to pull PR titles and descriptions.
+PR descriptions are the single best source for accurate "why it matters"
+text — strongly prefer them over inference.
 
-### Translate
+### 4. Translate
 
-If there are no commits, say so clearly and stop.
+Read **`references/translation-rules.md`** for the prompt-engineering details.
+Key rules at a glance:
 
-Otherwise translate into **2–5 bullet points**. Follow these rules:
+- **What + why**, not what + how
+- **Apply the glossary** from `context.json` (returned by the context resource
+  or visible in `get_git_activity` output)
+- **Provenance is mandatory** — every saved bullet gets `pr` / `commit_body` /
+  `commit_message` / `ticket` / `inferred`
+- **Group related commits** into one bullet, not many
+- **2-5 bullets total**, never more
 
-1. **What + why, not what + how.** Each bullet must say what was accomplished
-   AND why it matters to the business. "Fixed a bug in the auth middleware" is
-   useless to a manager. "Fixed login failures for admin users — unblocks the
-   Q2 portal launch" is useful.
+### 5. Print the user-facing output
 
-2. **Apply the glossary.** Replace every technical term listed in context.json
-   with its plain-English equivalent. If no glossary, infer from context.
-
-3. **Never hallucinate impact.** If you can't infer the business reason, say
-   "technical foundation work for [area]" rather than inventing an outcome.
-
-4. **Group related commits.** Three commits all touching auth tell one story —
-   write one bullet, not three.
+```
+📅 [Day, Date or date range]
 
-5. **WIP / draft commits** get `⏳ In progress:` and state what the expected
-   outcome is, not what was done so far.
+✅ [Summary]
+   → [Why it matters]
 
-6. **Be specific.** "Improved performance" is vague. "Reduced login latency
-   by ~40%" is specific. Use whatever numbers exist in the commit messages.
+⏳ In progress: [What]
+   → [Expected outcome]
 
-### Output format
+🚫 Blocked: [What]   (only if applicable)
+   → [What's needed]
 
+📁 [N] files across [areas]
+   [N] commit(s) on [branch]
 ```
-📅 [Day, Date]
 
-✅ [Plain-English summary of what was accomplished]
-   → [Why it matters — who it unblocks, what risk it reduces, what it enables]
+### 6. Save to history
 
-⏳ In progress: [What is being worked on]
-   → [Expected outcome when complete]
+Call **`save_impact_entry`** with the structured items including
+`provenance` for each. The MCP tool handles the SQLite write — never run
+`sqlite3` directly. Required fields per item: `status`, `summary`,
+`provenance`. Recommended: `impact`, `refs`.
 
-📁 [N] files changed across [brief description of areas touched]
-   [N] commit(s) on [branch name]
+Example item:
+```json
+{
+  "status": "done",
+  "summary": "Shipped multi-tenant data isolation",
+  "impact": "Unblocks SOC2 sign-off, prevents cross-company data leaks",
+  "provenance": "pr",
+  "refs": ["PR #142", "ENG-1234"]
+}
 ```
 
-### Save to history
-
-After printing the output, silently save to `.git-impact/history.db`:
-
-```bash
-mkdir -p "$REPO_ROOT/.git-impact"
-grep -qxF '.git-impact/history.db' "$REPO_ROOT/.gitignore" 2>/dev/null || \
-  printf '\n# git-impact local history (private, per-machine)\n.git-impact/history.db\n' \
-  >> "$REPO_ROOT/.gitignore"
-
-sqlite3 "$REPO_ROOT/.git-impact/history.db" "
-CREATE TABLE IF NOT EXISTS impact_entries (
-  id            INTEGER PRIMARY KEY AUTOINCREMENT,
-  date          TEXT NOT NULL,
-  repo_name     TEXT NOT NULL,
-  total_commits INTEGER NOT NULL DEFAULT 0,
-  total_files   INTEGER NOT NULL DEFAULT 0,
-  items_json    TEXT NOT NULL DEFAULT '[]',
-  created_at    TEXT NOT NULL DEFAULT (datetime('now'))
-);
-INSERT INTO impact_entries (date, repo_name, total_commits, total_files, items_json)
-VALUES ('$(date +%Y-%m-%d)', '$(basename $REPO_ROOT)', $COMMIT_COUNT, $FILE_COUNT, '$ITEMS_JSON');
-"
-```
+### 7. Point the user at the dashboard
 
-If `sqlite3` is not available, skip silently.
-
-### Build a polished HTML presentation
-
-After saving to history, **use your Write tool to create a bespoke HTML
-presentation** for today's standup. This is not a generic template — each day's
-file should be tailored to the actual content, with custom layout, charts, or
-diagrams when they help.
-
-**Where to write:**
-- `$REPO_ROOT/.git-impact/standups/YYYY-MM-DD.html` — today's file
-- `$REPO_ROOT/.git-impact/standups/index.html` — list of all standups (regenerate it)
-
-**Stack (all CDN, no install):**
-- Tailwind CSS via `<script src="https://cdn.tailwindcss.com">`
-- Inter font via Google Fonts
-- Chart.js (`https://cdn.jsdelivr.net/npm/chart.js`) only if there are real numbers worth charting
-- Mermaid (`https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs`) for flow/architecture diagrams when relevant
-
-**Required structure:**
-1. **Hero** — date label + a bold, plain-English headline that captures the day
-   ("Shipped safety analytics, hardened tenant isolation" — not "9 commits")
-2. **Stats grid** — 3-4 metric cards (commits, files, PRs merged, areas touched)
-3. **Achievement cards** — one per ✅ item with status pill, title, summary,
-   "→ Why it matters" line, and tags (PR #, area, file count)
-4. **Optional visual** — only when the content warrants one (a Mermaid flow
-   diagram for architecture changes, a Chart.js chart for ratios/comparisons,
-   a code-style block for a key formula). Skip if forced.
-5. **Footer** — file count, branch, link back to `index.html`
-
-**Design language:**
-- Dark theme by default (`bg-slate-950`), generous spacing, max width 4xl
-- Cards: `bg-slate-900/50 border border-slate-800 rounded-2xl p-6`
-- Status pills: emerald for done, amber for in-progress, rose for blocked
-- Print-friendly via `@media print`
-
-**Status pill colors:**
-- ✅ Shipped → `bg-emerald-500/20 text-emerald-400`
-- ⏳ In Progress → `bg-amber-500/20 text-amber-400`
-- 🚫 Blocked → `bg-rose-500/20 text-rose-400`
-
-After writing both files, print the file URL on the very last line of your reply:
+The rolling HTML dashboard at `<repo>/.git-impact/result.html` is the
+default visual output — it's regenerated automatically when the user runs
+`git-impact view`, and now includes today's entry because you just saved
+it. End your reply with that file URL on its own last line:
 
 ```
-🎯 file://$REPO_ROOT/.git-impact/standups/YYYY-MM-DD.html
+🎯 file:///<absolute-repo-path>/.git-impact/result.html
 ```
 
-Replace `$REPO_ROOT` with the real absolute path so the user can ⌘-click.
+**Only if the user explicitly asked for a "presentation", "slide",
+"shareable", or "screenshot-friendly" output**, ALSO read
+`references/html-template.md` and use your `Write` tool to create
+`<repo>/.git-impact/standups/YYYY-MM-DD.html` (plus update
+`standups/index.html`). Most days don't need this — skip by default.
 
 ---
 
 ## Mode: review
 
-Fetch saved history and synthesise a performance review.
-
-Parse the period from the user's message:
-- `last 30 days` / `30d` → last 30 days
-- `last 90 days` / `90d` → last 90 days (default)
-- `Q2-2026` → April 1 – June 30, 2026
-
-```bash
-sqlite3 "$REPO_ROOT/.git-impact/history.db" \
-  "SELECT date, repo_name, total_commits, items_json
-   FROM impact_entries
-   WHERE date >= '$FROM' AND date <= '$TO'
-   ORDER BY date ASC;" 2>/dev/null
+1. Parse the period from the user's message:
+   - "last 30 days" / "30d" → `last_days: 30`
+   - "last 90 days" / "90d" / no arg → `last_days: 90`
+   - "Q2-2026" → `from_date: 2026-04-01`, `to_date: 2026-06-30`
+2. Call **`get_history`** with the parsed window.
+3. If no entries returned: tell the user
+   *"No saved history yet for this period. Use the standup mode daily to
+   build up history, then come back."* and stop.
+4. Synthesise themes (Features, Reliability, Security, Code review,
+   Infrastructure). Only include themes that apply.
+5. Frame as **performance review prep** (evidence pack), not a finished
+   review — bullets should include dates and refs the user can paste into
+   their own writing.
+
+Output:
 ```
+Performance Review Prep — [Period]
 
-If the DB doesn't exist or returns nothing: *"No saved history found for this
-period. Use the standup mode daily to build up history, then come back."*
-
-Otherwise synthesise:
-
-```
-Performance Review — [Period]
-
-[One headline sentence — biggest contribution this period]
+[One headline sentence — biggest contribution]
 
 🚀 [High-impact theme]
-   • Specific achievement...
+   • Specific achievement [date, refs]
 
 ✅ [Medium-impact theme]
-   • Specific achievement...
+   • ...
 
 🔧 [Lower-impact theme]
    • ...
 
----
 📊 [N] commits across [N] working days
 ```
 
-Group by theme (Features shipped, Reliability, Security, Code review,
-Infrastructure). Only include themes that apply.
-
 ---
 
 ## Mode: init
 
-Ask the user three questions one at a time:
+Ask one at a time:
 
 1. *"What does your company/product do? (1–2 sentences)"*
 2. *"What does your manager care most about?"*
-3. *"Any technical terms to translate? Format: RLS=data security, MFA=login security (leave blank to skip)"*
+3. *"Technical terms to translate? Format: RLS=data security, MFA=login security (blank to skip)"*
 
-Then write `.git-impact/context.json` and tell the user:
-*"Saved to `.git-impact/context.json`. Commit this to share the glossary with
-your team. history.db is gitignored automatically."*
+Then call **`update_context`** with the answers. Tell the user:
+*"Saved to `.git-impact/context.json`. Commit this to share the glossary with your team."*
+
+If the install also wrote slash command files for other editors (Cursor,
+Copilot, Gemini), point that out so they know the same workflow works
+elsewhere.
 
 ---
 
@@ -280,6 +200,11 @@ your team. history.db is gitignored automatically."*
 
 - Write for a non-technical manager. No jargon that isn't in the glossary.
 - Short sentences. No filler. Skip "this change" / "this commit" constructions.
-- Confident — if you know the impact, state it. If not, use
-  "technical foundation work for X", never hedge with "might potentially".
+- Confident — if you know the impact, state it. If you guessed, label
+  `provenance: inferred` and use phrases like "technical foundation work
+  for X". Never hedge with "might potentially".
 - 2 accurate bullets beat 5 vague ones.
+
+For prompt details, anti-patterns, and the full output format, see
+`references/translation-rules.md`. For the bespoke daily HTML, see
+`references/html-template.md`.

package/skill/references/html-template.md

@@ -0,0 +1,131 @@
+# HTML presentation guide
+
+Read this file ONLY when composing today's bespoke HTML presentation. The
+`renderReport` MCP-side renderer handles the rolling dashboard at
+`.git-impact/result.html` automatically — this file is for the *daily artifact*
+the user can share as a screenshot or paste-into-Slack visual.
+
+## Where to write
+
+Use your `Write` tool to create:
+- `<repo>/.git-impact/standups/YYYY-MM-DD.html` — today's bespoke file
+- `<repo>/.git-impact/standups/index.html` — list of all standups (regenerate)
+
+## Stack (all CDN — no install)
+
+| Tool | URL | When to use |
+|---|---|---|
+| Tailwind CSS | `<script src="https://cdn.tailwindcss.com"></script>` | Always |
+| Inter font | `https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap` | Always |
+| Chart.js | `https://cdn.jsdelivr.net/npm/chart.js` | Only if there are real numbers worth charting |
+| Mermaid | `https://cdn.jsdelivr.net/npm/mermaid/dist/mermaid.esm.min.mjs` | Only for architecture/flow diagrams when relevant |
+| Lucide icons | `https://unpkg.com/lucide@latest` | Optional — call `lucide.createIcons()` after DOM ready |
+
+Don't include all of them. Pick what the day's content actually needs.
+
+## Required structure
+
+1. **Hero** — date label + a bold, plain-English headline that captures the day.
+   "Shipped safety analytics, hardened tenant isolation" — NOT "9 commits today".
+2. **Stats grid** — 3-4 metric cards (commits, files, PRs merged, areas touched).
+3. **Achievement cards** — one per ✅ item with status pill, title, summary,
+   "→ Why it matters" line, and small chips: PR #, area, file count, plus an
+   "inferred" chip when the bullet's provenance is `inferred`.
+4. **Optional visual** — only if the content warrants one:
+   - Mermaid flow diagram for architecture/data-flow changes
+   - Chart.js for ratios/comparisons
+   - Code block for a key formula or snippet
+   - Skip entirely if the day was straightforward — don't force visuals.
+5. **Footer** — file count, commit count, branch, link back to `index.html`.
+
+## Design language
+
+- **Theme:** dark by default (`bg-slate-950`), generous spacing, max width 4xl
+- **Cards:** `bg-slate-900/50 border border-slate-800 rounded-2xl p-6`
+- **Status pills:**
+  - ✅ Shipped → `bg-emerald-500/20 text-emerald-400`
+  - ⏳ In Progress → `bg-amber-500/20 text-amber-400`
+  - 🚫 Blocked → `bg-rose-500/20 text-rose-400`
+- **Inferred chip:** `bg-amber-500/10 text-amber-300/70 border border-amber-500/30`
+  with title attribute "Impact inferred — not explicitly stated in PR or commit"
+- **Print-friendly:** include `@media print { ... }` that hides nav and switches to light theme
+- **Spacing:** `max-w-4xl mx-auto px-8 py-12`, `space-y-6` between cards
+- **Typography:** Inter, tight letter-spacing on headlines, 1.6 line-height on body
+
+## Skeleton (adapt content to today's actual work)
+
+```html
+<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8" />
+  <meta name="viewport" content="width=device-width, initial-scale=1" />
+  <title>Standup — [Day, Date] · [Repo]</title>
+  <script src="https://cdn.tailwindcss.com"></script>
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700;800&display=swap" rel="stylesheet">
+  <style>
+    body { font-family: 'Inter', system-ui, sans-serif; }
+    @media print { .no-print { display: none } body { background: white; color: black; } }
+  </style>
+</head>
+<body class="bg-slate-950 text-slate-100 min-h-screen">
+  <div class="absolute inset-0 bg-[radial-gradient(circle_at_top,rgba(56,189,248,0.08),transparent_50%)] pointer-events-none"></div>
+
+  <main class="relative max-w-4xl mx-auto px-8 py-16">
+    <header class="mb-16">
+      <p class="text-sm uppercase tracking-widest text-slate-500 font-medium">[Saturday, May 9, 2026]</p>
+      <h1 class="mt-3 text-5xl font-bold tracking-tight leading-tight">[Headline that captures the day]</h1>
+      <p class="mt-4 text-xl text-slate-400 max-w-2xl">[One-sentence subtitle]</p>
+    </header>
+
+    <section class="grid grid-cols-2 md:grid-cols-4 gap-4 mb-16">
+      <div class="bg-slate-900/50 border border-slate-800 rounded-2xl p-5">
+        <div class="text-3xl font-bold">[N]</div>
+        <div class="text-sm text-slate-400 mt-1">commits</div>
+      </div>
+      <!-- ... 3 more stat cards -->
+    </section>
+
+    <section class="space-y-4 mb-16">
+      <h2 class="text-xs uppercase tracking-widest text-slate-500 font-semibold mb-4">Shipped today</h2>
+      <article class="bg-slate-900/50 border border-slate-800 rounded-2xl p-6">
+        <div class="flex items-start gap-4">
+          <span class="px-2 py-1 rounded-md bg-emerald-500/20 text-emerald-400 text-xs font-medium">✅ Shipped</span>
+          <div class="flex-1">
+            <h3 class="text-lg font-semibold">[Plain-English title]</h3>
+            <p class="text-slate-300 mt-2 leading-relaxed">[One-sentence summary]</p>
+            <p class="text-slate-400 mt-3 text-sm">→ [Why it matters in business terms]</p>
+            <div class="flex gap-2 mt-4 flex-wrap">
+              <span class="text-xs px-2 py-0.5 rounded-full border border-slate-700 text-slate-400">PR #142</span>
+              <!-- Add an inferred chip when provenance === "inferred" -->
+              <span class="text-xs px-2 py-0.5 rounded-full bg-amber-500/10 text-amber-300/70 border border-amber-500/30" title="Impact inferred">inferred</span>
+            </div>
+          </div>
+        </div>
+      </article>
+    </section>
+
+    <footer class="pt-8 border-t border-slate-800 text-sm text-slate-500 flex justify-between">
+      <span>[N] files · [N] commits · [branch]</span>
+      <a href="./index.html" class="hover:text-slate-300">← All standups</a>
+    </footer>
+  </main>
+</body>
+</html>
+```
+
+## Index page
+
+`<repo>/.git-impact/standups/index.html` should list every daily HTML file
+(newest first). Same dark theme, simple grid of cards each linking to its day.
+Keep it lightweight — don't re-render everything, just enumerate files.
+
+## Final line
+
+After writing both files, print exactly this on the LAST line of your reply:
+
+```
+🎯 file:///<repo-absolute-path>/.git-impact/standups/YYYY-MM-DD.html
+```
+
+Use the real absolute path so the user can ⌘-click.

package/skill/references/translation-rules.md

@@ -0,0 +1,87 @@
+# Translation rules
+
+Read this file when translating commits into impact bullets. The main `SKILL.md`
+covers orchestration; this file owns the prompt-engineering details.
+
+## Core rules
+
+1. **What + why, not what + how.** Each bullet must say what was accomplished
+   AND why it matters. "Fixed a bug in the auth middleware" is useless to a
+   manager. "Fixed login failures for admin users — unblocks the Q2 portal
+   launch" is useful.
+
+2. **Apply the glossary.** Replace every term in `context.json`'s `glossary`
+   with its plain-English equivalent. If no glossary exists, infer from
+   context but stay non-jargon.
+
+3. **Provenance is mandatory.** Every bullet you save via `save_impact_entry`
+   MUST include a `provenance` value. Use the strongest source available:
+
+   | Provenance | When to use |
+   |---|---|
+   | `pr` | The "why" came from the linked PR description body |
+   | `commit_body` | The "why" came from a multi-line commit message body (after the subject) |
+   | `commit_message` | The "why" was visible in the commit subject line itself |
+   | `ticket` | The "why" came from a linked Linear/Jira/GitHub issue |
+   | `inferred` | You guessed the impact without explicit text supporting it |
+
+   **Never label something `pr` or `commit_body` if you actually inferred it.**
+   Inferred is honest; faking provenance is worse than admitting a guess.
+
+4. **Group related commits.** Three commits all touching auth tell one story.
+   Write one bullet, not three. The grouping should follow the user's
+   *narrative*, not just shared paths — two commits in `/auth/` may be unrelated.
+
+5. **WIP / draft commits** get `status: "in_progress"` and the bullet should
+   describe the **expected outcome** when complete, not what was done so far.
+   "Refactoring auth flow → will reduce login latency by ~40%" beats
+   "WIP: extracted middleware function".
+
+6. **Blocked work** gets `status: "blocked"`. Use this when a commit is
+   reverted, a branch is abandoned, or the user explicitly says "stuck on X".
+
+7. **Be specific with numbers.** "Improved performance" is vague.
+   "Reduced login latency by ~40%" is specific. Pull numbers from commit
+   messages, PR descriptions, or diff stats. Don't invent them.
+
+8. **Refs help reviewers trust you.** When you have them, populate the `refs`
+   array: `["PR #142", "a1b2c3d", "ENG-1234"]`. These show as small chips in
+   the HTML report and let a reader click through to verify.
+
+## Output format (for the user-facing text reply)
+
+```
+📅 [Day, Date]
+
+✅ [Plain-English summary of what was accomplished]
+   → [Why it matters — who it unblocks, what risk it reduces, what it enables]
+
+⏳ In progress: [What is being worked on]
+   → [Expected outcome when complete]
+
+🚫 Blocked: [What is stuck]
+   → [What's needed to unblock]
+
+📁 [N] files changed across [brief description of areas touched]
+   [N] commit(s) on [branch name]
+```
+
+If a bullet is `inferred`, the HTML report will mark it with an "inferred"
+chip automatically — you don't need to do anything special in the text reply.
+
+## Tone
+
+- Write for a non-technical manager. No jargon that isn't in the glossary.
+- Short sentences. No filler. Skip "this change" / "this commit" constructions.
+- Confident — if you know the impact, state it. If you don't, label it
+  `inferred` and use phrases like "technical foundation work for X". Never
+  hedge with "might potentially" or "could possibly".
+- 2 accurate bullets beat 5 vague ones.
+
+## Anti-patterns
+
+- ❌ Restating commit messages verbatim ("refactor: extract middleware")
+- ❌ Inventing impact you can't ground in the data ("saves 10 hours per week")
+- ❌ Mixing provenance — one bullet pulled from PR + one from inference labeled the same way
+- ❌ Using `done` status when the work is genuinely in progress
+- ❌ Writing 5+ bullets to look productive — pick the 2-3 that actually mattered

package/dist/translator/prompt.d.ts

@@ -1,21 +0,0 @@
-import { GitSummary } from "../readers/git";
-import { GitHubSummary } from "../readers/github";
-import { UserContext } from "../storage/db";
-export interface TranslateInput {
-    git: GitSummary;
-    github: GitHubSummary | null;
-    context: UserContext | null;
-    dateLabel: string;
-}
-export declare function buildPrompt(input: TranslateInput): string;
-export declare function buildReviewPrompt(entries: Array<{
-    date: string;
-    items: Array<{
-        status: string;
-        summary: string;
-        impact: string;
-    }>;
-    totalCommits: number;
-    repoName: string;
-}>, context: UserContext | null, periodLabel: string): string;
-//# sourceMappingURL=prompt.d.ts.map