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 actual source code using:

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, or NO_CHANGES.md 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.

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.>
  

NO_CHANGES.md - if the Phase 3 impact map is empty (no doc-relevant changes for this release), write this at repo root with a one-line explanation and stop. Do not hand-edit any file.

SUMMARY.md - before the final commit, write a concise list of the hand-written doc changes you made. The caller surfaces it as the PR's "Summary of changes" so reviewers see what shipped without reading the diff. Skip it only when you wrote NO_CHANGES.md or made zero hand-edits. Keep it to 3-8 bullets, each formatted as one of:

• Added <what> at <path> - new pages/sections
• Updated <what> in <path> - meaningful prose edits
• Swept <what> across N files in <area> - repo-wide renames, apiVersion bumps, etc.
• Removed <what> from <path> - deletions

Describe one logical change as one bullet (don't enumerate each file in a sweep), and exclude auto-generated reference files the caller's refresh step updates: describe only your hand-written edits.

Phase 1: Discovery

1. Fetch the release:

   gh release view <TAG> --repo <OWNER>/<REPO> --json tagName,name,body,publishedAt
   

   If no tag was provided:

   gh release view --repo <OWNER>/<REPO> --json tagName,name,body,publishedAt
   

2. Extract PR numbers from the release notes body (look for #NNN patterns or full PR URLs). When referring to these PRs in any subsequent output, always fully qualify them as <OWNER>/<REPO>#NNN (see "Output conventions" above).

3. Categorize changes into:

   • New features: entirely new capabilities
   • Changed defaults: existing behavior that now works differently
   • New/changed configuration: new config options, env vars, CLI flags
   • Deprecations: features or options being phased out
   • API changes: new/modified endpoints, request/response formats
   • Bug fixes: corrections that may affect documented behavior
   • Internal/infra: CI, dependencies, refactoring (usually no docs impact)

4. Log the categorized summary for transparency, then proceed to Phase 2.

Phase 2: Deep Dive

For each PR identified in Phase 1 (skip internal/infra unless user requests):

1. Fetch PR details:

   gh pr view <NUMBER> --repo <OWNER>/<REPO> --json title,body,files
   

2. Fetch linked issues if referenced:

   gh issue view <NUMBER> --repo <OWNER>/<REPO> --json title,body
   

3. Understand the "why": for new features, look beyond the code to understand motivation and intended usage:

   • Check linked issues for user stories, acceptance criteria, and "definition of done"
   • Follow references to RFCs, design docs, or PRDs linked from issues or PR descriptions
   • Identify the intended user workflow: who uses this, why, and what happens after?
   • Map the full lifecycle: if the feature has a publish/produce side, actively search the source code for the consume/discover side. Check CLIs, client libraries, and related repositories. If consumption tooling doesn't exist in this release, note that explicitly. This gap must be documented rather than silently omitted.
   • If the "why" and consumption story aren't clear from any source, flag this gap. Documentation that only covers the API surface without explaining purpose or workflow is incomplete

4. For major new features: when a change introduces an entirely new capability (not just a config change or incremental addition), the "why" and consumer workflow often cannot be derived from source code alone. In this case, ask the user for additional context before writing documentation:

   • Request user stories, PRDs, RFCs, or design documents that explain the motivation and intended usage
   • Ask who the target users are and what workflow they're expected to follow
   • Ask how consumers are expected to discover and use the feature (CLI, IDE extension, API, etc.)
   • Do not attempt to fabricate the "why" or consumer story from code structure alone. This produces documentation that covers the "what" and "how" but misses the perspective and voice that only comes from understanding the product intent
   • Incremental changes (new config options, default changes, annotation additions) can proceed without this step
   • In unattended mode, do not ask. Follow the unattended decision-point behavior in Execution modes: derive the "why" from the PR body and linked issues, write it best-effort, and defer to GAPS.md only when it is genuinely underivable.

5. Check related repositories: components often span multiple repos. For example, a server's CRD/operator may live in a different repo than the server itself. When a release changes config structures, API surfaces, or deployment models, check whether related repos (operators, CLIs, client libraries) have also released changes that affect the documentation. Ask the user which repos are related if unclear (in unattended mode, infer related repos from the release notes and proceed best-effort).

6. Read the actual source code at the release tag to verify every claim made in the PR description:

   gh api repos/<OWNE
   

Content truncated.