Add an English-usage standard and wire it into fixing, review, and authoring#36
Merged
Merged
Conversation
Draft the task plan for establishing an org-wide English-usage standard: a shared error-catalog guideline, the stateless `proofread` fixer skill replacing `which-fixer`, English-usage checks in `review-docs` with wider Protobuf/TS/JS/Go scope, and authoring-side pointers. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Add guidelines/english-style.md — an error catalog for grammar, punctuation, and spelling in code comments (KDoc/Javadoc, Protobuf, TSDoc/JSDoc, Go) and Markdown docs, with leave-alone guards, per-language protections for machine-read comments, and the which/that rule migrated from which-fixer. Index it in _TOC.md and link it from the documentation, KDoc, Javadoc, and Protobuf pages. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Add skills/proofread — a stateless English-usage fixer that applies the english-style catalog to project-owned prose in comments and docs across Kotlin, Java, Protobuf, TypeScript, JavaScript, Go, Markdown, and AsciiDoc. It runs in three caller-selected modes: a branch-diff default, a full `all` sweep, and a path-scoped sweep; no memory sentinel. Extract the shared project-owned-file scoping into guidelines/project-owned-files.md, referenced by proofread and cross-linked from update-copyright. Retire which-fixer: delete its skill and command and swap the authoring-doc tier example; its which/that rule now lives in the english-style catalog. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Add check "E. English usage" to the review-docs skill: it applies the english-style catalog to changed prose lines, with a severity mapping (meaning-distorting -> Must fix, clear errors -> Should fix, debatable or catalog report-only cases -> Nit) and a pointer to the proofread skill for bulk fixes. Widen the reviewed scope from JVM sources plus Markdown to full Protobuf doc comments and TypeScript, JavaScript, and Go comments; a new Checks preamble marks prose checks (C/D/E) language-agnostic and structural checks (A/B) source-format-specific, and Check A now cites protobuf.md for message and field doc-comment structure. Broaden the pre-pr review-docs dispatch: it now runs whenever a changed hunk touches doc-comment or prose lines — any Markdown or Protobuf change (proto in addition to the build) and mixed code+comment JVM changes — not only on a docs-classified diff. Mirror the widened scope across the review-docs command, agent, and Codex wrappers and the pre-pr command wrapper. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Add a pointer to guidelines/english-style.md in the writer skill's documentation-conventions list, and a "fix genuine English errors while you are here" step to java-to-kotlin's Javadoc-to-KDoc conversion — the moment a comment is rewritten is the natural time to correct outright grammar, punctuation, and spelling errors and set the third-person KDoc summary verb, while preserving the author's meaning and voice. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
This PR introduces an organization-wide English-usage standard (grammar/punctuation/spelling) and wires it into the documentation authoring, reviewing, and remediation loop in the shared agents asset repo, replacing the narrower legacy which-fixer approach.
Changes:
- Added a unified English-usage catalog (
guidelines/english-style.md) and linked it from existing documentation guidelines and TOC. - Introduced a new
proofreadfixer skill (with Claude/OpenAI wrappers) and retiredwhich-fixer. - Extended
review-docsandpre-prto incorporate English-usage checking and broaden doc-comment scope (incl. Protobuf and TS/JS/Go).
Reviewed changes
Copilot reviewed 24 out of 24 changed files in this pull request and generated 1 comment.
Show a summary per file
| File | Description |
|---|---|
| skills/writer/SKILL.md | Adds english-style.md to authoring-time documentation conventions. |
| skills/which-fixer/SKILL.md | Removes the retired legacy fixer skill. |
| skills/which-fixer/agents/openai.yaml | Removes the retired legacy OpenAI wrapper. |
| skills/update-copyright/SKILL.md | Cross-references the shared “project-owned files” scoping definition. |
| skills/review-docs/SKILL.md | Broadens scope to more comment types and adds English-usage Check E. |
| skills/review-docs/agents/openai.yaml | Updates OpenAI wrapper prompt/description to match the new scope. |
| skills/proofread/SKILL.md | Adds the new remediation skill implementing the English-usage catalog. |
| skills/proofread/agents/openai.yaml | Adds the OpenAI wrapper for the proofread skill. |
| skills/pre-pr/SKILL.md | Updates reviewer dispatch logic to run review-docs on doc/prose hunks. |
| skills/java-to-kotlin/SKILL.md | Allows fixing clear English errors during Javadoc→KDoc conversion. |
| guidelines/protobuf.md | Links Protobuf doc-comment English rules to the new English style catalog. |
| guidelines/project-owned-files.md | Adds the shared definition for “project-owned” vs upstream-distributed files. |
| guidelines/kdoc.md | Links KDoc guidance to the English style catalog. |
| guidelines/javadoc.md | Links Javadoc guidance to the English style catalog. |
| guidelines/english-style.md | Adds the new English-usage error catalog and “Never edit” protections. |
| guidelines/documentation.md | Cross-links to English style as the language-quality reference. |
| guidelines/_TOC.md | Adds TOC entries for English style and project-owned files. |
| docs/authoring-skills.md | Updates examples to reference proofread instead of the retired which-fixer. |
| claude/commands/which-fixer.md | Removes the retired Claude command wrapper. |
| claude/commands/review-docs.md | Updates Claude command wrapper to the expanded review scope/checks. |
| claude/commands/proofread.md | Adds Claude command wrapper for proofread. |
| claude/commands/pre-pr.md | Updates wrapper text to match the new review-docs dispatch criteria. |
| claude/agents/review-docs.md | Updates Claude subagent wrapper to include English-usage checking. |
| .agents/tasks/english-usage-improvements.md | Adds task log/plan documenting the phased rollout work. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0d442b282e
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
Fixes for the Codex review findings: - proofread command wrapper: pass $ARGUMENTS (with an argument-hint) so the `all` and path modes are reachable from the slash command, and grant `git rm`/`rm` so the legacy which-fixer-marker cleanup in `all` mode can actually delete the file. - proofread skill: resolve the branch-diff base ref with an origin/master -> master fallback, and add untracked non-ignored files (git ls-files --others --exclude-standard) to the scan union so brand-new, unstaged prose is not silently skipped. - pre-pr: add a `doc-source (non-JVM)` classification and dispatch review-docs for TypeScript/JavaScript/Go doc-comment changes, so their English-usage issues no longer bypass the pre-PR gate. The aligned Markdown tables in english-style.md are kept as-is, per the maintainer's note that the layout is for human readers. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
The untracked-files fix made branch-diff mode's step-1 list include untracked, non-ignored files, but step 2 still read "scan git-tracked files only" — a contradiction Copilot flagged on re-review. Scope the tracked-only rule to the full-sweep and scoped-sweep modes; in branch-diff mode, keep the untracked new files the step-1 union already collected. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
armiol
approved these changes
Jul 18, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Context
Documentation prose across SpineEventEngine repositories carries recurring
English-language errors — an ad-hoc review of
core-jvmKDoc/Javadoc turned updozens (articles, subject–verb agreement, prepositions, "allows to",
punctuation), a pattern common in text written by Russian speakers. Only one
such rule was encoded anywhere (the
which-fixerwhich/that fixer); there wasno shared standard for a reviewer to enforce or an author to follow.
Because this repository floats to ~40 consumer repos through the shared-agents
submodule, encoding the standard here ships it organisation-wide on the next
config/pull.What this does
Establishes a single English-usage standard and wires it into a closed loop —
prevent, catch, remediate, learn.
The standard (Phase 1)
guidelines/english-style.md— an error catalog grouped by topic(articles, subject–verb agreement, verb form in API summaries, prepositions,
verb complementation, commas, hyphenated compound modifiers, confusables,
punctuation, spelling/dialect, and the restrictive which/that rule migrated
from
which-fixer), each topic with before/after examples and leave-aloneguards. Includes per-language "Never edit" protections for machine-read
comments (Go pragmas, TS/JS compiler and tool directives, Protobuf lint,
JSDoc machinery, godoc's leading-identifier convention, and more).
_TOC.md; linked fromdocumentation.md,kdoc.md,javadoc.md,and
protobuf.md.file's dominant dialect; report a genuinely split file and leave it. No
organisation-wide dialect conversion (that can be forced later as a separate
mechanical sweep).
The fixer (Phase 2)
skills/proofread/— a stateless fixer that applies the catalog toproject-owned prose across Kotlin, Java, Protobuf, TypeScript, JavaScript,
Go, Markdown, and AsciiDoc. Three caller-selected modes: a branch-diff
default, a full
allsweep (module by module), and a path-scoped sweep. Nomemory sentinel — the "swept already" fact lives in rollout tracking, not
repo state.
guidelines/project-owned-files.md— the submodule andconfig-distributed scoping (with the
buildSrc/src/main/kotlin/module.gradle.ktsexception and the
config/agentssource-repo exemption), extracted fromwhich-fixer's old step 2 and cross-referenced fromupdate-copyright.which-fixerretired — its skill and command are deleted; its which/thatrule now lives in the catalog.
proofread allremoves the legacy.agents/memory/which-fixer-applied.mdmarker during a repo's first fullsweep.
The reviewer (Phase 3)
skills/review-docs/gains check E. English usage, applied tochanged prose lines only, with a severity mapping: meaning-distorting error →
Must fix; clear grammar/punctuation/spelling error → Should fix;
debatable phrasing and catalog report-only cases → Nit. It reviews; it does
not rewrite (bulk fixing is
proofread's job).(type/field/enum/service, not only the file header) plus TypeScript,
JavaScript, and Go. A
## Checkspreamble marks prose checks (C/D/E)language-agnostic and structural checks (A/B) source-format-specific, and
Check A now cites
protobuf.mdfor message and field doc-comment structure.skills/pre-pr/dispatchesreview-docswhenever a changed hunk touchesdoc-comment or prose lines — any Markdown or Protobuf change (proto in
addition to triggering the build) and mixed code+comment JVM changes — not
only on a
docs-classified diff.review-docscommand/agent/Codex wrappers and thepre-prcommandwrapper are updated to match.
Authoring-time prevention (Phase 4)
writerlistsenglish-style.mdin its documentation-conventions, sonew prose is written to the catalog.
java-to-kotlingains a "fix genuine English errors while you are here"step: since a Javadoc→KDoc conversion rewrites the comment anyway, it's the
natural moment to correct outright errors and set the third-person KDoc
summary verb, while preserving the author's meaning and voice.
Expected behavior after merge
On the next
config/pull, consumer repos gain: theproofreadcommand forremediation sweeps;
review-docs/pre-prenforcement of the catalog ondoc-affecting PRs; and authoring skills that write to the standard.
Notes
review-docsagent before its commit(Phases 1 and 3 through two passes).
proofread allacross the ~40 repos andopening the reviewed PRs — is a separate follow-up, intentionally out of
scope here.
🤖 Generated with Claude Code