Skip to content

docs: normalize the Claude Code user reference to "user"#104

Open
taminomara wants to merge 1 commit into
testdouble:mainfrom
taminomara:chore/normalize-user-terminology
Open

docs: normalize the Claude Code user reference to "user"#104
taminomara wants to merge 1 commit into
testdouble:mainfrom
taminomara:chore/normalize-user-terminology

Conversation

@taminomara

Copy link
Copy Markdown
Contributor

What & why

Han referred to the person running a skill inconsistently — mostly "the user", but a minority of skills, shared reference files, one agent definition, and docs used "the operator". Several places mixed both terms for the same referent in a single sentence (e.g. issue-triage, code-review's $focus_areas, the research-analyst report registry). This normalizes the interactive person — and user-supplied material — to "user".

Scope

Normalized to "user" / "user-supplied/-provided/context":

  • Shared reference files: evidence-rule.md (×3), readability-rule.md (×4), and their doc mirror docs/evidence.md
  • research skill + report template, and the research-analyst agent definition (it stamped provided (operator-supplied…) into every research report's Sources registry)
  • Interactive references in issue-triage, work-items-to-linear, and code-review's $focus_areas

Normalized to "reader" (that skill's established audience term, not "user"):

  • code-overview SKILL + overview template — the term denoted the audience of the produced overview, a role that skill already calls "reader"

Deliberately preserved (a genuinely different referent):

  • Production/ops operators in code-review severity examples and the kill-switch template
  • The runbook incident-follower, Kubernetes / External Secrets Operators, the OpenShift {operator} path variable
  • The plugin-builder author-vantage "operator" (a plugin's end-operator)
  • The established "operator-facing documentation" framing across the docs corpus

Verification

Two review agents ran against the diff:

  • content-auditor → clean: no facts lost or altered, referents correct, doc mirrors faithful to their canonical sources
  • information-architect → flagged the research-analyst agent definition and the docs/evidence.md TL;DR as remaining misses (one referent, two terms); both fixed in this branch. A final case-insensitive sweep confirms every remaining "operator" is a deliberately-preserved sense.

20 files, 43 insertions, 43 deletions.

🤖 Generated with Claude Code

https://claude.ai/code/session_01QiYf8oTKFYcDhpsFEAaduk

The suite referred to the person running a skill inconsistently — mostly
"the user", but a minority of skills, shared reference files, one agent
definition, and docs said "the operator", sometimes mixing both terms for
the same referent in one sentence. Standardize on "user" for the
interactive person and for user-supplied material.

- Trust-class vocabulary in the shared evidence-rule (x3) and
  readability-rule (x4) reference files and their doc mirror
  (docs/evidence.md): "operator-supplied/-provided/context" -> "user-*".
- research skill + report template and the research-analyst agent
  definition (which stamped the trust-class token into every report's
  Sources registry): material vocabulary -> "user".
- Interactive references in issue-triage, work-items-to-linear, and
  code-review's $focus_areas.
- code-overview denoted the audience of the produced overview, so it
  becomes that skill's established "reader", not "user".

Preserve "operator" where it names a different referent: production/ops
operators in code-review severity examples and the kill-switch template,
the runbook incident-follower, Kubernetes / External Secrets Operators,
the OpenShift {operator} path variable, the plugin-builder author-vantage
"operator", and the established "operator-facing documentation" framing.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01QiYf8oTKFYcDhpsFEAaduk
@taminomara taminomara marked this pull request as ready for review July 3, 2026 22:00
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant