health

Clean Code Health

Print a short dashboard summarizing the project's clean code health. This skill is read-only by design — it reports, it does not change code. To fix what it reports, the user runs a specific skill (/cleancode:untangle fix, /cleancode:safety fix, /cleancode:fix).

Source: The Art of Clean Code, Principle 16 — Use Metrics.

When This Runs

• User asks for project health, a cleanliness score, or a quality dashboard
• Periodic team check-in on code quality

Arguments

/cleancode:health          # print dashboard, don't save
/cleancode:health save     # print + write .cleancode-health.md (for tracking over time)

Step 1: Scan the Project

1. Glob all source files (exclude node_modules, .git, dist, build, generated code).

2. For each file, measure:

   • Lines of code (excluding blank lines and comment-only lines)
   • Number of functions
   • Longest function length
   • Max nesting depth
   • Import count
   • For TypeScript files: number of exported classes and whether each has an interface

3. Aggregate across the project:

   • Total LOC
   • Total files
   • Files over 300 lines (Critical — Rule 1)
   • Files over 200 lines (Warning)
   • Functions over 40 lines (Critical — Rule 2)
   • Functions over 20 lines (Warning)
   • Average nesting depth
   • Max nesting depth
   • Interface coverage % (TS only): classes with interfaces / total public classes
   • Rough duplication estimate: run the 3-line-window duplication check, count flagged blocks

Step 2: Compute Cleanliness Score

Score is 100 minus weighted penalty for each violation. See references/metric-definitions.md for the exact formula. Summary:

Violation type	Penalty per occurrence
Critical file size	5
Critical function size	3
Warning file size	2
Warning function size	1
Deep nesting (> 4)	2
High fan-out (> 15 imports)	3
Missing interface [TS]	1
Duplication block	2
Hidden error (Rule 12)	3

Clamp to [0, 100]. Round to nearest integer.

Step 3: Print Dashboard

═══════════════════════════════════════════════════════════
  cleancode health — [Project Name]
═══════════════════════════════════════════════════════════

  Cleanliness Score: 72/100  🟡 Needs attention

  ──  Totals ──────────────────────────────
    Total LOC:              14,320
    Total files:               182
    Average file length:        79 lines
    Average function length:    14 lines
    Max nesting depth:           6

  ──  Violations ──────────────────────────
    🔴 Critical:  12
       • 3 files > 300 lines
       • 9 functions > 40 lines
    🟡 Warning:   38
       • 11 files > 200 lines
       • 22 functions > 20 lines
       •  5 method chains > 2
    🔵 Style:    124 (naming, magic numbers, unused code)

  ──  Top 10 Worst Files ──────────────────
    1. src/App.tsx                        487 lines 🔴
    2. src/services/userService.ts        412 lines 🔴
    3. src/utils/helpers.ts               378 lines 🔴
    ...

  ──  Top 10 Longest Functions ───────────
    1. processOrder()     src/order.ts           98 lines 🔴
    2. validateInput()    src/validator.ts       72 lines 🔴
    ...

  ──  TypeScript Coverage ─────────────────
    Interface coverage:       64% (32/50 public classes)

  ──  Suggested Next Actions ──────────────
    • Start with /cleancode:fix src/App.tsx
    • Run /cleancode:analyze src/services/userService.ts
    • Run /cleancode:untangle . to find coupling issues

═══════════════════════════════════════════════════════════

Step 4: Save (if requested)

If the user passed save:

1. Write the dashboard text + raw metrics (JSON block) to <project root>/.cleancode-health.md.

2. If the file already exists, append today's run to a history section:

   # Clean Code Health
   
   Last run: 2026-04-15
   
   ## Current
   [dashboard as above]
   
   ## History
   
   | Date | Score | Critical | Warning | Style |
   |---|---|---|---|---|
   | 2026-04-15 | 72 | 12 | 38 | 124 |
   | 2026-04-01 | 68 | 15 | 42 | 131 |
   | 2026-03-15 | 61 | 19 | 48 | 144 |
   

The history table is how teams track progress over time.

Rules

• Read-only. This skill never modifies source code. To fix, use the specific fixer skills.
• Always whole-project. Single-file health doesn't make sense — use /cleancode:analyze <file> for that.
• Fast. Don't deep-analyze every file; use quick line counts and spot-check violations. Target < 10 seconds for projects up to 200 files.
• Stable scoring. The formula in metric-definitions.md should not drift between runs — re-running on unchanged code must produce the same score.

Additional Resources

• references/metric-definitions.md — exact scoring formula, metric calculations, and tuning notes