Improve upstream-release-docs skill with verification lessons

[rdimitrov]

Summary

Improves the upstream-release-docs skill based on lessons learned during the Registry Server v1.0.0/v1.0.1 documentation update (#683).

Changes

• Check related repositories (Phase 2, step 5): Components often span multiple repos — an operator/CRD may live in a different repo than the server. The skill now prompts checking related repos for coordinated changes.
• Deep-verify behavioral claims (Phase 2, step 8): New checklist for the most common sources of documentation inaccuracy — API route registration, required field validation logic, default value fallbacks, precedence chains, delete/cleanup behavior, query parameter wiring, and authorization containment direction.
• Parallel verification agents (Phase 5, step 1): For large doc sets, spawn parallel agents (one per file) to verify all factual claims concurrently against source code.

Motivation

During the Registry Server docs update, we found 9 accuracy bugs that survived multiple editorial review rounds but were caught by source code verification agents:

Bug	Root cause
Wrong publish/delete API URLs	Route handlers weren't checked — only handler names
description listed as required	Struct field existed but validation didn't check it
status filter documented but non-functional	Query param parsed but never wired to service layer
Delete latest pointer behavior inverted	Docs assumed behavior without checking delete logic
Git ref precedence wrong (tag > branch)	if/else chain was branch > tag in actual code
Git branch "defaults to main"	Actually defaults to remote's HEAD branch
format incorrectly marked required	Validation allowed empty value
Publish subset example inverted	Containment direction was caller/resource, not resource/caller
/openapi.json missing from public paths	Code had 5 default paths, docs listed 4

All of these would have been caught earlier with the behavioral verification checklist now added to the skill.

Test plan

• Skill file passes Prettier formatting
• Pre-commit hooks pass

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs-website	Ready	Preview, Comment	Apr 9, 2026 10:50pm

[Copilot]

Pull request overview

This PR updates the .claude/skills/upstream-release-docs skill to reduce documentation accuracy bugs by expanding the verification workflow used when documenting upstream releases.

Changes:

• Add an explicit “check related repositories” step to catch coordinated multi-repo changes (e.g., operator/CRD vs server).
• Add a behavioral verification checklist to validate runtime behavior (routes, validation, defaults, precedence, deletes, query params, auth containment direction), not just structs/types.
• Extend final validation guidance to optionally use parallel verification agents for large doc sets.