dev to main

.claude/skills/derek/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: derek
+description: KB article quality reviewer. Run against KB articles in docs/kb/ to review frontmatter, article type and structure, title format, product names, and keyword quality. Use when editing or reviewing any file under docs/kb/.
+argument-hint: "[docs/kb/path/to/article.md]"
+---
+
+# Overview
+
+You are Derek, a KB article quality reviewer for Netwrix. Your job is to review KB articles against `kb_style_guide.md` and flag issues that Vale and Dale do not catch.
+
+**What Vale already handles — do not re-flag these:**
+- Contractions (`NetwrixKB.Contractions`)
+- Heading case (`NetwrixKB.HeadingCase`)
+- "Please" in instructions (`NetwrixKB.Please`)
+- "Note that" inline (`NetwrixKB.NoteThat`)
+- Impersonal constructions (`NetwrixKB.ImpersonalFiller`)
+- Generic link text (`NetwrixKB.WeakLinkText`)
+- "Utilize" variants (`NetwrixKB.Utilize`)
+- First-person plural (`NetwrixKB.FirstPersonPlural`)
+
+**What Dale already handles — do not re-flag these:**
+- Passive voice
+- Minimizing difficulty words (simply, just, easily)
+- Idioms and colloquialisms
+- Wordiness
+- Undefined acronyms
+
+Derek focuses on what's left: frontmatter validity, article type and structure, title format, product name usage, and keyword/description quality.
+
+# How to Review
+
+1. Read `kb_style_guide.md` from the repo root.
+2. Read the article at `$1`. Always read the file directly from disk — do not use any version of this file that may be in context from earlier in the session.
+3. Identify the article type (see below).
+4. Work through each review area.
+5. Output the assessment line and table.
+
+# Article Type Identification
+
+Determine the article type from the title:
+
+- Title starts with `Error:` → **Resolution (Error)**
+- Title starts with a gerund (verb ending in -ing, e.g., "Configuring...", "Modifying...") → **How-To (Instructions)**
+- Title is a question or starts with "How to" → **How-To (Q&A)**
+- Everything else → **Resolution (Symptom)**
+
+# Review Areas
+
+## 1. Frontmatter
+
+Check that all required fields are present and valid:
+
+| Field | What to check |
+|---|---|
+| `title` | Present; quoted if it contains colons or special characters |
+| `description` | Present, non-empty, 1–2 sentences |
+| `sidebar_label` | Present, non-empty |
+| `keywords` | Present, contains 8–12 items |
+| `products` | Present, contains at least one product ID |
+| `tags` | Present and includes `kb` |
+| `knowledge_article_id` | If present, must not be empty — a non-empty value must start with `kA` followed by alphanumeric characters. If absent, do not flag. |
+
+Flag each missing or invalid field as a separate row in the output table.
+
+## 2. Article Structure
+
+Check that the required H2 headings are present for the identified article type:
+
+| Type | Required headings |
+|---|---|
+| Resolution (Error or Symptom) | `## Symptom` or `## Symptoms`, `## Cause` or `## Causes`, `## Resolution` or `## Resolutions` |
+| How-To (Instructions) | `## Overview`, `## Instructions` |
+| How-To (Q&A) | `## Question`, `## Answer` |
+
+When a required heading is missing, include the full expected heading template in the Message column so the writer can copy it in.
+
+## 3. Title Format
+
+Check that the title matches the expected format for the article type:
+
+- **Resolution (Error):** starts with `Error:` followed by the unique error code or message
+- **How-To:** starts with a gerund — not "How to", no question mark
+- **Resolution (Symptom):** `[Feature or Component] [Symptom] [Optional: Context]` — descriptive, not vague (e.g., "AD not working" is too vague)
+
+Also check: title must not contain a product name — product names belong in the `products` frontmatter field.
+
+## 4. Product Names
+
+Check that Netwrix product names follow the correct pattern from `kb_style_guide.md`:
+
+- First mention in body text: full product name (e.g., "Netwrix Auditor")
+- All subsequent mentions: short product name (e.g., "Auditor")
+- No unapproved abbreviations (e.g., "NA" for Netwrix Auditor)
+
+## 5. Admonition Format
+
+KB articles use blockquote callouts, not Docusaurus admonition syntax. Flag any `:::note`, `:::tip`, `:::warning`, or `:::danger` blocks and tell the writer to convert them:
+
+- `> **NOTE:**` — for supplementary information
+- `> **IMPORTANT:**` — for critical information that could cause issues if ignored
+
+## 6. Keywords and Description Quality
+
+**Keywords:** The 8–12 keywords should be specific and searchable — error codes, product names, technical terms, and phrases a customer would type into a search bar. Flag if keywords are too generic, simply repeat the title, or are missing obvious terms visible in the article body.
+
+**Description:** Should be 1–2 sentences, SEO-friendly, and accurately summarize what the article covers and what it helps the reader do. Flag if empty, too vague, or a verbatim copy of the title.
+
+# Output
+
+**Output format is strictly required. Do not use a vertical list, prose paragraphs, or any other format. Always use the table below.**
+
+Print the assessment line first:
+
+> **Article type:** [How-To (Instructions) | How-To (Q&A) | Resolution (Error) | Resolution (Symptom) | Unknown] — **[N] issue(s) found.**
+
+Then print the markdown table. Every issue must be a row in this table — no exceptions:
+
+| Line | Rule | Message | Offending Text |
+|------|------|---------|----------------|
+| 1 | `frontmatter-tags-kb` | The `tags` field must be present and must include `kb`. | `tags: []` |
+
+If no issues are found, print the assessment line followed by "Derek found no issues." Do not print an empty table.
+
+**Consolidating structure violations:** When multiple required headings are missing for the same article type, use a single `structure-article-type` row. List all missing headings in the Message column. If fixing the title would change the article type and resolve the structure issue automatically, note that in the Message.
+
+**Line number guidance:**
+- Frontmatter field missing entirely: use line `1`
+- Frontmatter field present but invalid: use the line number of that field
+- Missing required heading: use line `1`; include the expected heading template in Message
+- Title format violation: use the line number of the H1 heading
+- Product name violation: use the line number of the offending text
+- Keywords or description quality issue: use the line number of the field in frontmatter
+
+# Troubleshooting
+
+Never re-flag issues that Vale or Dale already catch. Never respond with anything beyond the assessment line and output table.

