skills.rest
pydantic
pydanticOFFICIAL
Explore all skills by this author →
Website𝕏@pydanticGitHub

review-verbosity

Rewrites verbose comments and docstrings added by a git branch into concise documentation.

8.1k|413|Updated May 28, 2023
Search Tags:#comments#docstrings#Rust#Refactoring#Documentation#Git diff#Code review
One-click install
npx skills add https://github.com/pydantic/monty --skill review-verbosity
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: review-verbosity
Source: https://github.com/pydantic/monty/tree/main/.agents/skills/review-verbosity
Command: npx skills add https://github.com/pydantic/monty --skill review-verbosity

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

New code branches often accumulate overly long comments and docstrings that restate the obvious, making codebases harder to read and maintain. This Skill edits those comments down to concise, meaningful documentation instead of merely reporting the problem.

Core Features & Use Cases

  • Comment Condensation: Rewrites comments and docstrings added by the current branch, keeping them short (typically 1-3 lines for comments, up to 5 for docstrings) while preserving motivation and caveats.
  • Tautology and Narration Removal: Deletes comments that restate what the code plainly says, narrate history, or hedge, and fixes comments the branch made inaccurate.
  • Parallel Review via Sub-agents: Diffs against origin/main and dispatches one sub-agent per changed crate or file group so large diffs are reviewed exhaustively.
  • Use Case: After finishing a feature branch in a Rust workspace, run this Skill to tighten every comment the branch touched, then verify with make format-rs && make lint-rs before merging.

Quick Start

Ask the AI to review and tighten the verbose comments and docstrings added by the current branch compared to origin/main.

Frequently Asked Questions about review-verbosity

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

FAQPage Schema
How do I clean up verbose comments in a pull request?▼

Diff the branch against origin/main to find every comment it added, then rewrite each one concisely, deleting tautologies and narration while keeping the motivation. This Skill automates that pass and edits the files directly rather than only reporting issues.

How to review large diffs for comment quality exhaustively?▼

Split the diff by changed crate or file group and dispatch one sub-agent per group, then review their edits yourself. A single pass over a large diff tends to miss files, especially outside the main source directories.

Does this Skill change code behavior when editing comments?▼

No, it only touches comments and docstrings the branch added or changed. If a comment is wrong because the underlying code is wrong, it flags the issue instead of rewording the comment to match incorrect code.

What comment style rules does it enforce for Python docstrings?▼

Python docstrings are treated as markdown, using single backticks rather than RST double-backticks. Examples are limited to public items, capped at 8 lines, and must actually run in tests rather than being marked ignore.

When should I not use automated comment condensing?▼

Avoid it when comments contain genuinely valuable detail such as design rationale or known foot-guns, since the goal is concision without losing real information. It also only covers what the current branch touched unless a wider sweep is explicitly requested.

Related Skills

Explore More Software Engineering Skills→
villetakanenvilletakanen
29

ship

Validate the working tree, verify spec alignment, and create an atomic micro-commit.

Community
Advanced
r3bl-orgr3bl-org
477

run-clippy

Run clippy, cargo fmt, and module checks on Rust workspaces.

Official
Intermediate
AnXueHuaAnXueHua

code-review-excellence

Review code changes and return prioritized, actionable comments with a verdict.

Community
Intermediate
NVIDIANVIDIA
17.7k

mcore-linting-and-formatting

Runs linting and formatting checks on Megatron-LM code using ruff, black, isort, pylint, and mypy.

Official
Basic