docs-checker

# Documentation Grammar & Style Checker Check documentation files for grammar, punctuation, and style errors. Minimize changes: only fix actual errors. Do not rewrite or restructure text, do not add content, do not remove blocks of text. ## Selecting files to check - **With arguments** (`$ARGUMENTS`): check only the specified files or glob patterns. - **Without arguments**: check `.rst` and `.py` files changed on the current branch vs `main`. Run: ``` git diff main...HEAD --name-only -- '*.rst' '*.py' ``` If there are no changes vs main (e.g., on main itself), ask the user which files to check. ## What to check Only check **prose text**: skip code blocks, directive parameters, RST markup syntax, and inline code literals. For `.py` files, only check docstrings (triple-quoted strings), not comments or code. ### 1. Contractions (expand to full words) Find and expand all contractions. Common ones: | Wrong | Correct | |-------|---------| | don't | do not | | doesn't | does not | | didn't | did not | | can't | cannot | | won't | will not | | shouldn't | should not | | wouldn't | would not | | couldn't | could not | | isn't | is not | | aren't | are not | | wasn't | was not | | weren't | were not | | haven't | have not | | hasn't | has not | | hadn't | had not | | it's (it is) | it is | | let's | let us | | that's | that is | | there's | there is | | we're | we are | | they're | they are | | you're | you are | | I'm | I am | | we've | we have | | they've | they have | ### 2. Common misspellings | Wrong | Correct | |-------|---------| | authentification | authentication | | ceritificate, certifcate | certificate | | supplimentary | supplementary | | temporaily | temporarily | | withing | within | | exessive | excessive | | unexistent | nonexistent | | outcoming | outgoing | | inbetween | in between | | loose (meaning fail) | lose | | Persistant | Persistent | | Datenshutz | Datenschutz | | namepsace | namespace | | resouce | resource | | occured | occurred | | succeded | succeeded | | seperate | separate | | neccessary | necessary | | dependancy | dependency | | compatability | compatibility | ### 3. Incorrect idioms and phrases | Wrong | Correct | |-------|---------| | so as (meaning "as well as") | as well as | | allows to \<verb\> | allows \<verb\>ing | | might be not | might not be | | can be also | can also be | | diverts from (meaning deviates) | diverges from | | more on that | moreover | | not only it is | not only is it | | does not do any attempts | does not make any attempts | | cleanup (as a verb) | clean up (verb is two words) | ### 4. Passive voice → active voice Convert passive to active where it reads more naturally. Use appropriate subjects: - **Kopf** when referring to the framework itself - **the operator** when referring to operators built with Kopf - **the handler** when referring to handler functions - **the user** or **you** when referring to the developer using Kopf Examples: - "It is used for ..." → "Kopf uses it for ..." - "The state is stored in ..." → "Kopf stores the state in ..." - "Multiple namespaces can be served" → "The operator can serve multiple namespaces" Do not force active voice when passive reads more naturally or when the actor is genuinely unknown. ### 5. Articles and agreement - Check for missing articles (a, an, the) before singular countable nouns - Check subject-verb agreement ("the handler run" → "the handler runs") - Check pronoun agreement ("Handlers ... its" → "Handlers ... their") ### 6. Em dashes Use `---` (triple-minus) for em dashes in RST files. Replace any unicode em dash (`—`, U+2014) or double-minus (`--`) used as an em dash with `---`. | Wrong | Correct | |-------|---------| | `—` (unicode U+2014) | `---` | | `--` (used as em dash) | `---` | ### 7. RST-specific issues - Markdown-style links in `.rst` files: `[text](url)` should be `` `text <url>`_ `` - Incorrect capitalization of abbreviations: "RsT" → "RST", "yaml" → "YAML", "json" → "JSON" ### 8. American English consistency Use American English spelling when the file already uses it: | British | American | |---------|----------| | behaviour | behavior | | colour | color | | synchronised | synchronized | | capitalised | capitalized | | organisation | organization | | favour | favor | | honour | honor | ## Process 1. Determine which files to check (from arguments or git diff). 2. Read each file fully. 3. Scan prose text (skip code blocks and RST directives) for issues from the checklist above. 4. For each issue found, apply a fix using the Edit tool. 5. After fixing all files, report a summary of changes made per file. ## Important rules - **Minimize changes.** Only fix actual errors. Do not improve wording that is already correct. - **Do not touch code blocks**, inline code, directive parameters, or RST/Markdown structural markup. - **Do not remove or restructure text.** Keep the original meaning and structure intact. - **Do not add content** such as new paragraphs, comments, docstrings, or annotations. - **Preserve the author's voice.** Only fix what is objectively wrong or inconsistent.