use-context-reviewer-readability
Thresholds are based on cognitive limits such as working memory and one-screen focus, and established metrics such as McCabe complexity. The table below carries the recommended values; the detection table lists the deviations worth reporting rather than every crossing of them. Arguments are recommended at 3 and detected above 5.
| Target | Recommended | Why |
|---|---|---|
| Function lines | ≤30 | One-screen readability |
| File lines | ≤400 | Module-level cognitive ceiling |
| Nesting depth | ≤3 | Branch tracking within working memory |
| Function arguments | ≤3 | Argument order memorization limit |
| Cyclomatic complexity | ≤10 | McCabe 1976: testable without path explosion |
Detection
| ID | Pattern | Fix |
|---|---|---|
| RD1 | Vague processData() |
validateUserEmail() |
| RD1 | Misleading identifiers | Names reveal intent |
| RD2 | Nesting > 3 levels | Guard clauses, extract functions |
| RD2 | Function > 30 lines | Decompose |
| RD3 | Comment: // increment i |
Delete; self-evident |
| RD3 | Comment: // TODO: fix later |
Create issue or fix now |
| RD4 | Interface for single impl | Remove until 2nd impl |
| RD4 | Class for stateless logic | Pure function |
| RD5 | > 5 function parameters | Config object or decompose |
References
| Topic | File |
|---|---|
| Control Flow | ${CLAUDE_SKILL_DIR}/references/control-flow.md |
| Comments | ${CLAUDE_SKILL_DIR}/references/comments-clarity.md |
| AI Antipatterns | ${CLAUDE_SKILL_DIR}/references/ai-antipatterns.md |
| Naming | ${CLAUDE_SKILL_DIR}/references/naming.md |