Skip to content

content-inconsistent-terminology

Detect inconsistent terminology across instruction files (e.g., mixing 'directory' and 'folder')
Severity info (auto)
Autofix -
Since v0.7.0
Category Content Intelligence

Why

When instruction files use "directory" in one place and "folder" in another, the model may treat them as different concepts or waste tokens reconciling them. Consistent terminology reduces ambiguity and helps the model pattern-match instructions to the right context.

Examples

Bad (across files):

<!-- CLAUDE.md -->
Create a new directory under `src/`.

<!-- .claude/rules/testing.md -->
Put test fixtures in the `tests/` folder.

Good:

<!-- Both files -->
Create a new directory under `src/`.
Put test fixtures in the `tests/` directory.

How to fix

Pick the most common term across your instruction files and use it everywhere. Prefer technical terms over informal ones (e.g., "directory" over "folder", "repository" over "codebase"). A coding agent can standardize terminology automatically.

Only running prose counts as a terminology choice. Headings (e.g. a skill titled # Create Pull Request that says "PR" everywhere in its body) and inline code spans (e.g. a path like `.planning/codebase/foo.md`) are excluded, since they're a different register than the prose choice this rule is checking.

If a group doesn't apply to your repository — for example, a polyglot repo that legitimately documents both Go functions and Java methods — disable just that group (or override its severity) while keeping the rest enforced:

rules:
  content-inconsistent-terminology:
    severity: error
    groups:
      function/method: off      # disable this group only
      PR/pull request/merge request: warning  # downgrade this group

Valid group names: directory/folder, repo/repository/codebase, PR/pull request/merge request, function/method. Valid values: off (or false) to disable, or a severity (error, warning, info).

Configuration

rules:
  content-inconsistent-terminology:
    enabled: auto  # true | false | auto
    severity: info
Parameter Description Default
groups Per-group overrides keyed by group name (e.g. 'function/method'): 'off' or false disables the group; a severity ('error', 'warning', 'info') overrides the rule severity for that group {}

Research Basis

Detects inconsistent terminology across instruction files (e.g., one file says "directory" while another says "folder").

If one file says "run npm test" and another says "execute yarn test", the model must resolve the ambiguity at inference time. The "Curse of Instructions" paper shows that instruction conflicts compound multiplicatively — inconsistent terminology creates implicit contradictions that degrade compliance.

Consistent terminology is a well-established principle in technical writing. For LLMs, it's even more important: the model lacks the human ability to infer that two different terms refer to the same concept from broader context.

References:

Run skillsaw explain content-inconsistent-terminology to see this documentation and the rule's effective configuration in your terminal.