upstream-release-docs

Upstream Release Documentation

Analyze a new release of an upstream project and update the documentation site to reflect verified changes.

Core Principle

Verify everything against source code at the release tag. Never trust release notes, PR descriptions, PR review comments, or issue descriptions at face value. Always check the actual source code.

How you reach that source depends on what the caller gave you:

• A local clone at the tag (an automated caller usually provides one, and names its path in the invocation): read it with the Read, Grep, and Glob tools. Prefer this; it costs no API quota. See Reading the upstream clone for the constraints.

• No clone: fetch individual files from the API, and decode the base64 response.

  gh api repos/<OWNER>/<REPO>/contents/<PATH>?ref=<TAG>
  

Claims from any human-written source (release notes, PR bodies, review comments) may be inaccurate, outdated, or aspirational. The source code at the tag is the single source of truth.

Input

Parse the argument to extract:

• <OWNER>/<REPO>: the upstream repository (e.g., stacklok/toolhive-registry-server)
• <TAG> (optional): the release tag (e.g., v0.6.3). If omitted, fetch the latest release.

Output conventions

Any output that may be rendered as a GitHub comment, PR body, or Markdown file in the docs-website repo (progress narration, SUMMARY.md, GAPS.md, commit messages, PR descriptions) must fully qualify references to the upstream repo. GitHub auto-links bare #NNN relative to the repo the text lives in, so a bare #777 in a docs-website comment links to docs-website PR #777, not the upstream PR.

• Refer to upstream PRs and issues as <OWNER>/<REPO>#NNN (e.g., stacklok/toolhive#777), never bare #NNN.
• When the release notes body contains bare #NNN, expand them to <OWNER>/<REPO>#NNN before echoing them back.
• Full PR/issue URLs are also fine.

Execution modes

This skill runs in one of two modes. The caller signals the mode; absent an explicit unattended signal, assume interactive. Never infer unattended mode from surrounding context.

Interactive (default): a human is present. At decision points that need product context you cannot derive from source (Phase 2 step 4), ask the user. Never write the GAPS.md, SUMMARY.md, NO_CHANGES.md, or REVIEWERS.json artifacts described below in interactive mode; surface that information conversationally instead. Those files are machine-readable handoff artifacts for an automated caller, and writing them during a local run just litters the repo root.

Unattended: no interactive user, for example a CI workflow that invokes /upstream-release-docs ... in unattended mode. Never ask clarifying questions; proceed best-effort at every decision point, and route anything genuinely unresolvable into the artifacts below.

Unattended decision-point behavior

When Phase 2 step 4 would normally ask the user for a major feature's "why", instead:

1. Fetch the PR body and author with gh pr view <NUMBER> --repo <OWNER>/<REPO> --json title,body,author. The PR body usually carries the "why" the author wrote at open time: motivation, intended consumers, design decisions.
2. If the PR body references linked issues ("Closes #N", "Fixes #N", "Refs #N"), fetch the likely-context-bearing ones with gh issue view <N> --repo <OWNER>/<REPO>.
3. Write the "why"/consumer narrative directly into the relevant page using what you learned, translated into reader-facing language rather than the PR's engineering shorthand. This is best-effort; reviewers refine it later.
4. Defer to GAPS.md only when the rationale demonstrably cannot be derived from available sources: the PR points to an internal design doc you cannot access, multiple plausible consumer narratives exist and choosing one would mislead readers, or a release timeline or commitment needs product-team confirmation.

Reading the upstream clone

When a caller provides a local clone of the upstream repo at the release tag, read it with the Read, Grep, and Glob tools. Prefer it over gh api contents?ref=<tag>: it is already at the tag and costs no API quota.

Do not reach for Bash to explore it. An automated caller typically clones to a scratch directory outside the session's working directory, so ls, find, and grep run through Bash are refused there, and git -C <path> is refused everywhere because it can execute untrusted hooks from the target repo. Read, Grep, and Glob have no such restriction and are the right tools regardless.

Two consequences worth internalizing, because working around them by retrying Bash variants wastes turns and never succeeds:

• Don't try to run git log on the clone. When the caller supplies .release-meta.json, its commits array is the release range's commit list. Otherwise derive the range from the release notes and gh api.
• Don't append 2>&1 or chain with && on any Bash call. That splits the command into parts that no longer match the caller's tool allowlist, so the call is denied even when the underlying command is permitted.

