Skip to content

Commit 5a6cd94

Browse files
rdimitrovclaude
rdimitrov
and
claude
authored
Harden upstream-release-docs workflow: gitignore, Opus, split passes (#764)
* Gitignore claude-code-action's .claude-pr/ scratch dir 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> * Switch skill to Opus and split generation from editorial review 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> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 97e8b74 commit 5a6cd94

2 files changed

Lines changed: 95 additions & 51 deletions

File tree

‎.github/workflows/upstream-release-docs.yml‎

Lines changed: 89 additions & 51 deletions
Original file line numberDiff line numberDiff line change
@@ -432,8 +432,13 @@ jobs:
432432
")
433433
echo "docs_paths=$HINTS" >> "$GITHUB_OUTPUT"
434434
435-
- name: Run upstream-release-docs skill (multi-pass)
436-
id: skill
435+
# Invocation 1: generation. Runs /upstream-release-docs end-to-
436+
# end (all 6 phases, including the skill's own internal
437+
# docs-review in Phase 5). Uses Opus 4.7 — generation benefits
438+
# from the stronger model on long multi-file edits and source
439+
# verification.
440+
- name: Run upstream-release-docs skill (generation)
441+
id: skill_gen
437442
uses: anthropics/claude-code-action@38ec876110f9fbf8b950c79f534430740c3ac009 # v1
438443
with:
439444
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
@@ -455,6 +460,8 @@ jobs:
455460
# Actions Step Summary regardless of trigger.
456461
track_progress: ${{ github.event_name == 'pull_request' }}
457462
display_report: true
463+
claude_args: |
464+
--model claude-opus-4-7
458465
prompt: |
459466
You are running in GitHub Actions with no interactive user. Follow
460467
these steps exactly and do NOT ask clarifying questions -- proceed
@@ -467,55 +474,86 @@ jobs:
467474
CLONE: ${{ steps.clone.outputs.scratch_dir }}
468475
DOCS_HINTS: ${{ steps.hints.outputs.docs_paths }}
469476
470-
PASS 1 -- Initial content update:
471-
Run /upstream-release-docs ${{ steps.detect.outputs.repo }} ${{ steps.detect.outputs.new_tag }}
472-
Execute all 6 phases. Prefer reading source code from the
473-
local clone at ${{ steps.clone.outputs.scratch_dir }}
474-
instead of `gh api contents?ref=<tag>` -- it's already at
475-
the tag and doesn't consume API quota.
476-
For Phase 2 step 4 (context on major new features), SKIP
477-
writing the "why"/consumer narrative and append one bullet
478-
per gap to GAPS.md at repo root (create if missing). Each
479-
bullet MUST:
480-
- Name the feature
481-
- Reference the PR that introduced it, using the PR
482-
number you found in Phase 2 deep-dive
483-
- @-mention the PR author by their GitHub handle (skip
484-
this for bot authors like renovate[bot] or
485-
github-actions[bot])
486-
- Describe what context a human needs to supply
487-
Format: `- Feature X (PR #123 by @alice): needs a user
488-
story explaining who this is for and the expected
489-
consumer workflow.`
490-
This routes gaps to the engineer who built the feature
491-
rather than the whole reviewer pool.
492-
Follow the skill's own guidance on auto-generated reference
493-
files (Phase 4 step 5, Phase 4 step 6) -- do not hand-edit
494-
docs/toolhive/reference/cli/, static/api-specs/, or
495-
docs/toolhive/reference/crds/. Those are synced or
496-
regenerated from release assets by earlier steps in this
497-
workflow; if a release genuinely needs hand-written
498-
reference updates, note that in GAPS.md.
499-
500-
PASS 2 -- Editorial re-review:
501-
Run /docs-review over every file you changed in Pass 1 and
502-
apply every actionable fix. Do NOT re-run upstream-release-docs;
503-
you already have the source verification context in your
504-
history. If docs-review surfaces a factual concern, re-verify
505-
against source code at the tag before changing.
506-
507-
PASS 3 -- Technical re-verification:
508-
Re-run Phase 5 step 1 of /upstream-release-docs: re-verify
509-
every factual claim in the changed files against source code
510-
at the release tag. Fix any drift found. If no changes are
511-
needed, say so explicitly.
512-
Finally, re-run /docs-review one more time and apply any
513-
remaining fixes.
514-
515-
If at any point you conclude there are no doc-relevant changes
516-
for this release (Phase 3 impact map is empty), stop and write
517-
NO_CHANGES.md at repo root with a one-line explanation. Still
518-
do not hand-edit any file.
477+
Run /upstream-release-docs ${{ steps.detect.outputs.repo }} ${{ steps.detect.outputs.new_tag }}
478+
Execute all 6 phases. Prefer reading source code from the
479+
local clone at ${{ steps.clone.outputs.scratch_dir }}
480+
instead of `gh api contents?ref=<tag>` -- it's already at
481+
the tag and doesn't consume API quota.
482+
483+
For Phase 2 step 4 (context on major new features), SKIP
484+
writing the "why"/consumer narrative and append one bullet
485+
per gap to GAPS.md at repo root (create if missing). Each
486+
bullet MUST:
487+
- Name the feature
488+
- Reference the PR that introduced it, using the PR
489+
number you found in Phase 2 deep-dive
490+
- @-mention the PR author by their GitHub handle (skip
491+
this for bot authors like renovate[bot] or
492+
github-actions[bot])
493+
- Describe what context a human needs to supply
494+
Format: `- Feature X (PR #123 by @alice): needs a user
495+
story explaining who this is for and the expected
496+
consumer workflow.`
497+
This routes gaps to the engineer who built the feature
498+
rather than the whole reviewer pool.
499+
500+
Follow the skill's own guidance on auto-generated reference
501+
files (Phase 4 step 5, Phase 4 step 6) -- do not hand-edit
502+
docs/toolhive/reference/cli/, static/api-specs/, or
503+
docs/toolhive/reference/crds/. Those are synced or
504+
regenerated from release assets by earlier steps in this
505+
workflow; if a release genuinely needs hand-written
506+
reference updates, note that in GAPS.md.
507+
508+
If you conclude there are no doc-relevant changes for this
509+
release (Phase 3 impact map is empty), stop and write
510+
NO_CHANGES.md at repo root with a one-line explanation.
511+
Still do not hand-edit any file.
512+
513+
# Invocation 2: editorial re-review with FRESH CONTEXT. Running
514+
# docs-review in a separate session — with no exposure to the
515+
# generation session's internal reasoning — tends to catch style
516+
# and structure issues the generation pass rationalized away.
517+
# Also uses Opus 4.7 since docs-review benefits from the same
518+
# model quality.
519+
- name: Run docs-review on skill output (fresh context)
520+
id: skill_review
521+
if: always() && steps.skill_gen.conclusion == 'success'
522+
uses: anthropics/claude-code-action@38ec876110f9fbf8b950c79f534430740c3ac009 # v1
523+
with:
524+
anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
525+
additional_permissions: |
526+
actions: read
527+
allowed_bots: 'renovate'
528+
track_progress: ${{ github.event_name == 'pull_request' }}
529+
display_report: true
530+
claude_args: |
531+
--model claude-opus-4-7
532+
prompt: |
533+
You are running in GitHub Actions with no interactive user. Follow
534+
these steps exactly and do NOT ask clarifying questions -- proceed
535+
best-effort at every decision point.
536+
537+
A previous Claude session just generated content for the
538+
upstream release ${{ steps.detect.outputs.repo }} ${{ steps.detect.outputs.new_tag }}.
539+
You are a fresh reviewer with no prior context from that
540+
session. Your job is purely editorial.
541+
542+
Run /docs-review over every file the previous commit
543+
changed (use `git show --name-only HEAD` or `git diff
544+
--name-only HEAD~1 HEAD` to find them). Apply every
545+
actionable fix per the skill's standard guidance.
546+
547+
If you spot a factual concern, re-verify against source
548+
code in the local clone at
549+
${{ steps.clone.outputs.scratch_dir }} before changing
550+
anything. Don't introduce new claims; only refine what's
551+
already there.
552+
553+
Do NOT re-run /upstream-release-docs. Do NOT touch files
554+
under docs/toolhive/reference/cli/, static/api-specs/,
555+
or docs/toolhive/reference/crds/ — those are
556+
regenerated from release assets and aren't yours to edit.
519557
520558
- name: Capture skill signal files
521559
id: signals

‎.gitignore‎

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -27,3 +27,9 @@ yarn-error.log*
2727
/GAPS.md
2828
/NO_CHANGES.md
2929
.claude/scheduled_tasks.lock
30+
31+
# Scratch workspace claude-code-action creates during skill runs.
32+
# Contains a duplicate of .claude/ plus CLAUDE.md and husky hooks;
33+
# none of it belongs in the repo. First seen leaking into PR #759 when
34+
# our workflow's `git add -A` swept it up after the skill step.
35+
/.claude-pr

0 commit comments

Comments
 (0)