skills.rest
D3Hunter
D3HunterCOMMUNITY
Explore all skills by this author →
GitHub

review-clarity-naming-comment-intent

Identify clarity, naming, and comment intent defects in pull request diffs.

Updated Mar 3, 2026
Search Tags:#static analysis#code review#pull request#domain vocabulary#naming clarity#comment intent#contract consistency
One-click install
npx skills add https://github.com/D3Hunter/ai-engineer --skill review-clarity-naming-comment-intent
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: review-clarity-naming-comment-intent
Source: https://github.com/D3Hunter/ai-engineer/tree/main/skills/review-clarity-naming-comment-intent
Command: npx skills add https://github.com/D3Hunter/ai-engineer --skill review-clarity-naming-comment-intent

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

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.

Frequently Asked Questions about review-clarity-naming-comment-intent

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

FAQPage Schema
How do I check pull request diffs for naming clarity and comment intent before merging?▼

To check pull request diffs for naming clarity and comment intent, statically analyze behavior-changing changes focusing on public interfaces, exported symbols, and endpoint paths to prevent consumer confusion and contract mismatches.

Why do unclear parameter names and stale comments in API endpoints cause contract mismatches post-merge?▼

Unclear parameter names and stale comments cause contract mismatches because they fail to reflect side effects and domain semantics, leading to integration issues and consumer confusion when behavior-changing diffs are merged without pre-merge guardrails.

What's the best way to enforce domain vocabulary consistency across code and public interface surfaces?▼

The best way to enforce domain vocabulary consistency is to run static PR diff analysis that flags instances where the same concept uses multiple names or the same name has different meanings across code and interface surfaces.

Can I review code comments to ensure they capture intent rather than restate mechanics?▼

You can review code comments by validating comment intent to identify those that only restate mechanics, are stale, or contradict current behavior, and flag missing rationale for security-sensitive or non-obvious logic.

Does static analysis of PR diffs require running build or test commands?▼

Static analysis of PR diffs does not require running build or test commands, as it reviews code changes exclusively by focusing on naming clarity, comment intent, and public surface minimization across the codebase.

When should I minimize public surfaces in behavior-changing pull requests?▼

You should minimize public surfaces in behavior-changing pull requests when adding new API endpoints or exported symbols to prevent post-merge consumer confusion and reduce contract mismatch risks by enforcing pre-merge guardrails.

Related Skills

Explore More Software Engineering Skills→
nokusukunnokusukun

refactor

Restructure working code by extracting, inlining, collapsing, or splitting, preserving public interfaces and tests.

Community
Intermediate
xashggxashgg
1

deep-audit

Audit Codex academic workflow repository files for outdated references and errors.

Community
Advanced
shogoggshogogg
4

coderabbit-review

Automate CodeRabbit code reviews for uncommitted and committed Git changes.

Community
Advanced
act70255act70255

api-testing-observability-api-mock

Design realistic API mocks for contract validation and integration testing.

Community
Advanced