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) <noreply@anthropic.com>
This commit is contained in:
Tobias Gesellchen
2026-06-28 17:44:20 +02:00
co-authored by Claude Opus 4.8
parent d154d459c6
commit 4aad9fbcf0
+45 -10
View File
@@ -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 <tag>`. 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 (35 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: 300600 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: 300600 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 '—' <file>` 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.