naming-obviousness

Audit code names for vagueness, inconsistency, and non-obvious behavior.

11|Updated Feb 25, 2026
One-click install
npx skills add https://github.com/codybrom/clairvoyance --skill naming-obviousness
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: naming-obviousness
Source: https://github.com/codybrom/clairvoyance/tree/main/skills/naming-obviousness
Command: npx skills add https://github.com/codybrom/clairvoyance --skill naming-obviousness

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

This skill helps identify vague, misleading, inconsistent, or overly context-dependent names and exposes code whose behavior is difficult for a first-time reader to understand.

Core Features & Use Cases

  • Isolation Test: Evaluates whether names communicate an entity's meaning without surrounding context.
  • Scope-Length Review: Checks that name precision increases appropriately with scope and distance from use sites.
  • Consistency and Obviousness Audit: Detects semantic splits, hard-to-name abstractions, and violated reader expectations in interfaces and implementations.
  • Use Case: Apply it during a code review when variables such as data, process, or result obscure their roles, or when a method requires reading distant implementation details to understand its behavior.

Quick Start

Use the naming-obviousness skill to review the specified file or module for precise names, consistent terminology, and non-obvious behavior.

Frequently Asked Questions about naming-obviousness

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I check code readability and find vague variable names during a code review?

Check code readability by applying isolation tests to see if names communicate meaning without context, and audit scope-length to ensure name precision matches distance from use sites. This exposes vague variables like data or result that obscure their roles.

What is an isolation test for software design and when do I need it?

An isolation test evaluates whether a name communicates an entity's meaning without surrounding context. You need it during code reviews when variables obscure their roles or when methods require reading distant implementation details to understand behavior.

How do I audit naming consistency and non-obvious behavior in a module?

Audit naming consistency by detecting semantic splits, hard-to-name abstractions, and violated reader expectations across interfaces and implementations. This exposes non-obvious behavior and helps recommend precise renames that reduce required context.

Can I review method and interface names to reduce required context for first-time readers?

Yes, you can review method and interface names by applying reader-expectation checks and consistency audits. This identifies misleading or inconsistent names and recommends design improvements that make behavior understandable on first read.

What is the best way to fix misleading function names that violate reader expectations?

Fix misleading function names by applying consistency audits and reader-expectation checks to detect semantic splits, then recommend precise renames and design improvements that make behavior obvious without reading distant implementation details.

Why does my code require distant implementation details to understand method behavior?

Method behavior requires distant implementation details when names are vague, misleading, or overly context-dependent. Applying scope-length analysis and isolation tests identifies these non-obvious names and recommends precise renames to fix it.