clarity-linter
Evaluate and improve code clarity and cognitive load with rubric-driven scoring and targeted fixes.
When & Why to Use This Skill
The clarity-linter is a specialized Claude skill designed to automate code quality audits with a focus on readability and cognitive load optimization. It utilizes a three-phase workflow—Metrics Collection, Rubric Evaluation, and Fix Generation—to provide objective, weighted scoring across dimensions like function size, call depth, and naming semantics, ensuring codebases remain maintainable and easy to understand.
Use Cases
- Automated Code Quality Audits: Systematically evaluate large codebases for readability issues and cognitive overhead that standard linters might miss.
- Refactoring Legacy Code: Identify and fix 'thin helpers', excessive indirection, and deep call chains to simplify complex logic and improve developer onboarding.
- Standardizing Naming and Documentation: Analyze naming patterns and comment density to ensure consistent coding standards and meaningful explanations across the team.
- Pre-merge Quality Gates: Integrate into the CI/CD pipeline to provide ACCEPT/REJECT verdicts based on clarity scores, preventing technical debt from entering the main branch.
/============================================================================/ /* CLARITY-LINTER SKILL :: VERILINGUA x VERIX EDITION / /============================================================================*/
name: clarity-linter version: 2.1.0 description: | [assert|neutral] Machine-readable code clarity auditing with cognitive load optimization. 3-phase SOP - Metrics Collection (code-analyzer) -> Rubric Evaluation (reviewer) -> Fix Generation (coder + analyst). Detects t [ground:given] [conf:0.95] [state:confirmed] category: quality tags:
- general author: system cognitive_frame: primary: evidential goal_analysis: first_order: "Execute clarity-linter workflow" second_order: "Ensure quality and consistency" third_order: "Enable systematic quality processes"
/----------------------------------------------------------------------------/ /* S0 META-IDENTITY / /----------------------------------------------------------------------------*/
[define|neutral] SKILL := { name: "clarity-linter", category: "quality", version: "2.1.0", layer: L1 } [ground:given] [conf:1.0] [state:confirmed]
/----------------------------------------------------------------------------/ /* S1 COGNITIVE FRAME / /----------------------------------------------------------------------------*/
[define|neutral] COGNITIVE_FRAME := { frame: "Evidential", source: "Turkish", force: "How do you know?" } [ground:cognitive-science] [conf:0.92] [state:confirmed]
Kanitsal Cerceve (Evidential Frame Activation)
Kaynak dogrulama modu etkin.
/----------------------------------------------------------------------------/ /* S2 TRIGGER CONDITIONS / /----------------------------------------------------------------------------*/
[define|neutral] TRIGGER_POSITIVE := { keywords: ["clarity-linter", "quality", "workflow"], context: "user needs clarity-linter capability" } [ground:given] [conf:1.0] [state:confirmed]
/----------------------------------------------------------------------------/ /* S3 CORE CONTENT / /----------------------------------------------------------------------------*/
Clarity Linter
Kanitsal Cerceve (Evidential Frame Activation)
Kaynak dogrulama modu etkin.
Phase 0: Expertise Loading
Before linting for clarity:
- Detect Domain: Identify codebase language and patterns
- Check Expertise: Look for
.claude/expertise/clarity-${lang}.yaml - Load Context: If exists, load clarity thresholds and naming conventions
- Apply Configuration: Use expertise for context-aware linting
Purpose: Evaluate code clarity and cognitive load using machine-readable rubric with weighted scoring
Timeline: 35-105 seconds (Metrics 10-30s + Evaluation 5-15s + Fixes 20-60s)
Integration: Runs alongside connascence-analyzer in dogfooding quality detection cycles
System Architecture
[Code Implementation]
↓
[Metrics Collection] (code-analyzer)
↓ (func_lines, nesting_depth, call_count, name_semantic_score, etc.)
↓
[Rubric Evaluation] (reviewer)
↓ (5 dimensions: indirection, size, call depth, duplication, comments)
↓
[Scoring & Verdict] (ACCEPT ≥0.8 | REFINE 0.6-0.79 | REJECT <0.6)
↓
[Fix Generation] (coder + analyst)
↓ (Auto-fix PRs + Human-readable reports)
↓
[Memory-MCP Storage] (with WHO/WHEN/PROJECT/WHY tags)
When to Use This Skill
Activate this skill when:
- Code quality audit focused on readability and cognitive load (not just coupling)
- Detecting thin helpers that add useless indirection
- Analyzing call chain depth and excessive layering
- Evaluating function size and cohesion
- Identifying poor naming patterns that hide complexity
- Checking comment density (over-commented vs under-explained)
- Complementing connascence analysis with clarity-specific patterns
DO NOT use this skill for:
- Pure coupling analysis (use connascence-analyzer)
- Security vulnerabilities (use security-testing-agent)
- Performance bottlenecks (use performance-testing-agent)
- Quick lint checks (use quick-quality-check)
Input Contract
input:
target:
type: enum[file, directory, workspace]
path: string (required)
# Absolute path to analyze
rubric_config:
rubric_path: string (default: .claude/skills/clarity-linter/.artifacts/clarity_rubric.json)
policy: enum[strict, standard, lenient] (default: standard)
# Affects threshold values in rubric
metrics:
collect_call_graph: boolean (default: true)
analyze_naming: boolean (default: true)
detect_duplication: boolean (default: true)
options:
auto_fix: boolean (default: false)
# Generate auto-fix PRs for high-confidence violations
report_format: enum[json, markdown, html] (default: markdown)
min_score_threshold: number (default: 0.6, range: 0-1)
Output Contract
output:
metrics:
functions_analyzed: number
files_analyzed: number
total_metrics_collected: number
collection_time_ms: number
evaluation:
overall_score: number (0-1)
verdict: enum[ACCEPT, REFINE, REJECT]
dimension_scores:
thin_helpers_indirection: number (0-1)
function_size_cohesion: number (0-1)
indirection_call_depth: number (0-1)
duplication_vs_dry: number (0-1)
comments_explanation: number (0-1)
violations:
total_count: number
by_severity:
critical: number
warning: number
info: number
by_check_id: object
THIN_HELPER_SIZE: number
PASS_THROUGH_WRAPPER: number
SOFT_TOO_LONG_FUNCTION: number
# ... (18 total checks from rubric)
fixes:
auto_fix_prs: array[object] (if auto_fix enabled)
file: string
violation_id: string
diff: string
suggested_fixes: array[object]
file: string
line: number
check_id: string
message: string
suggested_fix: string
reports:
markdown_report: path
json_detailed: path
memory_namespace: string
SOP Phase 1: Metrics Collection (10-30 sec)
Objective: Collect code metrics for clarity rubric evaluation
/----------------------------------------------------------------------------/ /* S4 SUCCESS CRITERIA / /----------------------------------------------------------------------------*/
[define|neutral] SUCCESS_CRITERIA := { primary: "Skill execution completes successfully", quality: "Output meets quality thresholds", verification: "Results validated against requirements" } [ground:given] [conf:1.0] [state:confirmed]
/----------------------------------------------------------------------------/ /* S5 MCP INTEGRATION / /----------------------------------------------------------------------------*/
[define|neutral] MCP_INTEGRATION := { memory_mcp: "Store execution results and patterns", tools: ["mcp__memory-mcp__memory_store", "mcp__memory-mcp__vector_search"] } [ground:witnessed:mcp-config] [conf:0.95] [state:confirmed]
/----------------------------------------------------------------------------/ /* S6 MEMORY NAMESPACE / /----------------------------------------------------------------------------*/
[define|neutral] MEMORY_NAMESPACE := { pattern: "skills/quality/clarity-linter/{project}/{timestamp}", store: ["executions", "decisions", "patterns"], retrieve: ["similar_tasks", "proven_patterns"] } [ground:system-policy] [conf:1.0] [state:confirmed]
[define|neutral] MEMORY_TAGGING := { WHO: "clarity-linter-{session_id}", WHEN: "ISO8601_timestamp", PROJECT: "{project_name}", WHY: "skill-execution" } [ground:system-policy] [conf:1.0] [state:confirmed]
/----------------------------------------------------------------------------/ /* S7 SKILL COMPLETION VERIFICATION / /----------------------------------------------------------------------------*/
[direct|emphatic] COMPLETION_CHECKLIST := { agent_spawning: "Spawn agents via Task()", registry_validation: "Use registry agents only", todowrite_called: "Track progress with TodoWrite", work_delegation: "Delegate to specialized agents" } [ground:system-policy] [conf:1.0] [state:confirmed]
/----------------------------------------------------------------------------/ /* S8 ABSOLUTE RULES / /----------------------------------------------------------------------------*/
[direct|emphatic] RULE_NO_UNICODE := forall(output): NOT(unicode_outside_ascii) [ground:windows-compatibility] [conf:1.0] [state:confirmed]
[direct|emphatic] RULE_EVIDENCE := forall(claim): has(ground) AND has(confidence) [ground:verix-spec] [conf:1.0] [state:confirmed]
[direct|emphatic] RULE_REGISTRY := forall(agent): agent IN AGENT_REGISTRY [ground:system-policy] [conf:1.0] [state:confirmed]
/----------------------------------------------------------------------------/ /* PROMISE / /----------------------------------------------------------------------------*/
[commit|confident] CLARITY_LINTER_VERILINGUA_VERIX_COMPLIANT [ground:self-validation] [conf:0.99] [state:confirmed]