菜单
Use when a semantic-release-published GitHub release has terse bucket bullets or a spurious "closes [URL-fragment]" autolink that needs to be rewritten with proper narrative drawn from commit bodies and PR descriptions
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
基于 SOC 职业分类
Explore requirements and approaches through collaborative dialogue before writing a right-sized requirements document and planning implementation. Use for feature ideas, problem framing, when the user says 'let's brainstorm', or when they want to think through options before deciding what to build. Also use when a user describes a vague or ambitious feature request, asks 'what should we build', 'help me think through X', presents a problem with multiple valid solutions, or seems unsure about scope or direction — even if they don't explicitly ask to brainstorm.
Create structured plans for any multi-step task -- software features, research workflows, events, study plans, or any goal that benefits from structured breakdown. Also deepen existing plans with interactive review of sub-agent findings. Use for plan creation when the user says 'plan this', 'create a plan', 'write a tech plan', 'plan the implementation', 'how should we build', 'what's the approach for', 'break this down', 'plan a trip', 'create a study plan', or when a brainstorm/requirements document is ready for planning. Use for plan deepening when the user says 'deepen the plan', 'deepen my plan', 'deepening pass', or uses 'deepen' in reference to a plan.
Structured code review using tiered persona agents, confidence-gated findings, and a merge/dedup pipeline. Use when reviewing code changes before creating a PR.
Use when starting any conversation - establishes how to find and use skills, requiring skill tool invocation before ANY response including clarifying questions
Refresh stale or drifting learnings and pattern docs in docs/solutions/ by reviewing, updating, consolidating, replacing, or deleting them against the current codebase. Use after refactors, migrations, dependency upgrades, or when a retrieved learning feels outdated or wrong. Also use when reviewing docs/solutions/ for accuracy, when a recently solved problem contradicts an existing learning, when pattern docs no longer reflect current code, or when multiple docs seem to cover the same topic and might benefit from consolidation.
Document a recently solved problem to compound your team's knowledge
| name | release-notes-narrative |
| description | Use when a semantic-release-published GitHub release has terse bucket bullets or a spurious "closes [URL-fragment]" autolink that needs to be rewritten with proper narrative drawn from commit bodies and PR descriptions |
| argument-hint | <tag-or-range> |
This skill also runs automatically post-publish via @semantic-release/exec's successCmd in .releaserc.yaml. The hook dispatches fro-bot.yaml with a prompt that loads this skill and applies the 13-step procedure against the just-published tag. Manual invocation remains the canonical path for retroactive patches and historical releases; CI automation handles forward-going releases without operator intervention.
If you are reading this as the dispatched Fro Bot run, the prompt embedded the target tag and a correlation token. Echo the correlation token as your first log line, then proceed with the procedure below.
@semantic-release/release-notes-generator with the conventionalcommits preset builds release bodies from commit subject lines only — commit bodies and PR descriptions are never ingested. The result is mechanically correct but qualitatively thin: a bucket of one-line bullets that tells readers what changed but not why it matters. The same generator also misparses any path#fragment substring in a commit body as a Closes #N footer, emitting broken autolinks pointing at nonexistent issues.
This skill replaces the auto-generated body with AI-assisted narrative drawn from the commit log and, when the commit body is thin, from the PR description. It applies the patch via gh release edit --notes-file against an already-published release.
Core principle: The commit log is the authoritative source. Every claim in the rendered body must trace to a commit SHA, commit body, or PR description in the range. Do not invent context.
Overwrite behavior: This procedure always overwrites the existing release body unconditionally. If the release body contains manually-authored regions, those regions are replaced. Capture the pre-edit snapshot (procedure step 3) before running so you can restore it if needed.
* **ci:** add OpenCode group name to Renovate config (#425)) with no explanatory prosecloses [URL-fragment] autolink (e.g., closes [fro.bot/.../typed-validation](https://github.com/fro.bot/systematic/reference/configuration/issues/typed-validation)) generated by semantic-release misparsegit describe --tags --abbrev=0 v<target>^. If that command returns nothing, the procedure cannot run.$ARGUMENTS
<tag> — Target release tag (e.g., v2.20.6). The previous tag is resolved automatically.<prev>..<tag> — Explicit range. Use when the automatic previous-tag resolution would be wrong (e.g., a hotfix branched from an older tag).git describe --tags --abbrev=0).The following map is mirrored from .releaserc.yaml:46-70. If the preset config changes, update this table in the same PR.
| Conventional type | Section heading |
|---|---|
feat | Features |
fix | Bug Fixes |
build | Build System |
docs | Documentation |
test | Tests |
ci | Continuous Integration |
style | Styles |
refactor | Code Refactoring |
perf | Performance Improvements |
revert | Reverts |
chore | Miscellaneous Chores |
PR-body enrichment triggers when a release contains exactly one commit AND the parsed commit body (after stripping conventional-commit footers) is fewer than 200 non-whitespace characters.
Calibration basis — commit-body lengths (post footer-strip) across the v2.18.0..v2.21.0 range (29 commits):
| Non-whitespace chars | Count | Examples |
|---|---|---|
| 0 | 7 | fix(ci): add OpenCode group name to Renovate config (#425), fix(docs): modernize architecture guide (#422) |
| 80 | 11 | Renovate dependency-update boilerplate (build(dev): update all non-major dependencies (#414)) |
| 137 | 1 | docs(solutions): capture OpenCode plugin hook silent-defect-swallow pattern (#413) |
| 360–8651 | 10 | Real narrative bodies (feat: launch-surface cleanup (#428), feat(skills): deprecation surface (#401)) |
The natural break falls between 137 and 360. The 200-char threshold correctly classifies all 0/80/137-char commits as "thin" (PR enrichment appropriate) and all 360+-char commits as "rich" (commit body is sufficient). No commit in the calibration set falls in the 138–359 gap.
Read $ARGUMENTS. If empty, resolve the latest tag:
git describe --tags --abbrev=0
Call the result TARGET (e.g., v2.20.6).
git describe --tags --abbrev=0 "${TARGET}^"
This returns the most recent ancestor tag of the target's parent commit — the chronological predecessor regardless of when other tags were created. Call the result PREV (e.g., v2.20.5). If the command produces no output, stop and report: the target has no semver ancestor and the procedure cannot run.
mkdir -p .context/pr-evidence/release-notes-narrative
gh release view "${TARGET}" --json body --jq .body \
> ".context/pr-evidence/release-notes-narrative/${TARGET}-before.md"
This snapshot is the rollback source for procedure step 13. The .context/ directory is gitignored; the file is PR evidence only.
git log "${PREV}..${TARGET}" --pretty=format:'%H%x1f%s%x1f%b%x1e'
Split on the Record Separator (\x1e) to get per-commit records. Within each record, split on the Unit Separator (\x1f) to extract (sha, subject, body). Note: if any real commit body contains a literal \x1e byte, parsing will corrupt that record. No commit in this repo's history contains that byte; this is an acceptable limitation for now.
If the range contains zero commits, skip to step 8 and emit only the Compare link section.
Apply the conventional-commits regex to subject:
^(?<type>\w+)(?:\((?<scope>[^)]+)\))?(?<bang>!)?:\s+(?<subject>.+)$
Extract type, scope (optional), bang (breaking-change marker, optional), and subject.
Strip the commit body of conventional-commit footers by truncating at the first line that matches any of: ^BREAKING CHANGE:, ^Closes\s, ^Fixes\s, ^Refs\s, ^Co-authored-by:, ^Signed-off-by:. The remaining text is the prose body.
If the range contains exactly one commit AND the prose body (post-strip) contains fewer than 200 non-whitespace characters:
Extract the PR number from the squash subject (the trailing (#NNN) pattern). Then fetch the PR body:
gh pr view <NNN> --json body --jq .body
Use the PR body as enrichment alongside the commit body when synthesizing narrative in step 8.
Map each commit's type to a section heading using the bucket map above. Commits whose type does not appear in the map are grouped under Miscellaneous Chores. Commits with bang: true or a BREAKING CHANGE: footer are flagged as breaking and must appear prominently — either in their type bucket with a > **Breaking change:** callout, or in a dedicated ### Breaking Changes section at the top.
For each non-empty bucket, write a ### <Section Heading> block followed by one or more prose paragraphs. Draw from the structured commit data: type, scope, subject, prose body, and any PR enrichment from step 6. Explain what changed and why it matters — not just what the commit subject says.
Buckets with only dependency-update or boilerplate commits (e.g., Renovate build(dev) bumps, chore(deps) updates) do not warrant individual narrative paragraphs. Collect them into a ### Also in this release tail section as a compact bullet list.
Zero-commit edge case: Emit only the Compare link section (step 9) with a note that no commits were found in the range.
Append a ### Compare section:
### Compare
[v<PREV>...v<TARGET>](https://github.com/marcusrbrown/systematic/compare/v<PREV>...v<TARGET>)
Apply the autolink allowlist rules documented in references/autolink-allowlist.md. Parse the rendered body as a markdown AST; walk link nodes; strip any link that matches all four conditions in that document. Do not use a raw-string regex sweep over the body.
Before calling gh release edit, assert all of the following against the rendered body in the temp file. If any check fails, stop — do not apply the edit. Surface the failures and wait for operator review.
``` has a closing ```)Write the rendered body to a temp file and apply:
TMPFILE=$(mktemp /tmp/release-notes-XXXXXX.md)
# ... write rendered body to $TMPFILE ...
gh release edit "${TARGET}" --notes-file "${TMPFILE}"
rm -f "${TMPFILE}"
Re-read the published body and verify it structurally:
PUB=$(gh release view "${TARGET}" --json body --jq .body)
Assert:
## What's newDo NOT compare lengths. A narrative rewrite is routinely SHORTER than the auto-generated body it replaces — semantic-release inflates major-release bodies by embedding entire squash-commit prose under BREAKING CHANGES (v3.0.0: 11,048 chars raw vs 4,394 chars narrative), and a length gate rolls back exactly the rewrites that matter most. Structural presence of the render contract, not size, is the correctness signal.
If any assertion fails, restore the pre-edit snapshot:
gh release edit "${TARGET}" \
--notes-file ".context/pr-evidence/release-notes-narrative/${TARGET}-before.md"
Then report the failure. Do not silently leave a broken release body in place.
The rendered body must follow this shape:
## What's new
### <Bucket Heading>
<Narrative paragraph(s) explaining what changed and why it matters.>
### <Bucket Heading>
<Narrative paragraph(s).>
### Also in this release
- **deps:** Renovate bumps and minor dependency updates.
### Compare
[v<PREV>...v<TARGET>](https://github.com/marcusrbrown/systematic/compare/v<PREV>...v<TARGET>)
The ## What's new heading is required. Bucket headings use ###. The Compare link is always last. The ### Also in this release section is optional — include it only when there are boilerplate commits not covered by narrative buckets.
See references/historical-corpus.md for the v2.20.5, v2.20.6, and v2.21.0 anchor shapes.
Re-running the procedure against the same (PREV, TARGET) pair with the same commit range contents produces:
Narrative prose wording may vary between runs due to LLM nondeterminism. To verify structural idempotence, run the normalizer:
# Strip prose paragraphs; retain headings, bullet lists, and the Compare link.
# Apply to both run outputs, then diff the normalized forms.
grep -E '^#{1,4} |^\* |^\- |\[v[0-9]' <output-file> > normalized.txt
The normalized forms of two runs against the same range must be byte-identical.
v<PREV>...v<TARGET> format and points at github.com/marcusrbrown/systematiccloses [URL-fragment] autolinks remain after step 10.context/pr-evidence/release-notes-narrative/${TARGET}-before.md before gh release edit is called| Mistake | Fix |
|---|---|
Using git tag --sort=-creatordate | head -1 to find the previous tag | Use git describe --tags --abbrev=0 "${TARGET}^" — tag sort order is not the same as commit ancestry |
Calling gh release edit before the preflight check passes | Step 11 is a hard gate; never skip it |
| Regex-sweeping the raw body for autolinks | Parse as markdown AST (step 10); raw regex produces false positives on multiline content |
| Omitting the Compare link | It is required by the render contract and checked in both preflight (step 11) and post-edit verification (step 13) |
| Running on a release with manually-authored regions without reading the pre-edit snapshot first | The procedure overwrites unconditionally; read the snapshot before running on any release you did not generate |
| Carrying over bucket headings from a previous run without re-deriving from the commit range | Re-derive buckets from git log every run; the range contents are the source of truth |