Artifacts (unattended mode only, written at repo root)

These files are read by the automated caller and spliced into the PR body. The filenames and the repo-root location are a contract with the caller; do not rename or relocate them.

GAPS.md - only if you genuinely need to defer (see above). An empty GAPS.md is worse than none; do not create it if every feature's "why" was resolvable from available sources.

• Include only content gaps a human reviewer must fill. Exclude environment or sandbox limitations (for example, "couldn't run npm build"); the PR's CI handles those. Exclude "documented for clarity, not a gap" commentary.

• Each entry must @-mention the PR author, skipping bot authors (renovate[bot], github-actions[bot], stacklokbot).

• Each entry must include a paste-ready "Helper prompt for local Claude" referencing the specific file(s), the PR number for context, and the narrow piece of information the human must supply or confirm.

  Entry format:

  ### <Feature name> (PR <OWNER>/<REPO>#123 by @alice)
  
  <One paragraph: what's missing and why it couldn't be resolved from available sources.>
  
  **File(s):** path/to/file.mdx
  
  **Helper prompt for local Claude:**
  
  > <Self-contained, paste-ready prompt referencing the file(s), PR number, and the narrow piece of info needed.>
  

REVIEWERS.json - written whenever .release-meta.json exists at the repo root and lists contributors. This one is JSON, not markdown, because the workflow parses it with jq to decide who gets a review request.

Read .release-meta.json first (the caller writes it before invoking you):

{
  "repo": "stacklok/toolhive",
  "prev_tag": "v0.42.0",
  "new_tag": "v0.43.0",
  "owner": "jerm-dro",
  "owner_source": "merged release PR stacklok/toolhive#6333",
  "contributors": ["alice", "bob", "carol"],
  "commits": [
    {
      "sha": "8343851e9f06c0d67e315eb6aa4e9371d6ef76cf",
      "subject": "Push skills unsigned until keyless signing lands (#6334)",
      "author": "alice"
    }
  ]
}

commits is the commit list for the release range: use it instead of trying to run git log against the upstream clone, which is refused (see Reading the upstream clone). It is also what tells you which commits belong to which contributor for the classification below.

When commits_truncated is true, the range exceeded what the caller could fetch in one request, so both commits and contributors are partial. Treat the release notes as the authoritative list of changes for that run, and say in SUMMARY.md that the commit list was truncated so a reviewer knows the classification may have missed someone.

Classify every login in contributors as docs-facing or not, and write REVIEWERS.json at the repo root:

{
  "contributors": [
    {
      "login": "alice",
      "docs_facing": true,
      "docs_facing_shas": ["8343851e9f06c0d67e315eb6aa4e9371d6ef76cf"],
      "note": "Confirm the ai-plugin timeout flag section matches what you shipped."
    },
    {
      "login": "bob",
      "docs_facing": false,
      "reason": "CI workflow and test-fixture changes only"
    }
  ]
}

• docs_facing: true means at least one of this person's commits in the release range changed something a reader of the docs can observe: a CLI flag or subcommand, a CRD or config field, an API route, a default, an error message, a user-visible behavior, or anything you documented or corrected in this run. When you are unsure, classify as true. A needless review request is a minor annoyance; a missing one means a wrong page ships.
• docs_facing_shas (docs-facing only): every full commit SHA from commits that made the contributor docs-facing. If GitHub cannot request the contributor as a reviewer, the workflow uses all of these SHAs to find the human mergers of the relevant upstream PRs. Include only commits you verified as reader-visible; do not list an unrelated commit merely because the same contributor authored it.
• docs_facing: false is for changes with no reader-visible surface: CI and build plumbing, dependency bumps, tests and fixtures, internal refactors, lint fixes, comment-only edits. Base this on the actual diff you read in Phase 2, not on the commit message. A commit titled "refactor" that changes a default value is docs-facing.
• note (docs-facing only): one short sentence naming the specific thing that person should check, in their terms. Not a summary of the release, and not a restatement of their PR title. Skip the note rather than pad it.
• reason (non-docs-facing only): a short phrase naming what their changes actually were. This keeps the classification auditable when the run artifact is inspected; the workflow counts these contributors without rendering

Content truncated.