From 4aad9fbcf0cf947266811169ff1e90426f5e357e Mon Sep 17 00:00:00 2001 From: Tobias Gesellchen Date: Sun, 28 Jun 2026 17:35:52 +0200 Subject: [PATCH] docs(blog): fix /blog-update skill (footer convention, no-push, narrative) - Close every post with the established footer convention (## Current release + dated release line + subscribe note), and never restyle already-published posts to fit a new convention. - Prefer a narrative over a bare release-note aggregation. - Forbid em dashes (with a grep check). - Allow an explicit tag/date argument to override lookback detection. - Stop the skill from pushing or opening the PR itself: commit to a branch and hand the maintainer the push + PR commands (maintainer always pushes over SSH). Co-Authored-By: Claude Opus 4.8 (1M context) --- .claude/commands/blog-update.md | 55 +++++++++++++++++++++++++++------ 1 file changed, 45 insertions(+), 10 deletions(-) diff --git a/.claude/commands/blog-update.md b/.claude/commands/blog-update.md index 8058c30..bd550db 100644 --- a/.claude/commands/blog-update.md +++ b/.claude/commands/blog-update.md @@ -1,8 +1,13 @@ -Draft a "News & Updates" blog post for AfterTouch covering recent git activity, then open a draft PR for review. +Draft a "News & Updates" blog post for AfterTouch covering recent git activity, commit it to a branch, and hand the maintainer the commands to push and open a draft PR (the maintainer pushes, not you). ## Step 1 — Determine lookback window -Run: +If the invocation arguments name an explicit starting point (a tag like `v0.93.1` or a +date), use that as SINCE. For a tag, resolve its date: +`git log -1 --format=%ad --date=short `. An explicit argument always overrides the +auto-detection below. + +Otherwise, auto-detect from the last published post: ``` git log --format="%ad" --date=short -- docs/content/blog/ | grep -v '_index' | head -1 ``` @@ -63,25 +68,55 @@ sidebar: Body structure: 1. Opening paragraph (3–5 sentences) explaining what happened and why it matters to someone running AfterTouch. -2. One `##` section per non-empty category. Use bullet points written for an operator audience — no raw git subjects, no internal Go package paths. -3. End with: `**Current release:** vX.Y.Z` +2. The body. Prefer a narrative that ties the changes into a story (what shifted, why it matters), not a bare aggregation of the release notes. Group related work under `##` sections (the commit categories are raw material, not the final headings). Write for an operator audience: no raw git subjects, no internal Go package paths. A short bullet list inside a section is fine, but the post should read like prose, not a changelog dump. +3. Close with the standard footer convention used by the existing posts, so every post ends the same way: -Target length: 300–600 words. Never include real IPs, MAC addresses, account IDs, or device names. + ```markdown + ## Current release -## Step 6 — Create a branch and open a draft PR + **vX.Y.Z**, released MONTH D, YYYY + + This blog will be updated monthly, or whenever something significant ships. + Subscribe to the [GitHub releases](https://github.com/gesellix/Bose-SoundTouch/releases) + for individual version notes. + ``` + + Get the release date with `git log -1 --format=%ad --date=format:'%B %-d, %Y' vX.Y.Z`. + When in doubt about any recurring element (footer, release line, tags), match the most + recent existing post under `docs/content/blog/` rather than inventing a new convention. + Never retrofit or restyle already-published posts to fit a new convention — they are + dated records; a new convention applies going forward only. + +Target length: 300–600 words (longer is fine when the story warrants it). Never include +real IPs, MAC addresses, account IDs, or device names. + +**No em dashes.** Do not use the em dash character (`—`) anywhere in the post; use commas, +parentheses, colons, or separate sentences. (En dashes in a period label like +`April – May 2026` are fine.) Verify with `grep -c '—' ` before committing. + +## Step 6 — Create a branch and commit (do NOT push) ```bash git checkout -b blog/YYYY-MM-update git add docs/content/blog/YYYY-MM-slug.md git commit -m "docs(blog): add PERIOD update post" +``` + +**Do not push and do not open the PR yourself.** The maintainer always pushes over SSH +(see the global and project instructions). Pushing on their behalf, including over HTTPS +with a token or by switching the remote, is not allowed. + +## Step 7 — Done + +Hand the maintainer the ready-to-run commands to push and open the draft PR, then stop: + +```bash git push -u origin blog/YYYY-MM-update gh pr create --draft \ --title "Blog: PERIOD update post" \ - --body "Automated draft from /blog-update skill. Review content before merging — deployment is automatic on merge to main." + --body "Update post covering recent changes. Review content before merging — deployment is automatic on merge to main." ``` If the `documentation` label exists on the repo, add `--label documentation`. -## Step 7 — Done - -Report the PR URL. Do not merge, approve, or request review. +Do not merge, approve, or request review.