Add kb-writer and kb-pr-open skills - #1358
Conversation
Generated with AI Co-Authored-By: Claude Code <ai@netwrix.com>
Address code review: base the all-clean exit on branch state (git status/log vs dev) instead of run-local fix count, so already-committed content isn't stranded; use safe branch -d gated on no unmerged commits; drop personal machine path from the PR description memory reference. Generated with AI Co-Authored-By: Claude Code <ai@netwrix.com>
Address second code review round: - Fetch origin/dev before diffing and use the remote-tracking ref instead of a bare dev, which may not exist locally or may be stale; fail open to Step 5 if the git commands error instead of treating a failure as "clean." - Resolve kb-pr-open's internal self-contradiction on knowledge_article_id: the field's state is informational only, so drop the "add it if missing" and "must always be present" language that conflicted with the documented never-add/never-remove policy. - Drop citations to feedback_kb_* memory files that don't exist in the repo and are unreachable for other TSEs; the conventions they referenced are already inlined in the skill. Generated with AI Co-Authored-By: Claude Code <ai@netwrix.com>
Address third code review round: - Step 1 now strips a trailing "+ verbose" token before validating file paths, so the documented invocation form doesn't fail its own path check. - All-clean exit message now switches to dev before running git branch -d, since git refuses to delete the branch you have checked out. Generated with AI Co-Authored-By: Claude Code <ai@netwrix.com>
Address fourth code review round: - Move the stray ":::note is not the KB format" guidance out of the title:semantic Derek row (unrelated to titles, only read while scoring titles) into a new scan row (23) that actually enforces it: flag ::: admonitions and convert to blockquote callout form per kb_style_guide.md. Update row-count references from 22 to 23 accordingly. - All-clean exit now suggests git switch --detach origin/dev before git branch -d, since evaluating merge status against a stale or missing local dev could falsely refuse a delete. The shared-rule-drift finding (kb-pr-open vs kb-pr-review) is the same class of issue as the already-tracked dedup follow-up; evidence added as a comment on that issue instead of fixing here. Generated with AI Co-Authored-By: Claude Code <ai@netwrix.com>
Address fifth code review round: - Step 1 now checks Vale availability up front, and both this and the Step 2 fallback note render a missing/erroring Vale as "not run (Vale not installed)" rather than a silent false "Clean" row. - Ported the NetwrixKB scoping sentence explaining why KB files fire NetwrixKB.* rules only, and dropped BoilerplateCrossRef from the WeakLinkText fix guidance since that rule lives only in the Netwrix style and can never fire on docs/kb/ files. - Links check now recognizes pathname:///docs/... (the form rulebook §8 mandates for internal cross-doc links, in active use in 10 KB articles) in addition to /docs/..., and flags dotted version segments (8.2 instead of 8_2) per the same section. Restored the npm run build backstop note. - All-clean short-circuit pathspec widened from docs/kb/ to docs/, matching the blast radius of the title-change link-text sweep that runs immediately before it. The same BoilerplateCrossRef and pathname:// gaps exist in kb-pr-review (inherited, not introduced here); documented as follow-up evidence on the tracked dedup issue instead of fixing kb-pr-review in this PR. Generated with AI Co-Authored-By: Claude Code <ai@netwrix.com>
…e check Address sixth code review round: - kb_style_guide.md and derek/SKILL.md incorrectly allowed plural resolution headings (## Symptoms/## Causes/## Resolutions), contradicting kb-pr-open's and kb-pr-review's singular-only rule. Singular-only is the correct, established convention (confirmed by kb-pr-review); corrected the style guide and derek to match, and dropped the plural forms from kb-writer's Section Depth table. - All-clean short-circuit in kb-pr-open now checks the whole working tree and full branch history vs. origin/dev, not just docs/ — the exit message claims the tree is clean enough to delete the branch, which a docs/-scoped check couldn't actually establish (e.g. an uncommitted static/ asset would be invisible to the old pathspec). Generated with AI Co-Authored-By: Claude Code <ai@netwrix.com>
Address seventh code review round: drop the stale "scope the pathspec to docs/" lead-in sentence, left over from an earlier revision, that contradicted the no-pathspec code block and whole-tree wording that already follow it. Reviewer's rulebook §12 circular-reference finding did not reproduce — §12 already contains the raw log-line/error-dump title rule content, not just a pointer back to the skill. Migration debt (169 files with plural resolution headings) and the cross-section table row-count drift vs. the rulebook are documented as follow-up evidence on the tracked dedup issue. Generated with AI Co-Authored-By: Claude Code <ai@netwrix.com>
When Vale is missing, Step 1 told the agent to jump straight to Step 3 (report), bypassing Step 2 (Dale and Derek) entirely. Step 3's N/N-scanned receipt mechanism would then certify checks that never ran, producing a false all-clean report on exactly the fresh-machine case (Vale not yet installed) this skill's TSE audience is most likely to hit. Point to Step 2 instead, which already has the correct continue-on-error guard for Vale. Generated with AI Co-Authored-By: Claude Code <ai@netwrix.com>
- Step 7 Option A now confirms with the TSE before running git
push, matching the skill's own stated rule ("does not run git
operations without explicit TSE approval") — the push was the
only ungated git action in the flow.
- "Update existing PR" no longer claims "I pushed" when Option B
means the TSE did the push, not the skill.
- Step 1's branch check now handles detached HEAD explicitly
(stop and warn) instead of falling through to "proceed," since
a later git push would have no upstream to resolve.
The Derek-rules-in-four-places finding is the same class of issue
as the tracked dedup follow-up; added as further evidence there.
The gh pr list fork-branch edge case is noted there too, flagged
as possibly out of scope rather than fixed.
Generated with AI
Co-Authored-By: Claude Code <ai@netwrix.com>
…t caveats - Create new PR Option A/B no longer tell the agent to push again — Step 7 item 1 already pushed (and now gates that push on TSE approval per the prior commit). Two push sites for one action was a leftover from before that gate existed. - Step 4 now skips the "Ready to apply fixes?" prompt when Step 3's report already shows zero Required fixes, going straight to the All-clean short-circuit instead. Kept the report-clean condition explicit rather than just reordering the git checks earlier — moving the short-circuit's git status/log checks alone in front of the prompt would have incorrectly short-circuited runs that found real, not-yet-fixed findings (nothing would be in git yet either way). - Added the same "recount if the table changes" caveat already on the Derek row to the kb-editing-conventions scan and cross-section consistency row counts, keeping the N/N scanned receipt honest as those tables grow. Generated with AI Co-Authored-By: Claude Code <ai@netwrix.com>
- Title-change link-text sweep grep pattern now makes pathname:// optional, so it catches pathname:///docs/... links (17 in the repo) instead of only the bare /docs/... form. - Links check no longer claims onBrokenLinks unconditionally throws — docusaurus.config.js relaxes onBrokenLinks/ onBrokenMarkdownLinks/onBrokenAnchors to warn for single-product builds (the faster path CLAUDE.md recommends), so the build backstop only reliably fails on a full build. - derek/SKILL.md now flags a pluralized resolution heading (## Symptoms/Causes/Resolutions) as a rename, not as a missing heading — matches the explicit heading-labels rule kb-pr-open and kb-pr-review already have, instead of relying on the presence check's generic "add this heading" message. - Reworded the "no git operations without approval" rule to carve out read-only status commands (fetch/status/log used internally by the all-clean short-circuit) from the approval gate that covers state-changing operations (commit, push, branch create/ delete) — the flow already ran the read-only commands unprompted; the stated rule now matches. - Disambiguated "no pathspec on either command" (which reads oddly against a 3-command block) to name status/log specifically. Generated with AI Co-Authored-By: Claude Code <ai@netwrix.com>
…d-HEAD note Proactive audit + latest review round, combined: - Restored "and represent sequential steps of the same procedure" to Gate B (scan row 8) — dropped relative to the rulebook and kb-pr-review, which would have applied Step N labeling to any 3+ subheadings regardless of whether they're actually sequential steps of one procedure. - Added the missing H1/sidebar_label-consistency bullet to the mechanical title-fix list — present in kb-pr-review, absent here, so the areas-table citation to this section pointed at content that wasn't there. - Repointed the ::: admonition rule's citation from kb_style_guide.md (which never mentions Docusaurus admonition syntax at all) to derek/SKILL.md §7, the actual source. - Links check and title-change sweep now also cover relative .md links (../other-article.md), which kb_style_guide.md's own "Do" example uses and which were previously excluded as "external." - All-clean exit message now tells the TSE to check out a branch before the next article, since the suggested branch-delete command intentionally leaves them on a detached HEAD, which this same skill's Step 1 guard would otherwise stop them on next run. Empirically verified (Vale installed locally) that NetwrixKB truly replaces rather than merges with Netwrix on docs/kb/ files, per a review round questioning that claim: a Netwrix-only rule (BoilerplateCrossRef) produced zero alerts on a docs/kb/ test file. kb-pr-open's existing guidance was already correct; no change needed there. kb-pr-review's contradicting guidance, plus its missing admonition scan row and stale link-sweep pattern, are already logged as follow-up evidence on the tracked dedup issue. Generated with AI Co-Authored-By: Claude Code <ai@netwrix.com>
…n, push -u
- Canonicalize the admonition-type list (note/tip/info/warning/danger/
important) across derek/SKILL.md §7 and kb-pr-open's scan rows 1
and 23 — the two files previously enumerated different four-item
subsets, neither covering :::info or :::danger (both in real use).
- Step 4's skip-the-prompt condition now keys on "zero findings of
any kind," not "zero Required fixes" — a file with only soft
reminders (semantic title reframes, knowledge_article_id notes,
low-priority keyword observations) was previously skipped past
the fix prompt entirely, giving the TSE no chance to act on them.
- All-clean exit message now has two variants: the original for
when the report was genuinely empty, and a new one for when
findings existed but were declined/dismissed — the old single
wording ("no fixes were needed") was false in the latter case.
- Step 7's numbered push step now carries the -u fallback that was
already in the STOP callout above it but not in the step actually
being executed, so a fresh branch with no upstream doesn't fail.
The Derek-rules-hardcoded finding and the un-anchored N/N receipt
risk are the same class of issue as the tracked dedup follow-up;
added as further evidence there, including the admonition-list
drift this commit fixes as a concrete example of the failure mode.
Generated with AI
Co-Authored-By: Claude Code <ai@netwrix.com>
Code ReviewScope note: this PR touches only agent-instruction markdown ( I verified the checkable claims in Three correctness issues, all in the same family: 1. The gerund-title carve-out contradicts both stated sources of truth
and its Bad example is Failure scenario: a Q&A article titled 2. Derek's rules are hardcoded in Step 2 opens with:
Vale points at That drift is still live in this PR.
The source list grew to six but the conversion-target list is still two. Suggest either pointing Derek's section in 3.
Failure scenario: Not blocking, just noting: 🤖 Generated with Claude Code |
1 participant
Adds Claude skills for creating KB pull requests