What problem does it solve? Code that passes correctness review can still be hard to read: comments that restate code, misleading names, branch fanout, stale references, and iteration-history scars accumulate during PR iteration and slow down every future reader. This Skill applies a dedicated readability lens so those issues are caught before merge. ## Core Features & Use Cases - Eleven explicit heuristics: Tests for one-sentence purpose, comment deletion, branch fanout, name genericization, reader onramp, reference staleness, iteration-history scars, comment-to-code distance, duplication (including cross-file decision duplication), tests as documentation, and comment density. - Structured findings output: Returns JSONL findings with severity (P1/P2/P3), confidence, category, and the heuristic number that flagged each issue, following shared review conventions. - Comment rewrite delegation: Hands non-trivial comment rewrites to a dedicated comment-writer agent with bake-off evaluation, avoiding over-trimming of load-bearing detail. - Use Case: After a heavily iterated PR is confirmed correct, run this lens as the final pre-merge pass to flag a 6-branch if/else chain that should be a classifier table and a 50-line inline rationale that should become a function doc. ## Quick Start Ask the AI to run a legibility review on the current branch's diff, applying the eleven heuristics and reporting findings with severity and proposed cleanups.
