From 21428670ad9646e2f69f14214170142ec555c60b Mon Sep 17 00:00:00 2001 From: Hannes Blut Date: Fri, 24 Jul 2026 12:36:03 +0200 Subject: [PATCH 1/2] chore: improve docs skills Adds guardrails to check-doc skills. Added review docs skill, which takes a look at docs from various different perspectives to critique the information and style of the documents. On-behalf-of: @SAP Assisted-by: Copilot:gpt-5.3-codex Signed-off-by: Hannes Blut --- .claude/skills/check-doc-consistency/SKILL.md | 16 + .claude/skills/check-doc-drift/SKILL.md | 22 ++ .claude/skills/check-doc-expressions/SKILL.md | 24 ++ .claude/skills/check-doc-structure/SKILL.md | 24 ++ .../skills/review-docs-human-issue/SKILL.md | 319 ++++++++++++++++++ 5 files changed, 405 insertions(+) create mode 100644 .claude/skills/review-docs-human-issue/SKILL.md diff --git a/.claude/skills/check-doc-consistency/SKILL.md b/.claude/skills/check-doc-consistency/SKILL.md index 9599948b0..0590c0d6c 100644 --- a/.claude/skills/check-doc-consistency/SKILL.md +++ b/.claude/skills/check-doc-consistency/SKILL.md @@ -108,6 +108,22 @@ Group by severity: End with a verdict for the doc family or topic. +### 5. Verification guardrails + +Before finalizing findings: + +- Quote the exact conflicting text from both sides when possible (doc vs + doc, or doc vs source). +- Cite concrete `file:line` locations for both sides of the mismatch. +- If you cannot ground one side with a concrete citation, keep the + finding but mark it **needs research** and do not classify it as + **HIGH**. +- Re-check every **HIGH** finding against the current checkout just before + output to avoid stale or already-fixed claims. + +A zero-finding run is valid. If no contradictions are found, output an +explicit clean verdict instead of inventing weak findings. + ## Notes - This skill is read-only; hand findings to [[fix-docs]] to apply them. diff --git a/.claude/skills/check-doc-drift/SKILL.md b/.claude/skills/check-doc-drift/SKILL.md index 96e6ca868..af6c38717 100644 --- a/.claude/skills/check-doc-drift/SKILL.md +++ b/.claude/skills/check-doc-drift/SKILL.md @@ -116,6 +116,28 @@ For each finding give one line with a `file:line` reference for both the doc side and the source side. End with a two- to three-sentence health verdict per doc area. +### 4. Verification guardrails + +Before finalizing findings: + +- Quote the exact doc text and the exact source-side text that disagree. +- Include `file:line` for both sides of every finding. +- If you cannot quote or locate one side precisely, downgrade the finding + to **MEDIUM** or **LOW** and mark it **needs research**. +- Re-open and re-check every **HIGH** finding against the current + checkout before output. + +A zero-finding run is valid. If docs and source match for the audited +scope, report a clean result. + +### 5. Suppressions (do not report) + +- Pure style or tone issues with no factual mismatch (hand those to + [[check-doc-expressions]]). +- Naming preferences that are not contradictory and do not mislead the + reader. +- Weak "might be stale" guesses without a concrete conflicting source. + ## Drift patterns These recurring shapes are worth grepping for first: diff --git a/.claude/skills/check-doc-expressions/SKILL.md b/.claude/skills/check-doc-expressions/SKILL.md index 82ab61cf2..9f7823505 100644 --- a/.claude/skills/check-doc-expressions/SKILL.md +++ b/.claude/skills/check-doc-expressions/SKILL.md @@ -145,6 +145,30 @@ Group by severity: End with a short verdict for the page or doc set. +### 6. Verification guardrails + +Before finalizing findings: + +- Quote the exact sentence, paragraph fragment, or command/context pair + that triggered the finding. +- Cite concrete `file:line` locations. +- If a readability claim is subjective and cannot be grounded in a + specific text defect, either rewrite it as a concrete defect or drop + it. +- Re-check every **HIGH** finding to ensure the cited text still exists + in the current checkout. + +A zero-finding run is valid. If prose is clear for the selected audience +and no comprehension-impacting defects are found, report a clean result. + +### 7. Suppressions (do not report) + +- Pure preference nits that do not change comprehension or actionability. +- Repetition-only comments when the repeated text is intentional for + safety-critical visibility. +- General statements like "too long" without a concrete place where + meaning is lost. + ## Notes - This skill is read-only; do not rewrite the page until the wording diff --git a/.claude/skills/check-doc-structure/SKILL.md b/.claude/skills/check-doc-structure/SKILL.md index e316418b8..a766d1d3b 100644 --- a/.claude/skills/check-doc-structure/SKILL.md +++ b/.claude/skills/check-doc-structure/SKILL.md @@ -120,6 +120,30 @@ Group by severity: End with a per-doc-family verdict. +### 7. Verification guardrails + +Before finalizing findings: + +- Quote the exact structural defect trigger (missing heading, stale nav + entry, broken anchor, unresolved link). +- Cite concrete `file:line` locations for source and target sides when + applicable. +- If a target cannot be resolved from the checkout, mark the finding as + **blocked** or **needs judgment** rather than guessing. +- Re-check every **HIGH** finding against current files before output. + +A zero-finding run is valid. If navigation and structure are sound, +report a clean result. + +### 8. Suppressions (do not report) + +- Cosmetic heading-style preferences when hierarchy and navigation are + still correct. +- Pure prose complaints with no structural impact (route to + [[check-doc-expressions]]). +- "Could be organized differently" suggestions without a concrete + discoverability or integrity failure. + ## Notes - This skill is read-only; hand findings to [[fix-docs]] to apply them. diff --git a/.claude/skills/review-docs-human-issue/SKILL.md b/.claude/skills/review-docs-human-issue/SKILL.md new file mode 100644 index 000000000..f73242a9e --- /dev/null +++ b/.claude/skills/review-docs-human-issue/SKILL.md @@ -0,0 +1,319 @@ +--- +name: review-docs-human-issue +description: >- + Review documentation end-to-end without skipping any section, then + produce a complete issue that lists user-facing problems with clear + evidence and severity. Use when asked to audit docs quality from a + human reader perspective, before release, or after major doc edits. +argument-hint: Target docs scope and audience +--- + +# Review docs and file a user-facing issue + +This skill performs a full documentation review from the perspective of a +human reader. It does not stop at technical correctness: it finds anything +that makes docs harder to use, trust, or follow. + +## When to use + +- You need a complete doc review and cannot skip sections. +- You need a single issue listing all problems found. +- You want findings prioritized by user impact. + +## Inputs + +- Scope: exact files or directories to review (for example `docs/` + `README.md`). +- Audience: who the docs are for (new user, operator maintainer, contributor). +- Personas: reader lenses to run during review. Include at least developer, + editor, and management consultant or business analyst unless explicitly scoped. +- Goal: quality audit, release readiness, onboarding readiness, or consistency pass. + +If one of these inputs is missing, infer from repository conventions and state +assumptions in the report. + +### Default persona set + +Use this set when personas are not supplied: + +- Developer: checks technical correctness, runnable steps, prerequisites, + and debugging paths. +- Editor: checks structure, readability, consistency of voice, grammar, + and heading flow. +- Management consultant or business analyst: checks business framing, + decision clarity, expected outcomes, assumptions, and trade-offs. +- Operator or SRE: checks operational safety, rollback guidance, + observability cues, and failure handling. +- New adopter: checks onboarding clarity, jargon load, and first-run success path. + +### Optional personas (use when relevant) + +- Security reviewer: checks secret handling, unsafe defaults, threat-model gaps, + and whether security caveats are visible at the moment of action. +- Platform owner: checks standardization, support boundaries, ownership model, + and whether docs align with platform operating constraints. +- Release manager: checks upgrade/rollback readiness, version provenance, + deprecation messaging, and readiness-gate clarity. +- Support engineer: checks diagnosability, symptom-to-cause mapping, + and whether triage paths are fast under incident pressure. +- Technical writer: checks flow, audience fit, ambiguity, and whether each section + explains intent before mechanics. +- Copy editor: checks grammar, punctuation, sentence economy, and consistency of + voice and terminology. +- Information architect: checks document structure, progressive disclosure, + section chunking, and findability of key tasks. +- UX writer: checks clarity of instructions, action labels, and whether users can + predict outcomes from wording alone. +- Non-native English reader: checks idioms, phrasal verbs, and dense phrasing that + increases reading difficulty. +- Executive skim reader: checks whether headings and first sentences convey status, + risk, and decision-relevant takeaways quickly. + +## Procedure + +### 1. Build complete review inventory + +Enumerate every in-scope document and section heading before reviewing content. +Use this as a checklist and do not mark completion until every item is read. + +- Include top-level pages, nested pages, frontmatter, headings, tables, + callouts, code blocks, and command examples. +- Track each section as `unreviewed`, `reviewed`, or `blocked`. +- If content is blocked (missing asset, broken include), create a finding for it. + +### 2. Review section-by-section with multi-persona lenses + +Read every section in order and evaluate it once per selected persona. + +- Clarity: can a reader understand this on first pass? +- Actionability: can they execute steps exactly as written? +- Navigation: can they find prerequisite or next-step information quickly? +- Trust: are claims specific, current, and consistent with nearby docs? +- Cognitive load: is the section concise enough for real usage? +- Error recovery: does the doc help when a step fails? + +Use persona-specific checks in addition to shared checks: + +- Developer: command correctness, version/source provenance, and troubleshooting depth. +- Editor: sentence quality, repetition control, term consistency, and section balance. +- Management consultant or business analyst: value narrative, business impact, + risk clarity, and decision support quality. +- Operator or SRE: runbook usefulness, rollback safety, and monitoring hints. +- New adopter: plain-language clarity and minimum context needed to succeed. + +Apply these deeper checks per persona: + +- Developer: + - Can every command be copied and run in sequence without hidden state? + - Are prerequisites introduced before first use (tools, env vars, permissions)? + - Are expected outputs specific enough to distinguish success from partial failure? + - Are fallback and debug paths attached to the step that commonly fails? +- Editor: + - Does each section open with intent, then action, then expected result? + - Are similar steps written with similar depth and tense? + - Is terminology stable across quick start variants and reference links? + - Are headings scannable and non-redundant in a long page? +- Management consultant or business analyst: + - Is the user value clear before procedural detail? + - Are trade-offs explicit (time, cost, risk, complexity, portability)? + - Are decision points visible with criteria, not just options? + - Is there a clear "what good looks like" outcome at each major milestone? +- Operator or SRE: + - Are blast radius, rollback path, and safe re-run semantics documented? + - Are health checks and timeout expectations actionable under pressure? + - Are operational ownership boundaries clear (who owns what component)? + - Are logs, conditions, and metrics references sufficient for first response? +- New adopter: + - Can a first-time reader complete the flow without repo-internal context? + - Is jargon either avoided or defined at first mention? + - Are platform-specific assumptions explicit (macOS/Linux, rootful/rootless)? + - Is the path from first success to next action obvious? + +Use these readability-focused checks when optional writing personas are selected: + +- Technical writer: + - Does each section answer "why this step exists" before "how to do it"? + - Are transitions explicit between prerequisite, action, and verification? + - Are warnings near the exact step where mistakes happen? +- Copy editor: + - Are long sentences split where comprehension drops? + - Are filler words, repeated qualifiers, and hedge phrases minimized? + - Is capitalization, hyphenation, and term spelling consistent? +- Information architect: + - Is critical path separate from optional depth and side quests? + - Are anchors, cross-links, and section labels predictable and scannable? + - Can readers recover quickly if they enter mid-page? +- UX writer: + - Do command intros set expectation and success criteria clearly? + - Are labels and callouts action-oriented rather than abstract? + - Does each step avoid hidden assumptions and implied context? +- Non-native English reader: + - Are idioms replaced with literal phrasing? + - Are dense noun clusters broken into shorter clauses? + - Are acronyms expanded at first mention when not universally known? +- Executive skim reader: + - Do section openings surface impact, risk, and time cost? + - Can a reader extract decision points from headings alone? + - Is there a concise milestone summary at major transitions? + +Escalate severity when multiple personas fail on the same section, especially +when New adopter + Operator or Developer are both impacted. + +### 3. Capture findings immediately with evidence + +For each problem, record: + +- Severity: `HIGH`, `MEDIUM`, or `LOW`. +- Confidence: `verified`, `likely`, or `uncertain`. +- Persona: which reader lens found the issue. +- Location: file path plus section heading. +- User impact: what fails or confuses the reader. +- Evidence: quote or summarize the problematic text precisely. +- Fix direction: the smallest safe improvement. + +Quote-or-demote rule: + +- If you cannot quote the triggering text, set confidence to + `uncertain` and do not classify the finding as `HIGH`. +- If a claim depends on behavior outside docs, cite the source file and + line (script, config, or code) or mark it as an open question. + +Persona evidence prompts: + +- Developer: include exact failing command or missing prerequisite. +- Editor: include sentence/section pair showing structure drift. +- Management consultant or business analyst: include missing decision criterion or business outcome. +- Operator or SRE: include missing rollback/check/observability cue. +- New adopter: include exact jargon or context gap that blocks first-run comprehension. +- Technical writer: include where intent is missing or order harms comprehension. +- Copy editor: include sentence-level readability defect and a simpler rewrite direction. +- Information architect: include structure/navigation mismatch and affected user path. +- UX writer: include unclear instruction wording and resulting user misinterpretation. +- Non-native English reader: include idiom or dense phrase and a literal alternative. +- Executive skim reader: include missing decision signal in headings or summary lines. + +Never merge unrelated problems into one finding. One user-visible defect per +finding keeps follow-up work precise. + +### 4. Apply decision rules for severity + +- `HIGH`: user is likely blocked, misled, or at risk of a wrong action. +- `MEDIUM`: user can proceed but with friction, ambiguity, or backtracking. +- `LOW`: polish issue that does not block progress. + +When uncertain between two levels, choose the higher level and explain why. + +### 5. Run completion checks + +Before producing output, confirm: + +- Every in-scope section is marked `reviewed` or `blocked`. +- Every selected persona has reviewed every in-scope section. +- Every finding includes impact and evidence. +- Duplicates are consolidated only when they are truly the same defect. +- Findings are sorted by severity, then by reader journey order. +- Every `HIGH` finding was re-checked against the current checkout + immediately before output. + +### 6. Produce the issue draft + +Output a ready-to-file issue with this structure: + +```markdown +Title: docs: user-focused quality review findings () + +## Summary +- Reviewed scope: ... +- Audience lens: ... +- Personas used: ... +- Sections reviewed: X/Y (blocked: Z) +- Findings: HIGH A / MEDIUM B / LOW C + +## Persona coverage +- Developer: reviewed X/Y sections +- Editor: reviewed X/Y sections +- Management consultant or business analyst: reviewed X/Y sections +- Operator or SRE: reviewed X/Y sections +- New adopter: reviewed X/Y sections + +## Persona summary +- Developer: top systemic gap +- Editor: top systemic gap +- Management consultant or business analyst: top systemic gap +- Operator or SRE: top systemic gap +- New adopter: top systemic gap + +## Findings +### HIGH +1. [Persona | file path - section heading] Problem statement + - Confidence: + - Impact: + - Evidence: + - Suggested fix: + +### MEDIUM +... + +### LOW +... + +## Coverage checklist +- [x] page/section 1 +- [x] page/section 2 +- [ ] page/section blocked (reason) + +## Open questions +- ... +``` + +## Branching guidance + +- If scope is very large, split review execution into batches but keep one final + merged issue. +- If domain facts are uncertain, log as `Open questions` instead of guessing. +- If a finding belongs to code behavior rather than docs quality, still record it + when it causes user confusion and tag it as cross-team follow-up. +- If the same defect appears across personas, keep one finding and list all + impacted personas in that entry. + +## Release-version handling + +- Do not encode or hardcode any release version in this skill text, findings + templates, or suggested fixes. +- When docs mention a release and it looks stale or unclear, report it as a + provenance finding: ask where the value is sourced from and point to the + source-of-truth file or generator path. +- Prefer wording such as "current supported release" or "value from release + source-of-truth" over embedding concrete release numbers. + +## Quality bar + +- No skipped sections. +- No vague findings without user impact. +- No purely stylistic nitpicks unless they affect comprehension. +- Output is issue-ready without extra cleanup. + +## Suppressions (do not report) + +- Pure style preferences with no clarity, trust, or actionability impact. +- "Could be shorter" feedback without a concrete point where meaning or + execution fails. +- Suggestions that rely on unstated assumptions and provide no quoted + evidence. +- Duplicate findings that restate the same user-visible defect. + +## Empty-result branch + +Zero findings is a valid outcome. If the reviewed scope is clear, +actionable, and trustworthy for the selected personas, output a clean +issue draft with: + +- Findings summary set to `HIGH 0 / MEDIUM 0 / LOW 0`. +- An explicit statement that no user-facing defects were found. +- Any residual risk listed only as open questions, not as invented + findings. + +## Related customizations + +- Pair with [[check-doc-consistency]] for contradiction detection. +- Pair with [[check-doc-structure]] for nav/frontmatter/link integrity. +- Pair with [[check-doc-expressions]] for prose clarity refinement. \ No newline at end of file From a5f416a9b9db226468fbe06298edd5c8d9104285 Mon Sep 17 00:00:00 2001 From: Hannes Blut Date: Fri, 24 Jul 2026 12:42:06 +0200 Subject: [PATCH 2/2] chore: add review-docs skill to contribution guide Mention review-docs-human-issue skill in contributing claude-skills docs On-behalf-of: @SAP Assisted-by: Copilot:claude-sonnet-4.6 Signed-off-by: Hannes Blut --- docs/contributing/claude-skills.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/docs/contributing/claude-skills.md b/docs/contributing/claude-skills.md index 62d3a8236..cba5ac99b 100644 --- a/docs/contributing/claude-skills.md +++ b/docs/contributing/claude-skills.md @@ -21,7 +21,9 @@ documentation itself — and report drift before it reaches a release. The suite also carries three **planners** (`prepare-new-service`, `prepare-new-release`, `prepare-new-guide`) that turn an onboarding or authoring task into a phased checklist, a **doc-fix driver** -(`fix-docs`) that turns audit findings into actual edits, and a +(`fix-docs`) that turns audit findings into actual edits, a +**human-reader reviewer** (`review-docs-human-issue`) that produces a +complete user-facing issue from a full end-to-end doc pass, and a **runbook** (`debug-e2e-failure`) for diagnosing failing chainsaw e2e jobs. @@ -131,6 +133,7 @@ a companion Bash script (the deterministic part). | [`prepare-new-guide`](https://github.com/c5c3/forge/blob/main/.claude/skills/prepare-new-guide/SKILL.md) | Scaffolds a new how-to guide skeleton under `docs/guides/` for a chosen devstack anchor and validates draft guides against the guide conventions — placeholder names no tutorial produces, devstack↔flag consistency, raw-helm instructions against Flux-owned releases, projected-child edits without a revert warning. Defers to `tests/unit/docs/guide_devstack_and_tested_by_test.sh` as the authoritative gate. | When writing a new guide under `docs/guides/`; when checking a draft guide for convention violations. | | [`debug-e2e-failure`](https://github.com/c5c3/forge/blob/main/.claude/skills/debug-e2e-failure/SKILL.md) | Diagnoses a failing chainsaw e2e job — resolves the failed run, pulls the failed-step logs and JUnit/diagnostic evidence, maps the failure back to the suite directory under `tests/`, classifies it against the known flake patterns, and reproduces it locally against a kind cluster. | When any CI e2e job fails (`e2e-operator`, `e2e-chaos`, `e2e-controlplane`, …); when reproducing an e2e failure locally. | | [`fix-docs`](https://github.com/c5c3/forge/blob/main/.claude/skills/fix-docs/SKILL.md) | Applies fixes for findings produced by `check-doc-consistency`, `check-doc-expressions`, and `check-doc-structure` — or runs those audits first if no findings are supplied. Classifies each finding as mechanical (safe to apply directly), a judgment call (propose first, confirm before applying), or needs-research (establish the correct fact before writing anything), then edits the docs and re-verifies with the originating audit. | When asked to fix documentation issues; when actioning a docs audit report; when cleaning up findings from `check-doc-consistency`, `check-doc-expressions`, or `check-doc-structure`. | +| [`review-docs-human-issue`](https://github.com/c5c3/forge/blob/main/.claude/skills/review-docs-human-issue/SKILL.md) | Reviews documentation end-to-end from a human reader's perspective — does not stop at technical correctness but finds anything that makes docs harder to use, trust, or follow — and produces a single issue listing all problems with clear evidence and severity. | When asked to audit docs quality from a human reader perspective; before release; after major doc edits. | ## What a skill is, structurally