ABOUTME: Measures cognitive load of codebases using 8 dimensions, producing a 0-1000 score

ABOUTME: Sigmoid-normalized metrics with P90 weighting, Python calculator for deterministic results

Cognitive Load Analyzer

Produce a deterministic Cognitive Load Index (0-1000) with per-dimension breakdown and actionable recommendations.

When to run: before major refactors, when onboarding to unfamiliar codebases, during architecture reviews, or to track complexity trends over time.

Scoring Scale

Score is asymptotic: 0 and 1000 are unreachable by design. Cap at 999.

The 8 Dimensions

Weights sum to 1.00.

Formula derivations

Per-dimension sub-weights, the sigmoid definition, P90 weighting, and the aggregation/interaction-penalty math live in references/formulas.md. The lib/cli_calculator.py script is the deterministic source of truth; read the reference only to audit or explain a score.

Workflow

Phase 1: Discovery (2-3 turns)

1. Detect language(s) from file extensions
2. Count files, directories, LOC
3. Probe tools: command -v lizard radon jscpd gocyclo
4. If >100K LOC, activate deterministic sampling (SHA-256 hash mod 100 < 30, plus all files >200 LOC)

Phase 2: Dimension Collection (8-12 turns)

For each D1-D8:

1. Run tool or fallback command to collect raw metrics
2. Invoke calculator: uv run --no-project python3 <skilldir>/lib/clicalculator.py normalize-d<N> '<json>'
3. Record: raw metrics, normalized score, tool used, warnings

Tool priority: lizard (30+ languages) > language-specific (radon, gocyclo, eslint) > grep/awk/find heuristics.

Phase 3: Aggregation (2-3 turns)

1. Pass all scores: uv run --no-project python3 <skilldir>/lib/clicalculator.py aggregate '{"D1": ..., "D8": ...}'
2. Identify top 3 dimensions and top 5 worst offenders
3. Produce report

Calculator Commands

Script path: skills/cognitive-load-analyzer/lib/cli_calculator.py

All output is {"ok": true, "result": {...}} or {"ok": false, "error": "..."}.

Report Format

# Cognitive Load Index Report

## Summary
- CLI Score: {score} / 1000 ({rating})
- Language: {lang} | Files: {count} | LOC: {loc}
- D4 Mode: {llm_model | static_heuristic}

## Dimension Breakdown
| Dimension | Raw | Normalized | Weighted | Rating |
|-----------|-----|------------|----------|--------|
| D1-D8 rows... |
| Interaction Penalty | {pairs} | | +{pts} | |
| **TOTAL** | | | **{cli}** | **{rating}** |

## Top 5 Worst Offenders
1. {file:function} - {metrics}

## Recommendations
1. {action targeting highest-contributing dimension}

## Methodology
- Tools: {list} | Fallbacks: {list or "none"}
- Sampling: {full | SHA256 deterministic N%}

Recommended Actions by Dimension

Prioritize higher-weighted dimensions (D1, D4) over lower ones (D7, D8).

Polyglot Codebases

Analyze each language subset independently, aggregate weighted by LOC: CLIpolyglot = sum(LOClang / LOCtotal * CLIlang)

Large Codebase Sampling (>100K LOC)

selected = [f for f in sorted(files)
            if int(hashlib.sha256(f.encode()).hexdigest()[:8], 16) % 100 < 30]
# Plus all files > 200 LOC

Deterministic: identical results across runs for same codebase.