Add upgrade helper skill

[karthikjeeyar]

Add rhdh-upgrade-helper skill for RHDH upgrade assessments

Fixes: https://redhat.atlassian.net/browse/RHDHPLAN-1593

Summary

• Adds the rhdh-upgrade-helper skill — a customer-facing tool that analyzes RHDH configuration files against a target release and produces a personalized migration plan
• Tested against real Helm values (production config) and rhdh-local project configs across 1.8→1.10, 1.9→1.10 upgrade paths

What the skill does

1. Parses customer config files — auto-detects file type from content (Helm values, app-config, dynamic-plugins, Backstage CR, compose files, env files)
2. Clones the overlay repo locally — shallow clone of release-{X.Y} branch for instant metadata lookups with zero API rate limit risk
3. Resolves OCI references — two-pass lookup (by filename, then by spec.dynamicArtifact content) handles all naming patterns including rhdh-bsp-* abbreviations
4. Validates existing OCI plugin tags against workspace metadata for the target release
5. Searches RHDHBUGS Jira per-plugin for open bugs affecting specific plugin versions (gracefully skips if Jira unavailable)
6. Filters breaking changes into "Affects You" vs "Does NOT Affect You" based on actual config overlap
7. Computes a Readiness Score (0-100) with transparent breakdown tracing every deduction to a specific finding
8. Merges multiple app-config files in order (matching Backstage behavior) before analysis
9. Auto-detects rhdh-local projects — discovers configs, env vars, and RHDH version from compose.yaml

Key design decisions

• Evidence-based findings only — never flag Critical/Important without tracing to release notes, overlay repo metadata, or Backstage changelogs. No assumptions from naming conventions.
• Don't construct OCI references — only recommend what exists in spec.dynamicArtifact from workspace metadata. If metadata shows a local path, recommend relying on defaults instead of inventing an unverified OCI tag.
• Local clone over API calls — shallow git clone of the overlay repo replaces ~180 GitHub API calls with instant local file reads.
• Config files first, manual questions as fallback — interactive flow asks for file paths before auth/SCM/features since files give line-level guidance automatically.
• Release notes bundled, not fetched — pre-baked markdown files (1.4–1.10) with auto-fetch fallback via lynx for missing versions. Zero runtime dependencies for users.

How to test

### Prerequisites

• gh CLI (authenticated) for overlay repo clone and GitHub Issues search
• Atlassian MCP (optional) enables per-plugin bug search against RHDHBUGS. If not configured, the skill skips it silently.

Checkout the PR

gh pr checkout 3

Install the skill

npx skills add . --skill rhdh-upgrade-helper

Test the skill

  # Config-driven (config directory)
  /rhdh-upgrade-helper --from 1.8 --to 1.10 --config-path ./my-configs/

  # Config-driven (Helm)
  /rhdh-upgrade-helper --from 1.8 --to 1.10 --config ./values.yaml

  # rhdh-local project
  /rhdh-upgrade-helper --to 1.10 --config-path ./rhdh-local/configs

  # Interactive
  /rhdh-upgrade-helper --to 1.10

  # Help
  /rhdh-upgrade-helper --help

[04kash]

Tried the skill on a values.yaml file and got back a detailed assessment report. I also tried the interactive feature it worked very well 🎊.

Just added a small comment on if we wanted to consider adding rhdh- to the skill name.

[04kash]

You can add this to the CODEOWNERs file as well: https://github.com/redhat-developer/rhdh-users-skill-pack/blob/main/.github/CODEOWNERS

[karthikjeeyar]

Thank you @04kash for the review. I have addressed your comments.

[04kash]

Lgtm!