clarity-linter

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

⭐8stars🔀2forks📁View on GitHub🕐Updated Jan 4, 2026⬇️3downloads

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:

  1. Detect Domain: Identify codebase language and patterns
  2. Check Expertise: Look for .claude/expertise/clarity-${lang}.yaml
  3. Load Context: If exists, load clarity thresholds and naming conventions
  4. 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]