# Clarity Linter

> Evaluate and improve code clarity and cognitive load with rubric-driven scoring and targeted fixes.

- Skill: `majiayu000/clarity-linter` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds add majiayu000/clarity-linter`
- Raw SKILL.md: https://api.skillmd.com/api/skills/majiayu000/clarity-linter/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: majiayu000 (https://skillmd.com/u/majiayu000)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/majiayu000/clarity-linter

---



### L1 Improvement
- Rewrote the clarity linter as an English-first SOP with Prompt Architect-style constraint surfacing.
- Added structure-first guardrails, adversarial validation hooks, and confidence ceilings per Skill Forge.
- Consolidated input/output contracts into a single execution path for faster dogfooding.

## STANDARD OPERATING PROCEDURE

### Purpose
Assess readability and cognitive load, then deliver fixes with rubric-backed evidence.

### Trigger Conditions
- **Positive:** "clarity audit", "reduce cognitive load", "naming/readability review", "thin helper detection".
- **Negative:** coupling-only analysis (use connascence-analyzer), security/performance scans, or quick lint (use quick-quality-check).

### Guardrails
- Structure-first package: `SKILL.md`, `README.md`, `examples/`, `tests/`, `references/` kept current.
- Use explicit clarity rubric (size, indirection, call depth, duplication, explanation quality) and cite evidence.
- Apply confidence ceilings; do not overclaim automated fixes without human review when confidence <0.80.
- Store runs in memory with WHO/WHY/WHEN/PROJECT tags for traceability.

### Execution Phases
1. **Intent & Scope** – Confirm language, repo area, and goal (audit vs fix). Load domain expertise if available.
2. **Metrics Collection** – Gather size, nesting, call depth, duplication, naming signals, and comment density.
3. **Rubric Evaluation** – Score five dimensions; classify verdict (ACCEPT ≥0.80, REFINE 0.60–0.79, REJECT <0.60).
4. **Fix Planning** – Rank violations by impact; propose minimal-change patches.
5. **Fix Generation** – Apply or draft patches; keep diffs small and reversible.
6. **Validation** – Rerun metrics; ensure clarity score improves and tests still pass.
7. **Delivery** – Summarize findings, decisions, diffs, and confidence ceiling.

### Input Contract (minimum)
- `target`: file|directory with path.
- `policy`: strict|standard|lenient (defaults to standard thresholds).
- Flags: `auto_fix` (default false), `report_format` (md|json), `min_score_threshold` (default 0.60).

### Output Format
- Metrics snapshot, rubric scores, verdict, and top violations with evidence.
- Fix plan and applied/queued patches.
- Risks, follow-ups, and memory keys used.
- Confidence: X.XX (ceiling: TYPE Y.YY).

### Validation Checklist
- [ ] Trigger confirmed; correct domain expertise loaded.
- [ ] Rubric applied; evidence attached for each violation.
- [ ] If auto-fix enabled, regressions and tests rerun.
- [ ] Memory tagged and report stored.
- [ ] Confidence ceiling declared.

### Integration
- **Memory MCP:** `skills/tooling/clarity-linter/{project}/{timestamp}` for reports and diffs.
- **Hooks:** keep evaluation under `post_hook_max_ms:1000`; fail fast if metrics worsen.

Confidence: 0.70 (ceiling: inference 0.70) – SOP aligned to Prompt Architect constraint extraction and Skill Forge structure-first delivery.