From e353de6feb97e5b140d92a5e57fe2c47c16fbeb4 Mon Sep 17 00:00:00 2001 From: hilram7 <212961752+hilram7@users.noreply.github.com> Date: Wed, 8 Jul 2026 14:51:55 -0400 Subject: [PATCH] kb(skills): add link validation to kb-pr-review Derek checklist MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Adds a `links` row to the Derek review table in kb-pr-review/SKILL.md. Reviewers now find every internal `/docs/...` markdown link, resolve each to a real file on disk (via the target's `slug` frontmatter override or its real path/filename — not its `sidebar_label` or `title`), and flag any mismatch as a Required fix. --- .claude/skills/kb-pr-review/SKILL.md | 1 + 1 file changed, 1 insertion(+) diff --git a/.claude/skills/kb-pr-review/SKILL.md b/.claude/skills/kb-pr-review/SKILL.md index 74f28a8b02..e4cada0d34 100644 --- a/.claude/skills/kb-pr-review/SKILL.md +++ b/.claude/skills/kb-pr-review/SKILL.md @@ -158,6 +158,7 @@ For each file in `KB_FILES`: | **product-names** | **Product Names** | Always cross-check product IDs against `src/config/products.js` — the style guide table may be outdated. The config file is authoritative. | | **keywords-quality** | **Frontmatter > Required fields > keywords** | If a keyword does not appear in the article body but is a plausible legacy or alternate search term (e.g., an old product acronym), note it as a low-priority observation rather than a required fix. | | **images** | **Screenshots** | KB image structure is not in the style guide — apply this rule: images must be stored as PNG files in `0-images/` at the **product level** (`docs/kb//0-images/`), not inside category subfolders. Articles in category subfolders reference them with `../0-images/filename.png`. Flag any images linked from external sources (e.g., GitHub CDN URLs) — they must be downloaded and committed to the repo. | +| **links** | (not in style guide) | Find every internal markdown link in the article body — `[text](/docs/...)` patterns to other KB articles and to versioned product docs. For each, resolve the actual target file on disk: check for a `slug` frontmatter override on the target first; if none, the URL segment must match the target's real path/filename (not its `sidebar_label` or `title`). Flag any link whose URL does not resolve to a real file on disk as a Required fix, and correct it to the real path. External links (non-`/docs` URLs) are out of scope. Backstop is `npm run build` (`onBrokenLinks: 'throw'` in `docusaurus.config.js`), but that runs late — this check catches broken links before submission. | | **formatting** | **Markup Conventions** and **Lists** | The style guide's "single backticks for inline code" applies to error codes (e.g., `0x80070005`) — flag any error code in plain text. Sequential procedures must be numbered lists — this applies to Resolution sections and all sub-sections within them (e.g., verification steps), not just top-level procedures. | | **prose-directness** | **Voice and Tone > Impersonal constructions** and **Words and phrases to avoid** | Flag sentences where an impersonal subject ("the operation", "the process", "the system") could be replaced with the actual actor for a cleaner, more direct sentence. Example: "the operation fails with an error" → "Clicking **X** fails with an error". Apply judgment — not every impersonal subject is wrong. |