--- name: client-update-email description: Use when writing a client-facing email summarizing project work. Reads git history + code, drafts a tiered outline by client impact, outputs markdown with optional HTML/screenshots. disable-model-invocation: true --- # Client Update Email Generate a client-facing email summarizing project work. Six phases: gather → outline → fact-check → draft → screenshots → output. ## Inputs Ask the user for these if not already provided in conversation context: - **Scope:** What to compare. Default: `deploy/prod..deploy/stage`. Alternatives: date range, specific PRs, specific commits, or any two git refs. - **Tone:** Formal, informal, friendly-professional, or custom description. - **Language:** English, Czech, or other. ## Phase 1 — Deep Gather ### Step 1: Get change list Run these commands, adapting refs to the user's scope: - Commit list: !`git log deploy/prod..deploy/stage --oneline --no-merges 2>/dev/null || echo "SCOPE_ERROR: adjust refs"` - Diff stat: !`git diff deploy/prod..deploy/stage --stat 2>/dev/null || true` - Merged PRs: !`gh pr list --state merged --limit 50 --json number,title,body,url 2>/dev/null || true` If the default refs don't exist, ask the user which branches or refs to compare. ### Step 2: Deep-read each change For each PR or logical group of commits: 1. Read the full diff for that change (`git diff -- `). 2. Read the source files that changed — components, routes, handlers, templates — enough to understand the feature in context. 3. Read PR descriptions and linked issues (`gh issue view `) if available. 4. Synthesize an internal summary per change: - What it does from the **client's perspective** (not the developer's) - Which part of the app it touches - Which routes/pages/URLs are involved (save these for Phase 4 screenshots) - How visible the change is to the client Spend time here. Read the code. Understand what was built, not just what files changed. ### Step 3: Present raw list Show the synthesized list to the user: ``` Found N changes: 1. [Short name] — [What it does for the client]. Touches [area]. Route: /path 2. [Short name] ��� [What it does for the client]. Touches [area]. Route: /path ... ``` Ask: **"Anything missing or wrong? You can add changes that aren't in git (design work, config changes, manual deployments)."** Wait for confirmation before proceeding to Phase 2. ## Phase 2 — Editable Outline ### Tiering Group and tier the confirmed changes by **client-perceived impact** — not code complexity, not diff size: - **Big:** Things the client will notice or asked for. New features, visible UI changes, workflow changes. A one-line copy change on the homepage can be "big." A 500-line refactor the client never sees is not. - **Medium:** Improvements that affect their experience but aren't headline items. Performance gains, UX polish, minor new capabilities. - **Small:** Worth mentioning but not dwelling on. Bug fixes, stability improvements, behind-the-scenes work. ### Grouping Cluster related changes under a single heading. Three commits touching export become one "Export improvements" item. ### Present the outline ``` ## Big Changes - [Feature Name] — 1-line description of what it does for the client - [Feature Name] — ... ## Medium Changes - [Feature Name] — ... ## Small Changes - [Fix/improvement] — ... ``` Tell the user they can: - **Move** items between tiers - **Remove** items entirely - **Reorder** items within a tier - **Rename** or rewrite descriptions - **Add** items not in the original list Wait for the user to approve the outline before proceeding to Phase 3. ## Phase 2.5 — Fact-Check Before Drafting Before writing any client-facing draft, fact-check the approved outline against source evidence. ### Claim ledger Create a claim ledger for every substantive statement you plan to put in the email: ``` Claim: [exact user-facing claim] Evidence: [file:line, PR text, issue, screenshot, config, or user-provided fact] Confidence: high | medium | low Action: keep | narrow wording | remove | ask user ``` Rules: - Every claim about a UI label, button, badge, icon, role, route, page, filter, automation, or workflow must have direct evidence from code, PR metadata, screenshots, docs, or explicit user confirmation. - Inspect the actual rendering component, not only shared label files. A label string existing in code does not prove it appears on the page being described. - Prefer exact surfaces over broad phrasing. Say "main activity calendar" only if that specific page is verified; do not say "calendars" unless every relevant calendar is verified. - For role/permission claims, read the role guard or permission helper and name only verified roles. - For filtering/visibility claims, inspect both the list/page query and the detail/project view that supposedly remains visible. - Do not mention tests, backend side effects, performance, refactors, CI, or internal stabilization unless the user asked to include them or they are client-visible. - If a claim has no evidence or only weak inference, narrow it to what is proven or remove it before drafting. - If the user corrects a claim, treat that as a required fact and re-check the affected section before continuing. After the ledger is clean, write the markdown draft. Do not write a draft with unresolved low-confidence claims. ## Phase 3 — Draft Generation Create the output directory: ```bash mkdir -p client-updates/screenshots ``` Write the email as markdown to `client-updates/-update.md` using the approved outline. ### Email structure Follow this structure exactly. Apply the user's chosen **tone** and **language** consistently throughout. ``` # What's New — [date or period] [Opening paragraph — friendly summary of the update, 1-2 sentences.] ## Big Changes ### [Feature Name] [2-3 sentences: what it does and why it matters to the client.] **Where to find it:** [Navigation path, URL, or description — whatever communicates clearest] [Screenshot: — ] --- ### [Next Feature] ... ## Medium Changes ### [Feature Name] [1-2 sentences.] **Where to find it:** [Navigation path or URL] [Screenshot: — ] ← only if the change is visual --- ## Small Changes - **[Name]** — one-line description - **[Name]** — one-line description [Closing line — tone-appropriate sign-off.] ``` ### Rules - Big changes: full treatment — description + where to find it + screenshot placeholder. - Medium changes: description + where to find it. Screenshot placeholder only if the change is visual. - Small changes: bullet list only. No screenshots, no "where to find it." - No emojis unless the chosen tone calls for them. - Screenshot placeholders use the format: `[Screenshot: filename.png — description of what to capture]` ### Draft fact-check Before showing the draft to the user: 1. Read the generated markdown line by line. 2. Match each substantive sentence back to the claim ledger. 3. Remove or rewrite anything broader than the evidence. 4. Verify screenshot placeholder wording against actual UI states; avoid saying "badge", "tab", "button", "modal", or a specific label unless that exact UI exists. After writing the draft, show it to the user. Wait for approval or edits before proceeding to Phase 4. ## Phase 4 — Screenshot Capture ### Step 1: Dev server Check if a local dev server is already running by testing common ports (3000, 3001, 5173, 8080): ```bash lsof -i :3000 -i :3001 -i :5173 -i :8080 -sTCP:LISTEN 2>/dev/null ``` If not running, figure out how to start it. Check these sources in order: 1. **CLAUDE.md / AGENTS.md / README.md** — often has "how to run" instructions, dev URLs, docker-compose commands 2. **docker-compose.yml / docker-compose.dev.yml** — if the project uses Docker, run `docker compose up` (or the specific service) 3. **Makefile** — look for `dev`, `serve`, `run` targets 4. **package.json** — look for `dev`, `start`, or `serve` scripts 5. **.env / .env.local** — may contain `PORT` or `BASE_URL` hints Start the dev server using whatever method the project uses. Wait for it to be ready before proceeding. If unsure which method is correct, ask the user. ### Step 2: Plan captures For each screenshot placeholder in the draft, propose a capture plan. Use the route and component knowledge from Phase 1: ``` Screenshot captures: 1. [filename.png] — Navigate to http://localhost:/path → click "Tab Name" → scroll to section 2. [filename.png] — Navigate to http://localhost:/other-path → open modal via "Button Text" ... ``` The skill already knows which routes and components are involved from the Phase 1 deep-read. Use that knowledge to plan the navigation steps. Ask user to **confirm or adjust** the capture plan. Some screenshots may need specific data or login state — the user should flag these. ### Step 3: Execute captures For each planned screenshot, use browser automation tools: 1. Navigate to the URL on the local dev server. 2. Perform click, scroll, wait, or other interaction steps to reach the right visual state. 3. Capture a screenshot. 4. Save to `client-updates/screenshots/.png`. ### Step 4: Review Show the user which screenshots were captured and their file paths. The user can: - Ask to **recapture** any that aren't good enough (different viewport, different state, etc.) - **Skip** any and replace manually later - **Accept** and move to output Wait for approval before proceeding to Phase 5. ## Phase 5 — Output ### Generate HTML Convert the markdown draft to HTML. The HTML must look like a **normal composed email** — not a newsletter, not a marketing template. Styling rules: - Inline all CSS (email clients strip `