changelog · diff
git:20260720.e99f6c4 to git:20260807.fac9f85
82 added, 72 removed. Audit A to A.
---
name: changelog
- description: Generate a weekly social changelog card from git history and an HTML template. Use when turning recent shipped work into a screenshot-ready update.
+ description: Turn a verified git range into audience-appropriate changelog copy and optional visual assets. Use when preparing weekly updates, release summaries, or social changelog cards.
license: MIT
---
- Generate the weekly changelog Twitter card. Run every Friday (or whenever you ship).
+ # Changelog
- ## Steps
+ Translate a clearly defined change range into truthful release communication. Let the amount and importance of shipped work determine the item count, technical depth, and visual format.
- ### 1. Get this week's commits
+ ## Establish scope
+
+ Infer from the request and repository:
+
+ - target branch, tag range, release, or date window;
+ - whether uncommitted or unreleased work is excluded;
+ - audience and expected technical depth;
+ - output: prose, Markdown, HTML card, image, or a combination;
+ - existing changelog policy, template, visual system, and prior examples.
+
+ Ask only when the range or release status remains ambiguous. Record the exact range in the handoff. Do not describe merged, committed, or feature-flagged work as live without deployment evidence.
+
+ ## Inspect what changed
+
+ Start with repository-native release tooling when present. Otherwise inspect the chosen range:
+
```bash
- git log --oneline --since="7 days ago"
+ git log --oneline <range>
+ git diff --stat <range>
+ git diff --name-status <range>
```
- Get the stats:
- ```bash
- # Commit count
- git log --oneline --since="7 days ago" | wc -l
+ Read unclear diffs and relevant tests or documentation. Group commits by user-visible behavior rather than commit boundaries.
- # Files + lines changed
- git log --since="7 days ago" --pretty=tformat: --numstat | awk '{files++; add+=$1; del+=$2} END {print files " files · " add+del " lines"}'
- ```
+ Include internal changes when they affect compatibility, security, reliability, performance, migration, or operator behavior. Exclude churn that has no consequence for the intended audience.
- ### 2. Understand what actually shipped
- Read each commit message. For any that are unclear, look at the diff:
+ For each candidate item, capture:
+
+ - user or operator impact;
+ - evidence commits or diff paths;
+ - release status;
+ - breaking, migration, security, or limitation details;
+ - confidence and any missing deployment evidence.
+
+ ## Draft for the audience
+
+ Use as many items as the range supports. Combine changes only when they form one coherent outcome; do not pad the update to fill a layout.
+
+ Each item should answer what changed and why the audience cares. Include implementation language when readers need it to adopt, debug, migrate, or evaluate the release.
+
+ Preserve the product's voice and capitalization. Do not force lowercase, emoji, slogans, or benefit-only language. If icons or category labels are part of an existing template, use them consistently and accessibly.
+
+ Call out breaking changes and required actions beside the affected item. Keep unverified deployment claims out of published copy and report them separately.
+
+ ## Calculate truthful statistics
+
+ Use metrics only when they help and label exactly what they count. Avoid presenting changed-file entries across commits as unique files.
+
+ For unique files in a git range:
+
```bash
- git show [commit-hash] --stat
+ git diff --name-only <range> | sort -u | wc -l
```
- Group commits into themes. Ignore pure refactors, dependency bumps, and test fixes — users don't care. Focus on what changed for them.
- ### 3. Distill into exactly 6 items
- Each item needs:
- - **An emoji** that fits the work (✨ new feature, 🐛 fix, ⚡ performance, 🎨 design, 🔒 security, etc.)
- - **A short title** — 3-5 words, lowercase, punchy
- - **2-3 lines of body** — explain the user benefit, not the technical detail. Write like a human, not a release note. "credits update in real time" not "implemented shared zustand store for credit synchronisation."
+ Use `git diff --numstat <range>` for added/deleted text lines, accounting for binary entries. A commit count, unique-file count, or changed-line count is not a proxy for user value.
- If fewer than 6 meaningful things shipped, combine small related items or include one "under the hood" item about stability/performance.
+ ## Build a visual artifact conditionally
- ### 4. Find or create the changelog template
- Look for a `changelogs/` directory in the repo. If there's a `template.html`, use it.
+ If the user requests a card or the repository has an established changelog template:
- If no template exists, create `changelogs/template.html` with this structure:
- ```html
- <!DOCTYPE html>
- <html>
- <head>
- <meta charset="UTF-8">
- <style>
- * { margin: 0; padding: 0; box-sizing: border-box; }
- body {
- width: 1200px; height: 628px; overflow: hidden;
- background: #09090b; font-family: 'JetBrains Mono', ui-monospace, monospace;
- display: flex; flex-direction: column; padding: 48px;
- }
- .header { color: #71717a; font-size: 13px; margin-bottom: 32px; letter-spacing: 0.05em; }
- .header span { color: #fafafa; }
- .grid { display: grid; grid-template-columns: 1fr 1fr; gap: 20px; flex: 1; }
- .item { display: flex; gap: 12px; }
- .emoji { font-size: 18px; flex-shrink: 0; margin-top: 1px; }
- .content h3 { color: #fafafa; font-size: 13px; font-weight: 700; margin-bottom: 4px; }
- .content p { color: #71717a; font-size: 11px; line-height: 1.6; }
- .content p strong { color: #a1a1aa; }
- .footer { color: #3f3f46; font-size: 11px; margin-top: 24px; letter-spacing: 0.05em; }
- </style>
- </head>
- <body>
- <div class="header">what shipped this week · <span>MONTH DAY</span></div>
- <div class="grid">
- <div class="item"><div class="emoji">EMOJI</div><div class="content"><h3>TITLE</h3><p>BODY LINE 1<br>BODY LINE 2<br><strong>BODY LINE 3</strong></p></div></div>
- <!-- repeat 5 more times -->
- </div>
- <div class="footer">N commits · N files · N lines · all live</div>
- </body>
- </html>
- ```
+ 1. inspect existing assets, CSS, dimensions, and prior output;
+ 2. preserve locked template code unless the user requested a design change;
+ 3. choose a layout that fits the actual item count and copy length;
+ 4. create the dated artifact using the repository's naming convention;
+ 5. render or capture it at the target dimensions.
- ### 5. Create this week's file
- Create `changelogs/YYYY-MM-DD.html` (use today's date).
+ When no template exists, derive typography, color, and attribution from repository brand evidence. Do not default to a dark monospace card. Build semantic HTML, keep text selectable where appropriate, and support the requested capture tool and operating system.
- Fill in:
- - Header date (e.g. "what shipped this week · march 1")
- - All 6 items
- - Footer stats from step 1
+ If the desired platform or dimensions are unclear and affect composition, ask or provide a sensible explicitly labelled format.
- ### 6. Open in browser
- ```bash
- open changelogs/YYYY-MM-DD.html
+ ## Output contract
+
+ Deliver the requested artifact plus:
+
+ ```text
+ Range: [commits/tags/dates and branch]
+ Audience and channel: [who/where]
+ Release status: [verified live, released, unreleased, or mixed]
+ Items: [final count]
+ Provenance: [item -> commits or paths]
+ Statistics: [definitions and values, if used]
+ Artifacts: [paths and dimensions]
+ Limitations: [deployment or content facts not verified]
```
- Tell the user: "ready — screenshot the browser window (⌘+Shift+4 on Mac) and post it."
+ For a prose-only request, do not create HTML. For an audit request, stop at findings and proposed copy unless the user also asked for edits.
- ## Voice
- Lowercase. Direct. No buzzwords. User benefit first, technical detail never. If you can't explain the value to a non-engineer in one line, rewrite it.
+ ## Verify
- ## Design rule
- If using an existing template — never touch the CSS. Content only. The design is locked.
+ 1. Re-check every claim against the selected range and release evidence.
+ 2. Confirm no meaningful breaking, security, compatibility, or migration change was hidden by the “user-facing” filter.
+ 3. Confirm combined items describe one outcome and no item exists merely to fill space.
+ 4. Recompute any statistics with commands that match their labels and handle binary files.
+ 5. Validate dates, product names, links, versions, and attribution.
+ 6. Render visual artifacts at target dimensions and inspect overflow, clipping, contrast, hierarchy, and long-item behavior.
+ 7. Open the actual output using an available tool or provide a render path; do not rely on manual screenshot instructions as verification.
+ 8. Report whether deployment/live status was directly verified or inferred.