Improve upstream-release-docs skill: gap-hardening and workflow cleanup#917
Merged
Conversation
The skill was good at turning a release delta into new sections but
blind to what a release makes false and to whether a section covers
the feature's full surface. Add three reinforcing guards:
- Displacement audit (Phase 3): for a feature that extends or
replaces an existing capability, grep the displaced concept's
vocabulary and exclusivity/temporal phrasing ("only", "currently
implements", "is planned") to find statements the release now
falsifies. Flag purely-additive (+N/-0) prose edits as a smell.
Extend the Phase 5 re-verify pass beyond changed files.
- Completeness pass (Phase 2 + Phase 5): inventory the new public
surface (fields, flags, enum values, config keys, routes) and
verify each symbol is documented or consciously deferred. Accuracy
checks never catch omissions.
- Extend-existing bias (Phase 4): prefer adding a section to an
existing page over a standalone page when a feature extends a
documented capability, with a density guard for when to split a
section out instead.
Also consolidate the unattended-mode contract into a new Execution
modes section so the skill owns the GAPS.md / SUMMARY.md /
NO_CHANGES.md formats instead of duplicating them in the workflow,
with explicit interactive-mode gating so a local run never writes
those handoff artifacts.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
- The generation prompt duplicated the unattended-mode and artifact contracts now owned by the skill's Execution modes section. Replace ~100 lines with a pointer to the skill, keeping only environment- specific bits (clone path, auto-generated reference paths). Add a sync-point comment where the bash reads GAPS/SUMMARY/NO_CHANGES so the filename contract with the skill doesn't silently drift. - A recent review pass skipped formatting, claiming it needed npm ci approval and that CI would lint instead. Both were wrong: dependencies are pre-installed by an earlier step, and lint/format CI checks do not run on bot-pushed commits. Tell both prompts deps are installed, to run the linters directly, and not to defer to a CI pass that never runs. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the upstream-release-docs automation by (1) hardening the skill’s methodology to catch contradictions and omissions introduced by upstream releases, and (2) simplifying the GitHub Actions workflow prompts so the skill’s “Execution modes” section becomes the single source of truth for unattended behavior and handoff artifacts.
Changes:
- Refactors the workflow prompt to delegate unattended-mode contracts (GAPS/SUMMARY/NO_CHANGES) to the skill doc and to explicitly run format/lint locally (not via CI).
- Adds an “Execution modes” section to the skill and expands the skill workflow with displacement auditing, completeness checks, and an extend-existing bias for doc placement.
- Extends Phase 5 validation guidance to include repo-wide contradiction checks and completeness verification against an inventoried public surface.
Reviewed changes
Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.
| File | Description |
|---|---|
.github/workflows/upstream-release-docs.yml |
Simplifies and de-duplicates generation/review prompts; reinforces unattended-mode + local lint/format expectations. |
.claude/skills/upstream-release-docs/SKILL.md |
Adds execution-mode contract and strengthens audit/validation phases to catch contradictions and omissions. |
Condense four ballooned Key Principles into mnemonics that point at their phases, dropping recap that duplicated the phase bodies. Replace em dashes in the artifact templates with the list-style spaced hyphens the skill's own style rule sanctions. Scope the unattended decision-point header to Phase 2 step 4 only; step 5 already carries its own inline unattended guidance. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
rdimitrov
approved these changes
Jun 4, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Improvements to the
upstream-release-docsskill and its CI workflow, prompted by reviewing how #915 documented the CIMD feature: it added an accurate new section but left several existing pages asserting DCR as the only client-registration method, which the release made false.The skill was good at turning a release delta into new sections but blind to two things: what a release makes false in existing prose, and whether a new section actually covers the feature's full surface. Three reinforcing guards address that:
+N / -0) prose edits are flagged as a smell, and the Phase 5 re-verify pass now extends beyond changed files.Also consolidates the unattended-mode contract into a new "Execution modes" section so the skill owns the
GAPS.md/SUMMARY.md/NO_CHANGES.mdformats instead of duplicating them in the workflow YAML, with explicit interactive-mode gating so a local run never writes those handoff artifacts.On the workflow side: the generation prompt drops ~100 duplicated lines in favor of a pointer to the skill, and both prompts now tell the model that dependencies are pre-installed, to run the linters directly (not
npm ci), and not to defer to CI lint, which doesn't run on bot-pushed commits.Type of change
Related issues/PRs
Notes for reviewers
SKILL.mdand the workflow prompt edits don't run in CI here; they take effect on the next automated release-docs run.