Skip to content

Add an English-usage standard and wire it into fixing, review, and authoring - #36

Merged
alexander-yevsyukov merged 7 commits into
masterfrom
doc-review-improvements
Jul 18, 2026
Merged

Add an English-usage standard and wire it into fixing, review, and authoring#36
alexander-yevsyukov merged 7 commits into
masterfrom
doc-review-improvements

Conversation

@alexander-yevsyukov

@alexander-yevsyukovalexander-yevsyukov commented Jul 17, 2026

Copy link
Copy Markdown
Contributor

Context

Documentation prose across SpineEventEngine repositories carries recurring
English-language errors — an ad-hoc review of core-jvm KDoc/Javadoc turned up
dozens (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-fixer which/that fixer); there was
no 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-alone
    guards. 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).
  • Indexed in _TOC.md; linked from documentation.md, kdoc.md, javadoc.md,
    and protobuf.md.
  • Dialect policy: per-file consistency — align a clear outlier to the
    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 to
    project-owned prose across Kotlin, Java, Protobuf, TypeScript, JavaScript,
    Go, Markdown, and AsciiDoc. Three caller-selected modes: a branch-diff
    default, a full all sweep (module by module), and a path-scoped sweep. No
    memory sentinel — the "swept already" fact lives in rollout tracking, not
    repo state.
  • guidelines/project-owned-files.md — the submodule and
    config-distributed scoping (with the buildSrc/src/main/kotlin/module.gradle.kts
    exception and the config/agents source-repo exemption), extracted from
    which-fixer's old step 2 and cross-referenced from update-copyright.
  • which-fixer retired — its skill and command are deleted; its which/that
    rule now lives in the catalog. proofread all removes the legacy
    .agents/memory/which-fixer-applied.md marker during a repo's first full
    sweep.

The reviewer (Phase 3)

  • skills/review-docs/ gains check E. English usage, applied to
    changed 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).
  • Scope widened from JVM sources + Markdown to full Protobuf doc comments
    (type/field/enum/service, not only the file header) plus TypeScript,
    JavaScript, and Go. A ## 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.
  • skills/pre-pr/ dispatches review-docs whenever a changed hunk touches
    doc-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.
  • The review-docs command/agent/Codex wrappers and the pre-pr command
    wrapper are updated to match.

Authoring-time prevention (Phase 4)

  • writer lists english-style.md in its documentation-conventions, so
    new prose is written to the catalog.
  • java-to-kotlin gains 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: the proofread command for
remediation sweeps; review-docs/pre-pr enforcement of the catalog on
doc-affecting PRs; and authoring skills that write to the standard.

Notes

  • Markdown/YAML only — no code, build, Protobuf, or dependency changes.
  • Each phase was reviewed with the review-docs agent before its commit
    (Phases 1 and 3 through two passes).
  • Rollout automation — running proofread all across the ~40 repos and
    opening the reviewed PRs — is a separate follow-up, intentionally out of
    scope here.

🤖 Generated with Claude Code

alexander-yevsyukovand others added 5 commits July 17, 2026 18:07
@alexander-yevsyukov@claude
Add the English-usage improvement plan
fd61cbd
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>
@alexander-yevsyukov@claude
Introduce the English-style guideline
ac097c4
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>
@alexander-yevsyukov@claude
Replace which-fixer with the proofread skill
407ff52
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>
@alexander-yevsyukov@claude
Enforce English usage in review-docs and pre-pr
77c5733
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>
@alexander-yevsyukov@claude
Point the authoring skills at the English-style catalog
0d442b2
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>
CopilotAI review requested due to automatic review settings July 17, 2026 19:39
CopilotAI reviewed Jul 17, 2026
View reviewed changes

CopilotAI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 proofread fixer skill (with Claude/OpenAI wrappers) and retired which-fixer.
  • Extended review-docs and pre-pr to 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
