Diagnose Readability Debt

Retrieval Prompts

1. What are the three fastest ways code becomes expensive to read?
2. When should a comment survive instead of being replaced by cleaner code?
3. What does formatting communicate besides style preference?
4. Why is naming a design tool instead of just a label?

Compare and Distinguish

Explain the difference between each pair in one or two sentences:

• short name vs precise name
• useful comment vs redundant comment
• formatting for linter compliance vs formatting for narrative clarity
• readable code vs merely familiar code

Common Mistake Check

If your review notes say only "rename things" without naming the specific ambiguity, the diagnosis is too weak.

If you keep comments that simply repeat the next line, you are preserving noise.

If the file has no visual separation between phases of work, readability debt is probably higher than it first appears.

Mini Application

Choose one file and annotate it with these labels:

• naming ambiguity
• comment noise
• formatting friction
• hidden domain rule

You must record at least one example of each label or explicitly say that the file has none.

Evidence Check

You are done only when:

• you identified issues with examples, not vibes
• at least one issue was removed, not just noted
• you can explain why your rewrite lowered reading cost