Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion .claude-plugin/marketplace.json
Original file line number Diff line number Diff line change
Expand Up @@ -63,7 +63,8 @@
"./skills/release/rhdh-smoke-tests",
"./skills/release/rhdh-translation-upload",
"./skills/release/rhdh-translation-deploy",
"./skills/release/rhdh-test-plan-review"
"./skills/release/rhdh-test-plan-review",
"./skills/release/rhdh-kb-theme-analysis"
]
},
{
Expand Down
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -48,7 +48,7 @@ one. It performs no work itself.
and the single source of truth for membership. This file does not restate it.

Three skills are human-invoked and never selected automatically: `/ask-rhdh`,
`/setup-rhdh-skills`, and `/clean-prose`. The other 68 are model-invoked, and can
`/setup-rhdh-skills`, and `/clean-prose`. The other 69 are model-invoked, and can
also be called by name.

Skills are grouped into seven folders:
Expand All @@ -58,7 +58,7 @@ Skills are grouped into seven folders:
| `jira/` | Creating, refining, updating, and reporting on RHIDP, RHDHPLAN, RHDHBUGS, and RHDHSUPP work, plus sprint ceremonies and linking PRs to issues. |
| `plugins/` | Authoring, wiring, exporting, and fixing Backstage dynamic plugins; the overlays repository; local RHDH; opening and reviewing pull requests; testing rhdh-operator PRs on a cluster; midstream propagation; browser UI verification with Playwright. |
| `ci/` | Prow job configuration and nightly triggers, Konflux and Tekton task updates, plugin catalog index status, release-data admission tags, base images, and Yarn bumps. |
| `release/` | Release status and readiness, candidate-feature capacity through Code Freeze, milestone schedules, freeze announcements, teams, fix-version sync across RHIDP/RHDHPLAN/RHDHBUGS, test-plan review, platform lifecycle, plugin CVE export, and RC/GA Helm+Operator smoke. |
| `release/` | Release status and readiness, candidate-feature capacity through Code Freeze, milestone schedules, freeze announcements, teams, fix-version sync across RHIDP/RHDHPLAN/RHDHBUGS, test-plan review, platform lifecycle, plugin CVE export, RC/GA Helm+Operator smoke, and public KB theme analysis for release planning. |
| `refinement/` | The OpenSpec artifact-driven change workflow: propose, explore, implement, audit, verify, and archive a change. See [the workflow](docs/refinement/refinement-workflow.md). |
| `reference/` | The reusable layer other skills invoke by name: repository and version context, the forge read seam, the write gate, the OpenSpec journal and RHDH's spec-driven schema, and the Jira and Backstage reference material. |
| `meta/` | The three human-invoked entry points, plus skill authoring and repository agent-readiness. |
Expand Down
1 change: 1 addition & 0 deletions skills/meta/ask-rhdh/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,7 @@ competing inventory, which is what this table used to be.
| Reads GitHub and GitLab and constructs unexecuted forge payloads for the other RHDH skills: parse an issue, pull request, or merge request reference, fetch issue detail, resolve a plugin workspace, inspect checks or pipelines, read repository files, or build the exact command for a GitHub pull request, GitLab merge request, comment, label, assignee, approval, or /publish write. Use for a forge URL, a bare #number, a !number merge request, "which workspace is this issue in", a stale statusCheckRollup, "why did that check fail", or safe gh, glab, and jq command construction. | `/rhdh-forge` |
| Reads RHDH Jira and owns the mechanics every other RHDH Jira skill needs: `acli` flags and their traps, JQL for RHIDP, RHDHPLAN, RHDHBUGS and RHDHSUPP, custom field IDs, GraphQL and REST fallbacks, board and sprint IDs, the component catalog, and the workflow states with their exit criteria. Use to look up an issue such as RHIDP-1234, to write or debug a JQL query, to answer "which field is Story Points", "why is my search returning 30 rows", or "what does Release Pending require". Reading and query mechanics only — deciding what to file, judging readiness, or changing an issue belongs to the Jira skill that owns that verb. | `/rhdh-jira-api` |
| Supplies the craft of writing good RHDH Jira work in RHIDP, RHDHPLAN, RHDHBUGS, and RHDHSUPP: the Feature, Epic, Story, Task, and Bug description templates with filled examples, the RHDH challenge matrix that stress-tests scope, sizing, acceptance criteria, and Epic independence, the T-shirt and Fibonacci sizing scales, keyword duplicate detection, and the tracer-bullet rules for breaking a Feature into Epics or an Epic into Stories. Use when drafting or judging the text and shape of an issue such as RHIDP-1234 — how big is this, is this AC testable, should this be one Epic or three, does this already exist. Prose and estimation craft only; it runs no Jira command. | `/rhdh-jira-authoring` |
| Analyzes Red Hat Customer Portal Knowledgebase Solution articles for Red Hat Developer Hub, compares rolling 90-day and 365-day windows, and turns public article metadata into support-theme, documentation, and roadmap signals. Use for RHDH KB trend analysis, support-theme reviews, or product friction scans. | `/rhdh-kb-theme-analysis` |
| Owns the append-only interaction journal for an OpenSpec change — `openspec/changes/<change>/journal.jsonl` — and the fixed event vocabulary written to it (change.created, artifact.added/revised, mode.chosen, task.start/complete/blocked, verifier.result, decision, handoff, archive, skill.invoked, agent.spawned, context.compacted, turn.start/end). Invoked by name from the openspec-\* skills whenever one of those events happens; not a user-facing entry point on its own. Use for "log this to the journal", "emit a journal event", "what fields does task.complete need", or "why did the journal helper reject my write". | `/openspec-journal` |
| Owns RHDH's project-local OpenSpec workflow definition — the `rhdh-spec-driven` schema (proposal -> {specs, design} -> tasks -> apply), its four artifact templates, the Canonical Touchpoints rule that ties a change back to `specifications/prd/`, `specifications/adr/`, and `openspec/specs/<capability>/spec.md`, and the shared artifact-creation-loop mechanics every openspec-\* skill drives through the `openspec` CLI. Also installs `config.yaml` and `schemas/rhdh-spec-driven/` into a product repo's `openspec/` so the CLI can resolve that schema. Invoked by name from openspec-new-change, openspec-continue-change, openspec-ff-change, and openspec-onboard; not a standalone entry point. Use for "what does the spec-driven schema require", "install the rhdh-spec-driven schema", "what goes in Canonical Touchpoints", "how do I fill in an artifact template", or "why did an artifact instruction reject my capability name". | `/rhdh-spec-driven-schema` |
| Scaffolds a new OpenSpec change directory and shows the first artifact's template without writing it. Use for "start a new change", "scaffold a change", "set up a change for X", or "what's the first artifact I need" — when the user wants the folder and the first template, not a drafted proposal. Creates the change directory and stops — it does not draft or write any artifact content, and it does not implement code. | `/openspec-new-change` |
Expand Down
6 changes: 6 additions & 0 deletions skills/meta/setup-rhdh-skills/assets/catalog.json
Original file line number Diff line number Diff line change
Expand Up @@ -452,6 +452,12 @@
"prose-editing"
]
},
{
"name": "rhdh-kb-theme-analysis",
"category": "release",
"invocation": "model",
"requiresSkills": []
},
{
"name": "openspec-journal",
"category": "reference",
Expand Down
99 changes: 99 additions & 0 deletions skills/release/rhdh-kb-theme-analysis/SKILL.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,99 @@
---
name: rhdh-kb-theme-analysis
description: >-
Analyzes Red Hat Customer Portal Knowledgebase Solution articles for Red Hat
Developer Hub, compares rolling 90-day and 365-day windows, and turns public
article metadata into support-theme, documentation, and roadmap signals. Use
for RHDH KB trend analysis, support-theme reviews, or product friction scans.
compatibility: "Node 18+; no dependencies."
---

# RHDH KB theme analysis

Turn public Red Hat Customer Portal KB metadata into a product-facing view of
RHDH support themes. The workflow is read-only and uses the public KB search
API; it does not open, read, or modify private support cases or issue-tracker
data.

## Run

Use the bundled script:

```bash
node scripts/analyze-kb.mjs \
--product "Red Hat Developer Hub" \
--as-of YYYY-MM-DD \
--format markdown
```

Defaults:

- product: `Red Hat Developer Hub`
- recent window: trailing 90 days
- comparison window: trailing 365 days
- output: Markdown

Pass explicit `--recent-since`, `--recent-until`,
`--comparison-since`, or `--comparison-until` values when the user asks for a
calendar quarter, calendar year, release window, or custom range.

Choose the taxonomy before the run:

- omitted: the built-in clusters, for a general support-theme scan;
- `--themes PATH`: a taxonomy proposed for this investigation;
- `--themes none`: no clustering, leaving the grouping to you.

Read `references/taxonomy.md` before writing a taxonomy file. Use
`--format json` when the answer needs every article rather than the top 15, and
add `--include-abstracts` when the grouping will be done from article text.

`component` is unnormalized free text. The report folds case, whitespace, and
dashes by default; pass `--component-aliases PATH` with a JSON object of
`{"from": "to"}` pairs when a question needs real synonyms merged, and say that
you did.

## Authoring and demand

The report answers two questions. The `recent` and `comparison` windows filter on
`createdDate` and measure what support published. The `demand` view ignores
`createdDate` and weights the whole corpus by `caseCount_365`. Lead with demand
when the question is about customers; lead with authoring when it is about
publishing cadence or taxonomy coverage. Case weights are annual — a quarterly
case-volume answer is not derivable from this data.

## Boundary with neighbouring skills

- Use this skill for public KB article themes and release-planning signals.
- Use `/rhdh-release-status` for open Jira work, blockers, CVEs, and release
readiness.
- Use `/rhdh-feature-docs` to write or update documentation content.
- Use `/rhdh-platform-lifecycle` for vendor support phases and EOL dates.

## Interpretation

Read `references/interpretation.md` before turning script output into product,
documentation, or roadmap recommendations. It carries the taxonomy the run used
and the rule that both windows share one.

Read `references/api.md` only when changing the query, troubleshooting the API,
or extending the script.

## Failure mode

If the KB API is unreachable or returns a non-2xx response, report that the
public KB data could not be fetched. Do not infer themes from memory or from a
previous run. Name the endpoint status if the script provides one.

## Completion

Complete when the answer names:

- the product and run date;
- both window boundaries;
- recent and comparison article counts;
- the strongest theme signals, as `movement` classes rather than adjectives;
- the demand view, its attributed case total, and any concentration warning;
- the stale, high-touch articles worth refreshing;
- linked citations for every article named in the answer;
- a final “Product and documentation improvement areas” section that connects recent findings to candidate product and documentation work;
- the caveats from the interpretation reference.
3 changes: 3 additions & 0 deletions skills/release/rhdh-kb-theme-analysis/agents/openai.yaml
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
interface:
display_name: "RHDH KB Theme Analysis"
short_description: "Compare RHDH KB themes and case-weighted demand"
82 changes: 82 additions & 0 deletions skills/release/rhdh-kb-theme-analysis/references/api.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,82 @@
# Red Hat KB search API

The Customer Portal KB search page is client-rendered. Do not scrape the HTML.
Use the JSON endpoint behind it:

```text
https://access.redhat.com/hydra/rest/search/platform/kbase
```

## Query shape

The script sends:

- `q=*`
- `fq=-id:Other`
- `fq=documentKind:(Solution Article)`
- `fq={!tag=productFilter}standard_product:"..."`
- `facet=true`
- `facet.mincount=1`
- `enableElevation=true`
- `f.standard_product.facet.limit=-1`
- `redhat_client=kb-search`
- `facet.field=documentKind`
- `facet.field={!ex=productFilter}standard_product`

The Solr local params in `{!ex=...}` and `{!tag=...}` must remain URL-encoded.
`URLSearchParams` handles this correctly.

## Pagination

The API reports `response.numFound` and returns documents in
`response.docs`. The script requests 100 rows per page, uses a 30-second
request timeout, and follows `start` until it has `numFound` results or reaches
the 10,000-result safety cap. If the cap truncates the result, the report
prints an “at least” count rather than presenting the fetched count as the
total.

## Fields the analysis reads

Treat these fields as optional because Red Hat can change the public response.
The script accepts either string or array shapes for `category`, `component`,
`tag`, and `standard_product`:

- `id`, `title`, `view_uri`
- `createdDate` — publication date. The authoring windows filter on its
`YYYY-MM-DD` prefix.
- `lastModifiedDate` — last editorial change. Drives the refresh-candidate
signal.
- `kcsState`, with `publication_state` as a fallback — `verified`, `unverified`,
or `wip`.
- `category`, `component`, `tag`
- `standard_product` — every product the article is tagged to. More than one
entry means the article is shared, and its case weight is divided by that
count.
- `issue` — the abstract. The taxonomy matches against it, and it is mined for
emergent terms.
- `caseCount` — lifetime linked cases.
- `caseCount_365` — linked cases in a fixed trailing 365 days.

## Case-count semantics

`caseCount_365` is published by Red Hat and cannot be re-windowed. A query for a
90-day range still returns the trailing-year count, so no case-volume statement
shorter than a year is derivable from this API. The demand view in the report is
annual for that reason, whatever `--as-of` says.

## Fields present but unused

`kcsRateUp` and `kcsRateDown` carry article usefulness votes, and `sbr`,
`internalTags`, and `issueTag` carry extra classification. They are sparse in
the RHDH corpus — fewer than a dozen articles carry any vote — so the report
does not read them. Revisit if the vote coverage improves.

The analysis filters on the `YYYY-MM-DD` prefix of `createdDate`. Theme
matching reads `title`, `issue` (the abstract), `category`, and `component`, so
broad stems match abstract prose; `--include-abstracts` only controls whether an
abstract is echoed in the output, never whether it is matched.

## Runtime

`scripts/analyze-kb.mjs` is the committed, dependency-free runtime artifact. Do
not add a dependency or build step at skill runtime.
Loading