Skip to content

DOCS-988 - "Humanize" GitHub/Jira comments - #7101

Merged
kimsauce merged 9 commits into
mainfrom
DOCS-988
Sep 10, 2026
Merged

kimsauce merged 9 commits into
mainfrom
DOCS-988

Conversation

@kimsauce

@kimsauce kimsauce commented Sep 3, 2026

Copy link
Copy Markdown
Collaborator

Purpose of this pull request

A comment Claude Code posts should read as though a person wrote it. This makes that a requirement for GitHub PR comments, GitHub issue comments, and Jira ticket comments.

  • .claude/skills/humanizer/SKILL.md vendors blader/humanizer v3.0.0 (MIT), copied verbatim so version bumps stay a clean overwrite. It rewrites the patterns that mark prose as machine-written, working from 25 numbered tells drawn from Wikipedia's "Signs of AI writing", and leaves code, commands, paths, and link targets untouched.
  • AGENTS.md gains an Output tone section requiring the skill on the draft of every comment, in its embedded mode so only the final text comes back. It also states three rules that hold whether or not the skill runs: no em dashes, be concise, plain language. On a PR, one more rule applies: put each point in an inline comment on the line it concerns, and keep a top-level summary comment only for feedback not tied to a specific line.

The rules sit alongside the skill rather than inside it because a skill invocation is model-initiated, and so probabilistic. If the skill does not fire, the rules still apply.

Pairs with DOCS-1867 (#7099), which removes the attribution marker Claude appends to comments. Between them: the marker that labels a comment as automated, and the style that betrays it anyway.

Select the type of change

  • Minor Changes - Typos, formatting, slight revisions
  • Update Content - Revisions, updating sections
  • New Content - New features, sections, pages, tutorials
  • Site and Tools - .clabot, version updates, maintenance, dependencies, new packages for the site (Docusaurus, Gatsby, React, etc.)

Ticket (if applicable)

https://sumologic.atlassian.net/browse/DOCS-988

🤖 Generated with Claude Code

Add a "no em dashes, be concise, plain language" standard that applies to published documentation and to comments Claude posts to people (GitHub, Jira, Asana, Slack). Repo infrastructure stays out of scope.

- docs/contributing/style-guide.md: new "Concise, human phrasing" and "Dashes" subsections.
- .claude/skills/sumo-style/SKILL.md: mirror the concision rule.
- AGENTS.md: new "Output tone" section so the rules reach connector comments, where the sumo-style skill does not load.

Covers DOCS-988 action item 2 (team guidelines). Action item 1 (humanizer vs sumo-style evaluation) captured in a ticket comment.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
@kimsauce kimsauce self-assigned this Sep 3, 2026
@cla-bot cla-bot Bot added the cla-signed Contributor approved, listed in .clabot file label Sep 3, 2026
@kimsauce kimsauce changed the title DOCS-988 - Add plain-tone rules for docs and human-facing comments DOCS-988 - Add plain-tone rules for comments Sep 9, 2026
Scope the tone rules to the prose Claude posts for people to read in
GitHub PR comments, GitHub issue comments, and Jira ticket comments. A
comment should read as though a person wrote it.

Removes the additions to docs/contributing/style-guide.md and to the
sumo-style skill. Both applied the rules to published documentation,
which reaches past the intended scope.

Drops the em dash exception for a tooling-appended attribution marker,
since no marker is appended to a comment now, and drops Asana and Slack
from the surface list.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
kimsauce and others added 4 commits September 8, 2026 23:48
Vendors blader/humanizer v3.0.0 (MIT) at .claude/skills/humanizer/SKILL.md,
copied verbatim so future version bumps are a clean overwrite. It rewrites
the patterns that mark prose as machine-written, working from 25 numbered
tells drawn from Wikipedia's "Signs of AI writing", and leaves code, paths,
and link targets untouched.

AGENTS.md now requires running it on the draft of every GitHub PR comment,
GitHub issue comment, and Jira ticket comment, in the skill's embedded mode
so only the final text comes back. Stated as a standing requirement rather
than a step someone has to ask for.

The three tone rules stay, since a skill invocation is model-initiated and
therefore probabilistic. They hold whether or not the skill runs.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
…skill

SKILL.md was copied in with only "license: MIT" in its frontmatter: no
copyright line, no permission notice, and no pointer upstream. This repo is
public and MIT licensed in its own right, so redistributing a third-party
MIT file without its notice does not meet the license terms, and nothing in
the directory told a maintainer the file was third-party at all.

Adds a README recording the upstream URL, version 3.0.0, the commit it was
copied from, and the file's sha256, plus the upstream copyright and
permission notice verbatim. Also states the update rule: overwrite from
upstream, never edit locally, so an update stays a clean overwrite.

Copyright (c) 2025 Siqi Chen, per https://github.com/blader/humanizer.

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
@kimsauce kimsauce changed the title DOCS-988 - Add plain-tone rules for comments DOCS-988 - Plain-tone rules for GitHub/Jira comments Sep 9, 2026
@kimsauce
kimsauce marked this pull request as ready for review September 9, 2026 08:56
@kimsauce kimsauce changed the title DOCS-988 - Plain-tone rules for GitHub/Jira comments DOCS-988 - "Humanize" GitHub/Jira comments Sep 9, 2026

@amee-sumo amee-sumo left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Reviewed the vendored skill and the AGENTS.md changes:

  • SKILL.md is byte-identical to the documented upstream checksum.
  • The "Output tone" section is well-scoped to comments, and the em-dash rule is consistent with the existing sumo-style doc-prose convention rather than a new invention.
  • The skill's process explicitly requires keeping every supported claim and never inventing sources, so this is a style pass, not a content-fabrication risk.
  • Enforcement is instruction-only for now (no hook), which the ticket's own implementation notes already call out as a known follow-up once #7099's hook lands on main.

Non-blocking note: paired with #7099 (which drops the "via Claude Code" marker), this means a GitHub/Jira comment posted under a contributor's own account will carry neither an attribution marker nor a stylistic tell. That may be exactly the outcome intended from the 9/2 Tech Docs discussion, but it's worth the team double-checking that the "no way to tell AI-drafted from human-drafted after the fact" consequence was the explicit intent, not just a side effect of "make comments sound less robotic."

Approving.

@kimsauce
kimsauce added this pull request to the merge queue Sep 10, 2026
Merged via the queue into main with commit a68bba1 Sep 10, 2026
3 of 4 checks passed
@kimsauce
kimsauce deleted the DOCS-988 branch September 10, 2026 08:11
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

cla-signed Contributor approved, listed in .clabot file

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants