doc-clarity-opportunity

disable-model-invocation	true
name	doc-clarity-opportunity
description	Looks for opportunities to improve documentation and code clarity — JSDoc, inline comments, and README updates. Use when the user wants to find documentation gaps or improve code clarity.

Doc Clarity Opportunity Skill

1. Identify Target Scope

Determine which files or changes to analyze (e.g., current workspace changes, specific files, or a git diff). If the scope is ambiguous, ask the user for clarification.

2. Review for Clarity Opportunities

Analyze the target scope directly. Look for three types of improvements:

• JSDoc / type comments: exported functions, classes, or types with non-obvious signatures that lack documentation
• Inline comments: complex logic, non-obvious invariants, workarounds, or hidden constraints with no explanation
• README / docs: stale information, missing setup steps, undocumented behaviours visible in the code

High bar: only flag improvements that add net-new context — rationale, invariants, workarounds, or side effects a reader wouldn't derive from reading the code. Discard suggestions for obvious or self-documenting code.

3. Present Suggestions & Await Approval

Present the filtered list of high-value documentation improvements to the user. Do NOT apply any changes directly — await explicit approval before proceeding.