.claude/specs/2026-04-07-derek-design.md

@@ -0,0 +1,206 @@
+# Derek Skill — Design Spec
+
+**Date:** 2026-04-07  
+**Status:** Approved
+
+---
+
+## Summary
+
+Derek is a Claude skill that lints KB articles against the Netwrix KB style guide. It is the KB equivalent of dale — pure input/output, no conversation. Invoked with `/derek <kb-file>`.
+
+Two deliverables:
+1. `kb_style_guide.md` — new file at repo root, authoritative style reference for KB articles
+2. `.claude/skills/derek/` — the skill itself
+
+---
+
+## Context
+
+- KB articles live in `docs/kb/<product>/`
+- They are written by TSEs (technical support engineers), not the docs team
+- They follow a different style guide than regular product docs
+- The `feature/frontmatter-autoinjection` script explicitly skips KB files (`docs/kb/*`) because their frontmatter schema is more complex — derek handles it instead
+- Dale enforces the docs style guide (`netwrix_style_guide.md`). Derek enforces the KB style guide (`kb_style_guide.md`). **The two guides conflict on contractions and heading case — do not run `/dale` on KB files.**
+
+---
+
+## Deliverable 1: `kb_style_guide.md`
+
+Created at the repo root alongside `netwrix_style_guide.md`.
+
+**Source:** Internal wiki KB style guide (`knowledge-style-guide-markdown.md`), with the following additions and overrides.
+
+### Additions (from docs style guide — apply universally)
+
+- No "please" in instructions — be direct
+- No "simply", "just", "easily", "basically", "obviously"
+- No inline "note that" / "please note" — use admonition blocks
+- No impersonal constructions: "it is recommended / necessary / possible / required / advised / suggested"
+- Active voice — with examples
+- Define technical terms and acronyms on first use
+- Descriptive link text — never "click here", "read more", "learn more", "see more"
+
+### Overrides (wiki rule takes precedence over docs style guide)
+
+| Topic | KB rule |
+|---|---|
+| Contractions | Write out in full: "do not", "cannot", "you will" |
+| Heading case | Title case (Chicago style, capitalizemytitle.com) |
+
+### Tags field — required, must include `kb`
+
+The wiki marks `tags` as optional. **This is overridden for the Netwrix repo:** `tags` must be present and must include `kb`. This enables KB article filtering in Algolia search — Algolia indexes the `tags` field automatically, no Algolia config changes required.
+
+### Frontmatter schema
+
+All KB articles must have this frontmatter:
+
+```yaml
+---
+description: >-
+  Short, SEO-friendly summary of the article (1–2 sentences).
+keywords:
+  - keyword one
+  - keyword two
+  - (8–12 items total)
+products:
+  - product-id
+sidebar_label: 'Article Title'
+tags:
+  - kb
+title: "Full Article Title"
+knowledge_article_id: kA0Qk000000XXXXKAA
+---
+```
+
+**Required fields:**
+
+| Field | Format |
+|---|---|
+| `title` | Quoted string — full article title |
+| `description` | Non-empty string or `>-` multiline block |
+| `sidebar_label` | Quoted string — matches or shortens the title |
+| `keywords` | YAML list of 8–12 technical/product search terms |
+| `products` | YAML list of product IDs (see product names table) |
+| `tags` | YAML list; **must include `kb`** |
+| `knowledge_article_id` | Salesforce KB article ID matching `kA[0-9A-Za-z]+` |
+
+---
+
+## Deliverable 2: `.claude/skills/derek/`
+
+### Architecture
+
+Mirrors dale exactly: `SKILL.md` + `rules/*.yml` + `references/rule-schema.yml`. Option A chosen over Option B (split `rules/` and `checks/`) because the output and invocation are identical, and the added complexity of two processing loops in SKILL.md provides no user-facing benefit. The `reason` field in rule files describes what to look for — equally valid for prose patterns and structural assertions.
+
+### File layout
+
+```
+.claude/skills/derek/
+  SKILL.md
+  rules/
+    frontmatter-title.yml
+    frontmatter-description.yml
+    frontmatter-sidebar-label.yml
+    frontmatter-keywords-count.yml
+    frontmatter-products.yml
+    frontmatter-tags-kb.yml
+    frontmatter-knowledge-article-id.yml
+    structure-article-type.yml
+    no-please.yml
+    minimizing-difficulty.yml
+    no-note-that.yml
+    impersonal-constructions.yml
+    passive-voice.yml
+    undefined-jargon.yml
+    descriptive-links.yml
+    contractions.yml
+    title-case-headings.yml
+    business-jargon.yml
+  references/
+    rule-schema.yml
+```
+
+18 rules total: 7 frontmatter, 1 structure, 10 prose.
+
+### SKILL.md behavior
+
+- Pure linter — no conversation, no explanation beyond the output table
+- Creates a Todo for each rule file
+- For each rule: reads `reason`, checks the document, notes violations
+- Outputs a single table at the end (or "no issues found")
+- Includes a warning: **do not run `/dale` on KB files** — the KB style guide and docs style guide conflict on contractions and heading case
+
+### Output format (same as dale)
+
+```
+| Line | Rule | Message | Offending Text |
+|------|------|---------|----------------|
+```
+
+- Frontmatter violations where a field is missing: Line is `1` (frontmatter block start)
+- Structure violations: Line is the line number of the first mismatched or missing heading
+- Structure violations where sections are entirely missing: message includes the expected heading template the writer can copy in
+
+---
+
+## Rules detail
+
+### Frontmatter rules
+
+| File | Level | Checks |
+|---|---|---|
+| `frontmatter-title.yml` | error | `title` present and is a quoted string |
+| `frontmatter-description.yml` | error | `description` present and non-empty |
+| `frontmatter-sidebar-label.yml` | error | `sidebar_label` present and non-empty |
+| `frontmatter-keywords-count.yml` | warning | `keywords` present and contains 8–12 items |
+| `frontmatter-products.yml` | error | `products` present with at least one item |
+| `frontmatter-tags-kb.yml` | error | `tags` present and includes `kb` |
+| `frontmatter-knowledge-article-id.yml` | error | `knowledge_article_id` present and matches `kA[0-9A-Za-z]+` |
+
+### Structure rule
+
+| File | Level | Checks |
+|---|---|---|
+| `structure-article-type.yml` | warning | Infers article type from title, validates required H2 headings are present |
+
+**Type inference logic:**
+- Title starts with `"Error:"` → Error Resolution → expects `## Symptom/Symptoms`, `## Cause/Causes`, `## Resolution/Resolutions`
+- Title starts with a gerund or `"How to"` → How-To → expects `## Overview` + `## Instructions`, or `## Question` + `## Answer`
+- Everything else → Symptom Resolution → expects `## Symptom/Symptoms`, `## Cause/Causes`, `## Resolution/Resolutions`
+
+When required headings are missing, the violation message outputs the expected heading template for the inferred type.
+
+### Prose rules
+
+| File | Level | Checks |
+|---|---|---|
+| `passive-voice.yml` | warning | Passive voice constructions in body text |
+| `no-please.yml` | warning | "please" in instructions |
+| `minimizing-difficulty.yml` | warning | "simply", "just", "easily", "basically", "obviously" |
+| `no-note-that.yml` | warning | Inline "note that" or "please note" |
+| `impersonal-constructions.yml` | warning | "it is recommended/necessary/possible/required/advised/suggested" |
+| `contractions.yml` | warning | Contractions (don't, can't, you'll, etc.) — write out in full in KB articles |
+| `title-case-headings.yml` | warning | Headings not in title case (Chicago style) |
+| `business-jargon.yml` | warning | "utilize/utilise", "leverage" (non-financial), "synergy" |
+| `descriptive-links.yml` | warning | Generic link text: "click here", "read more", "learn more", "see more", "this link" |
+| `undefined-jargon.yml` | warning | Technical terms or acronyms used without definition on first use |
+
+`undefined-jargon.yml` is `warning` (not `error`) because it requires the most judgment and is the most likely source of false positives.
+
+---
+
+## Branch
+
+New feature branch off `dev`: `feature/derek-skill`
+
+---
+
+## Notes on existing articles
+
+Article scan (15 articles across 6+ products) found:
+- **Tags**: All articles have either `tags: []` or category-based tags — no article has `kb` in tags. `frontmatter-tags-kb` will fire on every existing article.
+- **Keyword count**: Range 3–9 across sampled articles, below the 8–12 requirement. `frontmatter-keywords-count` will fire frequently.
+- **Missing sidebar_label**: One article found without it.
+- These are expected and reflect the remediation work derek is meant to surface.

.vale.ini

@@ -5,4 +5,4 @@ MinAlertLevel = suggestion
 BasedOnStyles = Netwrix
 
 [docs/kb/**/*.md]
-BasedOnStyles =
+BasedOnStyles = NetwrixKB

.vale/styles/NetwrixKB/Contractions.yml

@@ -0,0 +1,32 @@
+extends: existence
+message: "Write '%s' out in full for KB articles (e.g., 'do not', 'cannot', 'you will')."
+level: warning
+ignorecase: true
+tokens:
+  - "don't"
+  - "doesn't"
+  - "didn't"
+  - "can't"
+  - "wouldn't"
+  - "shouldn't"
+  - "couldn't"
+  - "isn't"
+  - "aren't"
+  - "wasn't"
+  - "weren't"
+  - "hasn't"
+  - "haven't"
+  - "hadn't"
+  - "you'll"
+  - "it's"
+  - "there's"
+  - "that's"
+  - "won't"
+  - "we're"
+  - "they're"
+  - "you're"
+  - "he's"
+  - "she's"
+  - "we've"
+  - "they've"
+  - "you've"

.vale/styles/NetwrixKB/FirstPersonPlural.yml

@@ -0,0 +1,10 @@
+extends: existence
+message: "Avoid first person plural '%s'. Rewrite without 'we', 'our', 'us', or 'ours'."
+level: warning
+ignorecase: true
+nonword: true
+tokens:
+  - '\bwe\b'
+  - '\bour\b'
+  - '\bours\b'
+  - '\bus\b'