Docs Check Compliance

Check Documentation Compliance

Arguments

1. docs-file — Path to documentation file (e.g., docs/reference/xml.md)
2. rule-skill — Rule skill name (e.g., docs-writing-style, docs-mdoc-conventions)

CRITICAL REQUIREMENT

YOU MUST create a comprehensive checklist of all rules from the rule skill and systematically verify each rule step by step until ensuring complete compliance with zero violations. Do not skip rules, do not assume compliance without verification, and do not move forward until each rule is fully checked and any violations are fixed.

Workflow

Step 1: Load Rule Skill

You MUST use the Skill tool to invoke the rule skill. Do not substitute a different skill. Load it now:

Use the Skill tool with the rule-skill name. For example, if the rule-skill argument is docs-writing-style, invoke:

Skill: docs-writing-style

Read all rules it defines. For enumerated rule skills, note the rule numbers and create a checklist. These are the only rules you will enforce.

Not every rule skill is numbered. docs-mdoc-conventions, for one, is a decision tree and a set of named checks (modifier selection, public-symbols-only, admonition frequency, …), not a numbered list. When the rule skill has no numbers, build your checklist from its distinct named points instead — each named check or named subsection is one checklist item, cited by name rather than number (e.g. "mdoc-conventions: modifier-matches-decision-tree" instead of "rule 4").

Step 2: Read Doc File

Read the full documentation file to understand its current state.

Use the Read tool with the docs-file path. For example, if the docs-file argument is docs/reference/chunk.md, invoke:

Read: <PROJECT_ROOT>/docs/reference/chunk.md

Note: Always use absolute paths (starting from <PROJECT_ROOT>/)

Step 3: Check and Fix Each Rule

MUST: Create a comprehensive checklist of ALL rules defined by the rule skill. Number each rule and list it with its full name and description. Display this checklist to the user so they see exactly what will be checked.

Then, process each rule from the checklist sequentially, ensuring zero violations before moving to the next rule. Do not skip any rule. Do not assume compliance without verification.

For each rule in your checklist:

1. Identify violations — Use adversarial verification: assume the document fully complies with THIS RULE, then prove yourself wrong by finding evidence of violations. Cite exact line numbers, quote problematic text, and explain why it violates THIS RULE. If you cannot find evidence, this rule has zero violations.

2. Fix violations — Apply minimal edits (add, remove, edit, or restructure as needed). Preserve the intent of the document.

3. Commit immediately — Run:

   git add <docs-file>
   git commit -m "docs(<docs-file-stem>): fix <rule-name>"
   

   Example (numbered rule skill): git commit -m "docs(chunk): fix rule-2-sentence-clarity" Example (unnumbered rule skill): git commit -m "docs(chunk): fix mdoc-conventions modifier-selection"

Repeat steps 1–3 for each rule until zero violations remain, then proceed to the next rule.

Step 4: Compile

Run mdoc to verify the doc compiles without errors:

sbt "docs/mdoc --in docs/reference/chunk.md --out website/docs/reference/chunk.md"

(Substitute the actual docs-file path for both --in and --out — --out is the same path prefixed with website/.) Never bare sbt docs/mdoc without --in/--out — it recompiles every doc in the tree, minutes of sbt for a one-file check.

If mdoc fails, identify the error, fix it, and commit:

git add <docs-file>
git commit -m "docs(<docs-file-stem>): fix mdoc error"

Step 5: Report

Output a summary including:

• Total violations found and fixed per rule
• Which rules had zero violations (no changes needed)
• Final mdoc status (pass/fail)

Key Principles

• One commit per rule violation — not one big commit
• Commit immediately after each fix — don't batch
• Verify mdoc passes at the end — this is the final proof of correctness
• Be concise — minimal changes, preserve intent

Example Invocation

To check docs/reference/chunk.md against the docs-writing-style rule skill:

1. Load the rule skill: Skill: docs-writing-style
2. Read the doc file: Read: <PROJECT_ROOT>/docs/reference/chunk.md
3. For each rule, find violations, fix, and commit
4. Run: sbt "docs/mdoc --in docs/reference/chunk.md --out website/docs/reference/chunk.md"
5. Report results

Example commit message:

docs(chunk): fix rule-3-active-voice