FileDescription
skills/writer/SKILL.mdAdds english-style.md to authoring-time documentation conventions.
skills/which-fixer/SKILL.mdRemoves the retired legacy fixer skill.
skills/which-fixer/agents/openai.yamlRemoves the retired legacy OpenAI wrapper.
skills/update-copyright/SKILL.mdCross-references the shared “project-owned files” scoping definition.
skills/review-docs/SKILL.mdBroadens scope to more comment types and adds English-usage Check E.
skills/review-docs/agents/openai.yamlUpdates OpenAI wrapper prompt/description to match the new scope.
skills/proofread/SKILL.mdAdds the new remediation skill implementing the English-usage catalog.
skills/proofread/agents/openai.yamlAdds the OpenAI wrapper for the proofread skill.
skills/pre-pr/SKILL.mdUpdates reviewer dispatch logic to run review-docs on doc/prose hunks.
skills/java-to-kotlin/SKILL.mdAllows fixing clear English errors during Javadoc→KDoc conversion.
guidelines/protobuf.mdLinks Protobuf doc-comment English rules to the new English style catalog.
guidelines/project-owned-files.mdAdds the shared definition for “project-owned” vs upstream-distributed files.
guidelines/kdoc.mdLinks KDoc guidance to the English style catalog.
guidelines/javadoc.mdLinks Javadoc guidance to the English style catalog.
guidelines/english-style.mdAdds the new English-usage error catalog and “Never edit” protections.
guidelines/documentation.mdCross-links to English style as the language-quality reference.
guidelines/_TOC.mdAdds TOC entries for English style and project-owned files.
docs/authoring-skills.mdUpdates examples to reference proofread instead of the retired which-fixer.
claude/commands/which-fixer.mdRemoves the retired Claude command wrapper.
claude/commands/review-docs.mdUpdates Claude command wrapper to the expanded review scope/checks.
claude/commands/proofread.mdAdds Claude command wrapper for proofread.
claude/commands/pre-pr.mdUpdates wrapper text to match the new review-docs dispatch criteria.
claude/agents/review-docs.mdUpdates Claude subagent wrapper to include English-usage checking.
.agents/tasks/english-usage-improvements.mdAdds task log/plan documenting the phased rollout work.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment threadguidelines/english-style.md
@alexander-yevsyukovalexander-yevsyukov moved this to In Review in v2.0Jul 17, 2026
chatgpt-codex-connector[bot]
chatgpt-codex-connectorBot reviewed Jul 17, 2026
View reviewed changes

@chatgpt-codex-connectorchatgpt-codex-connectorBot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 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".

Comment threadclaude/commands/proofread.md Outdated
Comment threadclaude/commands/proofread.md Outdated
Comment threadskills/proofread/SKILL.md Outdated
Comment threadskills/proofread/SKILL.md Outdated
Comment threadskills/pre-pr/SKILL.md Outdated
@alexander-yevsyukov@claude
Address PR#36review comments on proofread and pre-pr
c81970f
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>
CopilotAI review requested due to automatic review settings July 17, 2026 19:59
CopilotAI reviewed Jul 17, 2026
View reviewed changes

CopilotAI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 24 out of 24 changed files in this pull request and generated 1 comment.

Comment threadskills/proofread/SKILL.md Outdated
@alexander-yevsyukov@claude
Resolve tracked-only contradiction in proofread step 2
a5bb063
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>
CopilotAI review requested due to automatic review settings July 17, 2026 20:28
CopilotAI reviewed Jul 17, 2026
View reviewed changes

CopilotAI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 24 out of 24 changed files in this pull request and generated no new comments.

@alexander-yevsyukov
alexander-yevsyukov merged commit 2369ab8 into masterJul 18, 2026
1 check passed
@alexander-yevsyukov
alexander-yevsyukov deleted the doc-review-improvements branch July 18, 2026 15:40
@github-project-automationgithub-project-automationBot moved this from In Review to ✅ Done in v2.0Jul 18, 2026
Sign up for freeto join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code reviewCopilot
Copilot review effort
Applies to this pull request for everyone.Learn more about Copilot code review.
Copilot left review comments
@chatgpt-codex-connectorchatgpt-codex-connector[bot]chatgpt-codex-connector[bot] left review comments
@armiolarmiolarmiol approved these changes

Assignees

@alexander-yevsyukovalexander-yevsyukov

Labels

None yet

Projects

v2.0
Archived in project

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@alexander-yevsyukov@armiol