Harden upstream-release-docs workflow: gitignore, Opus, split passes#764
Merged
Harden upstream-release-docs workflow: gitignore, Opus, split passes#764
Conversation
PR #759 got a bad "Add upstream-release-docs content for toolhive v0.23.1" commit carrying 17 files of leakage from .claude-pr/.claude/* + .claude-pr/CLAUDE.md + .claude-pr/.husky/. That directory is created by anthropics/claude-code-action@v1 as scratch workspace during skill runs — it clones our own .claude/ skill configs into a sibling dir for its own use. None of it belongs on the repo's main branch. Our workflow's "Commit and push" step runs `git add -A` after the skill, which scooped up the scratch dir alongside any legitimate content. Ignoring /.claude-pr at the root so it never gets staged. The legit content from the skill (guide updates, v1alpha1 → v1beta1 migration docs) lands as intended via claude-code-action's own auto-commit. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
danbarr
previously approved these changes
Apr 21, 2026
Two changes to the claude-code-action invocation:
1. Switch to Opus 4.7 via `claude_args: --model claude-opus-4-7`.
Generation benefits from the stronger model on long multi-file
edits and source verification, and docs-review benefits from the
same quality. The default is Sonnet.
2. Split the single "multi-pass" skill step into two separate
claude-code-action invocations:
- `skill_gen`: runs /upstream-release-docs end-to-end (all 6
phases, including the skill's own internal docs-review in
Phase 5).
- `skill_review`: runs /docs-review over the files the previous
commit changed, in a fresh context with no exposure to the
generation session's internal reasoning.
Dan's hypothesis: fresh context for the editorial pass tends to
catch style and structure issues the generation pass rationalized
away. This was previously a same-session Pass 2 after the skill.
The removed Pass 3 (Phase 5 re-verification) was redundant with the
skill's own Phase 5 and is dropped.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
rdimitrov
changed the title
danbarr
approved these changes
Apr 21, 2026
rdimitrov
added a commit
that referenced
this pull request
Apr 21, 2026
…774) Four concrete hardenings to make upstream-release-docs PRs land-ready without human pre-merge cleanup: 1. Grant `gh` CLI to both skill invocations via claude_args `--allowed-tools "Bash(gh:*)"`. GH_TOKEN is already in the job env. Without this, Claude Code's default Bash allowlist blocks gh and the skill has to work from commit messages only, missing most of the "why" narrative that PR authors write at open time. The skill is already designed (SKILL.md) to use gh release view, gh pr view, gh api compare — we're just unblocking it. 2. Rewrite the Phase 2 step 4 instruction. Previously: "SKIP writing the why/consumer narrative and append to GAPS.md" — which guaranteed a "Gaps needing human context" section on every substantive release. Now: fetch PR descriptions via gh, write best-effort narrative directly in the docs, defer to GAPS.md only when rationale demonstrably cannot be derived from available sources. 3. Tighten the GAPS.md contract. Explicitly exclude environment limitations (the skill's v0.23.1 run flagged "npm run build blocked" as a gap — that's not a content gap, PR CI handles it) and "not a gap" commentary. Require each entry to include a paste-ready "Helper prompt for local Claude" block so a reviewer can resolve the gap by pasting into their local Claude Code rather than reverse-engineering what to ask. Require no GAPS.md file at all when nothing is genuinely deferred. 4. Add an auto-fix step after skill_review that runs `npx prettier --write` and `npx eslint --fix` against skill-touched files (scoped by git diff vs a pre-skill SHA, excluding auto-generated reference paths). The skill sandbox doesn't include these, so formatting drift was landing on PR CI — v0.23.1 failed the Lint and format checks job on one file. This matches the project's pre-commit hook behavior for human contributions. Also updated: - Top-of-file comment block (was "Runs the upstream-release-docs skill (3 passes)"). - The PR body template text at the previous "each ran twice (three total passes)" line — stale since PR #764 split the multi-pass inline design into two separate claude-code-action invocations. Now describes the two-Opus-session architecture. - The "fill them in before merging" review-guidance text now points reviewers to the Helper prompt blocks. - skill_review prompt now explicitly tells the editorial pass not to touch GAPS.md / NO_CHANGES.md signal files. Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
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.
Three hardenings to the upstream-release-docs pipeline, learned from the first successful end-to-end run on PR #759.
1. Gitignore
claude-code-action's.claude-pr/scratch dirAlongside the legitimate ~40-file content commit from the skill, our workflow's "Commit and push" step produced a spurious commit of 17 files:
It's scratch workspace that
anthropics/claude-code-action@v1creates during skill runs - a duplicate of our own.claude/skills tree the action stages for its own use. None of it belongs on the main branch.Our workflow's
git add -Ain the post-skill "Commit and push" step swept it up. Adding/.claude-prto.gitignoremakesgit add -Askip it. The skill's own auto-commit of real content (which comes from the action, not ourgit add -A) is unaffected.2. Switch skill runs to Opus 4.7
Via
claude_args: --model claude-opus-4-7on theclaude-code-actionsteps. Default was Sonnet. Generation benefits from the stronger model on long multi-file edits and source verification; docs-review benefits equally.3. Split generation from editorial review into two invocations
Previously the workflow ran
/upstream-release-docsend-to-end then a same-session Pass 2 of/docs-reviewand Pass 3 re-verification. Now split into two claude-code-action invocations:skill_gen- runs/upstream-release-docsend-to-end (all 6 phases, including the skill's own internal docs-review in Phase 5).skill_review- runs/docs-reviewover files the previous commit changed, in a fresh context with no exposure to the generation session's internal reasoning.Hypothesis (Dan's): fresh context for the editorial pass catches style and structure issues the generation pass rationalized away. This is the "clean room reviewer" pattern.
The removed Pass 3 (Phase 5 re-verification) was redundant with the skill's own Phase 5.
Followups (not in this PR)
49b7bbd. After this merges, the cleanest resolution is to delete those files in a follow-up commit on the Renovate branch (or revert49b7bbd). The legitimate content commitb90df7dstays.First real validation of all three changes is the next Renovate-opened upstream-release PR (or a manual
workflow_dispatchagainst PR #759 once this merges).