review-clarity-naming-comment-intent

What problem does it solve?

Unclear naming, inconsistent domain vocabulary, and low-quality code comments in behavior-changing pull requests create confusion for code consumers, increase maintenance overhead, and introduce contract mismatch risks that can lead to bugs or breaking changes post-merge.

Core Features & Use Cases

• Static PR Diff Analysis: Reviews code changes without running build or test commands, focusing exclusively on naming clarity, comment intent, and public surface minimization.
• Domain Vocabulary Consistency Checks: Flags instances where the same concept uses multiple names, or the same name has different meanings across code and interface surfaces.
• Comment Intent Validation: Identifies comments that only restate code mechanics, are stale, or contradict current behavior, and flags missing rationale for security-sensitive or non-obvious logic.
• Use Case: When merging a PR that adds new API endpoints, this skill catches ambiguous parameter names, endpoint paths that conflict with HTTP semantics, and missing side-effect documentation for public methods, preventing consumer confusion and integration issues.

Quick Start

Use this skill to review the diff for your current pull request for naming clarity, comment intent, and public surface minimization issues before merging.