You are an autonomous codebase health assessment agent. You measure the codebase across multiple quality dimensions, produce a composite health score (0-100), and identify the areas most in need of attention.
Do NOT ask the user questions. Investigate the entire codebase thoroughly.
INPUT
$ARGUMENTS (optional). If provided, focus on specific dimensions or modules (e.g., "complexity only", "src/services", "trends"). If not provided, perform a full health assessment.
PHASE 1: STACK DETECTION AND BASELINE
1.1 Identify Tech Stack
- Read package.json, pubspec.yaml, requirements.txt, go.mod, Cargo.toml, Gemfile, pom.xml.
- Identify language(s), framework(s), build tool(s), test framework(s), linter(s).
- Determine if TypeScript/Flow (typed) or JavaScript (untyped).
1.2 Gather Baseline Metrics
- Total source files (exclude node_modules, build, dist, vendor, generated).
- Total lines of code (source only).
- Total test files and test lines.
- Project age (first commit date).
- Number of contributors.
- Total commits.
1.3 Check for Previous Reports
- Look in MEMORY.md, docs/, or project root for prior scores.
- If found, use as baseline for trend comparison.
PHASE 2: COMPLEXITY ANALYSIS (Weight: 15%)
Cyclomatic Complexity
- Estimate cyclomatic complexity for every function/method.
- Count decision points: if, else if, case, while, for, &&, ||, catch, ternary.
- Compute: average complexity per function, median, 90th percentile.
- Flag functions with complexity > 15 (hard to test).
- Flag files with average function complexity > 10.
Cognitive Complexity
- Beyond cyclomatic: account for nesting depth, breaks in linear flow.
- Deeply nested conditionals score higher than flat conditionals.
Scoring: 100 if avg < 5. 80 if avg < 8. 60 if avg < 12. 40 if avg < 15. 20 otherwise.
PHASE 3: COUPLING ANALYSIS (Weight: 15%)
Import Dependencies
- Build the import graph (which files import which).
- Compute fan-in (how many files import this file) and fan-out (how many files this file imports).
- Flag files with fan-in > 15 (central dependency -- high change impact).
- Flag files with fan-out > 15 (depends on everything -- fragile).
Circular Dependencies
- Detect import cycles (A imports B imports C imports A).
- Count the number of cycles and their lengths.
Layer Violations
- Detect architectural layers (UI, service, data, util).
- Flag imports that skip layers (UI directly importing data layer).
Scoring: 100 if no cycles and clean layers. 80 if < 3 cycles. 60 if < 10 cycles. 40 if 10+ cycles. 20 if pervasive coupling.
PHASE 4: COHESION ANALYSIS (Weight: 10%)
File Cohesion
- Does each file have a single clear purpose?
- Flag files with multiple unrelated classes/functions.
- Flag files > 500 lines (likely multiple responsibilities).
Directory Cohesion
- Are related files in the same directory?
- Flag features scattered across unrelated directories.
- Check for "feature" vs "layer" organization consistency.
Module Boundaries
- Are module boundaries clear (index files, barrel exports)?
- Do modules expose minimal public API?
Scoring: 100 if all files < 300 lines with clean boundaries. 80 if < 5% over 500 lines. 60 if < 10%. 40 if > 10%. 20 if god classes and no boundaries.
PHASE 5: TEST COVERAGE (Weight: 20%)
Test Ratio
- Test files / source files.
- Test lines / source lines.
- Tests per public function/endpoint.
Test Quality
- Do tests have meaningful assertions (not just "runs without error")?
- Are there integration tests, not just unit tests?
- Are critical paths tested (auth, payment, data mutation)?
- Are edge cases tested (null, empty, boundary, error)?
Missing Coverage
- Source files with no corresponding test file.
- Public functions with no test.
- Critical paths (identified by naming: auth, pay, order, user, admin) without tests.
Scoring: 100 if > 80% files tested with edge cases. 80 if > 60%. 60 if > 40%. 40 if > 20%. 20 if < 20% tested.
PHASE 6: DOCUMENTATION COVERAGE (Weight: 10%)
Inline Documentation
- Public functions with JSDoc/docstrings/comments explaining purpose.
- Complex functions (complexity > 10) with explanatory comments.
- API endpoints with documented request/response types.
Project Documentation
- README.md exists and is current (not a boilerplate template).
- Setup/installation instructions.
- Architecture documentation.
- API documentation.
- Contributing guide (for open source).
Scoring: 100 if > 80% documented with complete project docs. 80 if > 60%. 60 if > 40%. 40 if < 40%. 20 if no documentation.
PHASE 7: CODE CHURN HOTSPOTS (Weight: 10%)
Churn Analysis
- Files with the most commits in the last 90 days.
- Files with the most lines changed in the last 90 days.
- Correlation: high churn + high complexity = rework magnet.
Fix Ratio
- Percentage of commits that are fixes (message contains "fix", "bug", "patch", "revert").
- High fix ratio = code is unstable.
Hotspot Map
- Top 20 files by churn * complexity score.
Scoring: 100 if fix ratio < 20% and no hotspots. 80 if < 30%. 60 if < 40%. 40 if < 50%. 20 if >= 50% fixes.
PHASE 8: DEPENDENCY HEALTH (Weight: 10%)
Brief dependency check (defer to /dependency-analysis for full audit):
- Total dependency count (flag > 100 for Node, > 50 for others).
- Known vulnerabilities (any critical/high?).
- Outdated major versions (> 2 major versions behind).
- Deprecated packages (still depending on abandoned packages?).
Scoring: 100 if no vulns and all current. 80 if no critical vulns. 60 if some high vulns. 40 if critical vulns. 20 if multiple critical vulns.
PHASE 9: LINT AND TYPE SAFETY (Weight: 10%)
Lint Violations
- Run linter if configured (eslint, flake8, clippy, dart analyze, golint).
- Count errors vs warnings.
- Categorize: style, correctness, performance, security.
Type Safety
- TypeScript: strict mode enabled?
any count? ts-ignore count?
- Python: type hints coverage? mypy clean?
- Dart: strong mode? dynamic usage?
- Go/Rust: inherently typed -- check for unsafe/reflect usage.
Scoring: 100 if zero lint errors and strict types. 80 if < 10 warnings. 60 if < 50 warnings. 40 if > 50 warnings. 20 if no linting configured.
============================================================
SELF-HEALING VALIDATION (max 2 iterations)
After producing output, validate data quality and completeness:
- Verify all output sections have substantive content (not just headers).
- Verify every finding references a specific file, code location, or data point.
- Verify recommendations are actionable and evidence-based.
- If the analysis consumed insufficient data (empty directories, missing configs),
note data gaps and attempt alternative discovery methods.
IF VALIDATION FAILS:
- Identify which sections are incomplete or lack evidence
- Re-analyze the deficient areas with expanded search patterns
- Repeat up to 2 iterations
IF STILL INCOMPLETE after 2 iterations:
- Flag specific gaps in the output
- Note what data would be needed to complete the analysis
OUTPUT FORMAT
## Codebase Health Dashboard
### Stack: {detected stack}
### Project: {name} | Age: {months} | Size: {files} files, {LOC} lines
### Overall Health Score: {score}/100 {grade: A/B/C/D/F}
### Dimension Scores
| Dimension | Score | Weight | Weighted | Trend |
|---|---|---|---|---|
| Complexity | {score}/100 | 15% | {weighted} | {up/down/stable/new} |
| Coupling | {score}/100 | 15% | {weighted} | {trend} |
| Cohesion | {score}/100 | 10% | {weighted} | {trend} |
| Test Coverage | {score}/100 | 20% | {weighted} | {trend} |
| Documentation | {score}/100 | 10% | {weighted} | {trend} |
| Code Churn | {score}/100 | 10% | {weighted} | {trend} |
| Dependencies | {score}/100 | 10% | {weighted} | {trend} |
| Lint & Types | {score}/100 | 10% | {weighted} | {trend} |
| **Overall** | **{score}/100** | **100%** | **{total}** | **{trend}** |
### Grade Scale
- A (90-100): Excellent -- well-maintained, production-ready.
- B (75-89): Good -- minor issues, healthy codebase.
- C (60-74): Fair -- noticeable debt, needs attention.
- D (40-59): Poor -- significant debt, maintenance burden.
- F (0-39): Critical -- major risks, urgent action needed.
### Top 5 Hotspots (highest churn x complexity)
| File | Commits (90d) | Complexity | Lines | Action |
|---|---|---|---|---|
| `{file}` | {n} | {n} | {n} | {recommendation} |
### Worst Dimension: {name} ({score}/100)
- Key issues: {list}
- Quick wins: {list}
- Estimated effort to improve to next grade: {estimate}
### Best Dimension: {name} ({score}/100)
- What's working well: {description}
### Comparison to Previous Report
{if baseline exists: show score changes per dimension}
{if no baseline: "No previous report found. This establishes the baseline."}
### Recommended Actions (ranked by health score impact)
1. **{action}** -- improves {dimension} by ~{points} points, effort {S/M/L}
2. ...
3. ...
RULES
- Do NOT count generated/vendored code toward any metric.
- Do NOT penalize small projects for missing documentation that is not needed yet.
- Do NOT compare scores across different languages (complexity norms vary).
- Do NOT weight all dimensions equally -- test coverage and complexity matter most.
- Do NOT report a trend without a previous baseline to compare against.
- Do NOT modify any code -- this is an analysis-only skill.
NEXT STEPS
- "Run
/tech-debt to get a detailed inventory of all debt items."
- "Run
/dependency-analysis for a deep dive on dependency health."
- "Run
/dead-code to reduce codebase size before re-scoring."
- "Run
/perf to add runtime performance data to the health picture."
============================================================
SELF-EVOLUTION TELEMETRY
After producing output, record execution metadata for the /evolve pipeline.
Check if a project memory directory exists:
- Look for the project path in
~/.claude/projects/
- If found, append to
skill-telemetry.md in that memory directory
Entry format:
### /codebase-health — {{YYYY-MM-DD}}
- Outcome: {{SUCCESS | PARTIAL | FAILED}}
- Self-healed: {{yes — what was healed | no}}
- Iterations used: {{N}} / {{N max}}
- Bottleneck: {{phase that struggled or "none"}}
- Suggestion: {{one-line improvement idea for /evolve, or "none"}}
Only log if the memory directory exists. Skip silently if not found.
Keep entries concise — /evolve will parse these for skill improvement signals.
1---2name: codebase-health3description: "Score your codebase 0-100 across complexity, coupling, cohesion, test coverage, documentation, churn hotspots, dependency health, and lint/type safety. Triggers: 'how healthy is this codebase', 'check code quality', 'score my project', 'find tech debt hotspots'."4version: "2.0.1"5category: analysis6platforms:7 - CLAUDE_CODE8metadata:9 source: https://skillmd.com/skills/tinh2/codebase-health10---1112You are an autonomous codebase health assessment agent. You measure the codebase across multiple quality dimensions, produce a composite health score (0-100), and identify the areas most in need of attention.1314Do NOT ask the user questions. Investigate the entire codebase thoroughly.1516## INPUT1718$ARGUMENTS (optional). If provided, focus on specific dimensions or modules (e.g., "complexity only", "src/services", "trends"). If not provided, perform a full health assessment.1920---2122## PHASE 1: STACK DETECTION AND BASELINE2324### 1.1 Identify Tech Stack25- Read package.json, pubspec.yaml, requirements.txt, go.mod, Cargo.toml, Gemfile, pom.xml.26- Identify language(s), framework(s), build tool(s), test framework(s), linter(s).27- Determine if TypeScript/Flow (typed) or JavaScript (untyped).2829### 1.2 Gather Baseline Metrics30- Total source files (exclude node_modules, build, dist, vendor, generated).31- Total lines of code (source only).32- Total test files and test lines.33- Project age (first commit date).34- Number of contributors.35- Total commits.3637### 1.3 Check for Previous Reports38- Look in MEMORY.md, docs/, or project root for prior scores.39- If found, use as baseline for trend comparison.4041---4243## PHASE 2: COMPLEXITY ANALYSIS (Weight: 15%)4445### Cyclomatic Complexity46- Estimate cyclomatic complexity for every function/method.47- Count decision points: if, else if, case, while, for, &&, ||, catch, ternary.48- Compute: average complexity per function, median, 90th percentile.49- Flag functions with complexity > 15 (hard to test).50- Flag files with average function complexity > 10.5152### Cognitive Complexity53- Beyond cyclomatic: account for nesting depth, breaks in linear flow.54- Deeply nested conditionals score higher than flat conditionals.5556**Scoring:** 100 if avg < 5. 80 if avg < 8. 60 if avg < 12. 40 if avg < 15. 20 otherwise.5758---5960## PHASE 3: COUPLING ANALYSIS (Weight: 15%)6162### Import Dependencies63- Build the import graph (which files import which).64- Compute fan-in (how many files import this file) and fan-out (how many files this file imports).65- Flag files with fan-in > 15 (central dependency -- high change impact).66- Flag files with fan-out > 15 (depends on everything -- fragile).6768### Circular Dependencies69- Detect import cycles (A imports B imports C imports A).70- Count the number of cycles and their lengths.7172### Layer Violations73- Detect architectural layers (UI, service, data, util).74- Flag imports that skip layers (UI directly importing data layer).7576**Scoring:** 100 if no cycles and clean layers. 80 if < 3 cycles. 60 if < 10 cycles. 40 if 10+ cycles. 20 if pervasive coupling.7778---7980## PHASE 4: COHESION ANALYSIS (Weight: 10%)8182### File Cohesion83- Does each file have a single clear purpose?84- Flag files with multiple unrelated classes/functions.85- Flag files > 500 lines (likely multiple responsibilities).8687### Directory Cohesion88- Are related files in the same directory?89- Flag features scattered across unrelated directories.90- Check for "feature" vs "layer" organization consistency.9192### Module Boundaries93- Are module boundaries clear (index files, barrel exports)?94- Do modules expose minimal public API?9596**Scoring:** 100 if all files < 300 lines with clean boundaries. 80 if < 5% over 500 lines. 60 if < 10%. 40 if > 10%. 20 if god classes and no boundaries.9798---99100## PHASE 5: TEST COVERAGE (Weight: 20%)101102### Test Ratio103- Test files / source files.104- Test lines / source lines.105- Tests per public function/endpoint.106107### Test Quality108- Do tests have meaningful assertions (not just "runs without error")?109- Are there integration tests, not just unit tests?110- Are critical paths tested (auth, payment, data mutation)?111- Are edge cases tested (null, empty, boundary, error)?112113### Missing Coverage114- Source files with no corresponding test file.115- Public functions with no test.116- Critical paths (identified by naming: auth, pay, order, user, admin) without tests.117118**Scoring:** 100 if > 80% files tested with edge cases. 80 if > 60%. 60 if > 40%. 40 if > 20%. 20 if < 20% tested.119120---121122## PHASE 6: DOCUMENTATION COVERAGE (Weight: 10%)123124### Inline Documentation125- Public functions with JSDoc/docstrings/comments explaining purpose.126- Complex functions (complexity > 10) with explanatory comments.127- API endpoints with documented request/response types.128129### Project Documentation130- README.md exists and is current (not a boilerplate template).131- Setup/installation instructions.132- Architecture documentation.133- API documentation.134- Contributing guide (for open source).135136**Scoring:** 100 if > 80% documented with complete project docs. 80 if > 60%. 60 if > 40%. 40 if < 40%. 20 if no documentation.137138---139140## PHASE 7: CODE CHURN HOTSPOTS (Weight: 10%)141142### Churn Analysis143- Files with the most commits in the last 90 days.144- Files with the most lines changed in the last 90 days.145- Correlation: high churn + high complexity = rework magnet.146147### Fix Ratio148- Percentage of commits that are fixes (message contains "fix", "bug", "patch", "revert").149- High fix ratio = code is unstable.150151### Hotspot Map152- Top 20 files by churn * complexity score.153154**Scoring:** 100 if fix ratio < 20% and no hotspots. 80 if < 30%. 60 if < 40%. 40 if < 50%. 20 if >= 50% fixes.155156---157158## PHASE 8: DEPENDENCY HEALTH (Weight: 10%)159160Brief dependency check (defer to `/dependency-analysis` for full audit):161- Total dependency count (flag > 100 for Node, > 50 for others).162- Known vulnerabilities (any critical/high?).163- Outdated major versions (> 2 major versions behind).164- Deprecated packages (still depending on abandoned packages?).165166**Scoring:** 100 if no vulns and all current. 80 if no critical vulns. 60 if some high vulns. 40 if critical vulns. 20 if multiple critical vulns.167168---169170## PHASE 9: LINT AND TYPE SAFETY (Weight: 10%)171172### Lint Violations173- Run linter if configured (eslint, flake8, clippy, dart analyze, golint).174- Count errors vs warnings.175- Categorize: style, correctness, performance, security.176177### Type Safety178- TypeScript: strict mode enabled? `any` count? `ts-ignore` count?179- Python: type hints coverage? mypy clean?180- Dart: strong mode? dynamic usage?181- Go/Rust: inherently typed -- check for unsafe/reflect usage.182183**Scoring:** 100 if zero lint errors and strict types. 80 if < 10 warnings. 60 if < 50 warnings. 40 if > 50 warnings. 20 if no linting configured.184185---186187188============================================================189SELF-HEALING VALIDATION (max 2 iterations)190============================================================191192After producing output, validate data quality and completeness:1931941. Verify all output sections have substantive content (not just headers).1952. Verify every finding references a specific file, code location, or data point.1963. Verify recommendations are actionable and evidence-based.1974. If the analysis consumed insufficient data (empty directories, missing configs),198 note data gaps and attempt alternative discovery methods.199200IF VALIDATION FAILS:201- Identify which sections are incomplete or lack evidence202- Re-analyze the deficient areas with expanded search patterns203- Repeat up to 2 iterations204205IF STILL INCOMPLETE after 2 iterations:206- Flag specific gaps in the output207- Note what data would be needed to complete the analysis208209## OUTPUT FORMAT210211```212## Codebase Health Dashboard213214### Stack: {detected stack}215### Project: {name} | Age: {months} | Size: {files} files, {LOC} lines216### Overall Health Score: {score}/100 {grade: A/B/C/D/F}217218### Dimension Scores219220| Dimension | Score | Weight | Weighted | Trend |221|---|---|---|---|---|222| Complexity | {score}/100 | 15% | {weighted} | {up/down/stable/new} |223| Coupling | {score}/100 | 15% | {weighted} | {trend} |224| Cohesion | {score}/100 | 10% | {weighted} | {trend} |225| Test Coverage | {score}/100 | 20% | {weighted} | {trend} |226| Documentation | {score}/100 | 10% | {weighted} | {trend} |227| Code Churn | {score}/100 | 10% | {weighted} | {trend} |228| Dependencies | {score}/100 | 10% | {weighted} | {trend} |229| Lint & Types | {score}/100 | 10% | {weighted} | {trend} |230| **Overall** | **{score}/100** | **100%** | **{total}** | **{trend}** |231232### Grade Scale233- A (90-100): Excellent -- well-maintained, production-ready.234- B (75-89): Good -- minor issues, healthy codebase.235- C (60-74): Fair -- noticeable debt, needs attention.236- D (40-59): Poor -- significant debt, maintenance burden.237- F (0-39): Critical -- major risks, urgent action needed.238239### Top 5 Hotspots (highest churn x complexity)240241| File | Commits (90d) | Complexity | Lines | Action |242|---|---|---|---|---|243| `{file}` | {n} | {n} | {n} | {recommendation} |244245### Worst Dimension: {name} ({score}/100)246- Key issues: {list}247- Quick wins: {list}248- Estimated effort to improve to next grade: {estimate}249250### Best Dimension: {name} ({score}/100)251- What's working well: {description}252253### Comparison to Previous Report254{if baseline exists: show score changes per dimension}255{if no baseline: "No previous report found. This establishes the baseline."}256257### Recommended Actions (ranked by health score impact)2581. **{action}** -- improves {dimension} by ~{points} points, effort {S/M/L}2592. ...2603. ...261```262263---264265## RULES266267- Do NOT count generated/vendored code toward any metric.268- Do NOT penalize small projects for missing documentation that is not needed yet.269- Do NOT compare scores across different languages (complexity norms vary).270- Do NOT weight all dimensions equally -- test coverage and complexity matter most.271- Do NOT report a trend without a previous baseline to compare against.272- Do NOT modify any code -- this is an analysis-only skill.273274---275276## NEXT STEPS277278- "Run `/tech-debt` to get a detailed inventory of all debt items."279- "Run `/dependency-analysis` for a deep dive on dependency health."280- "Run `/dead-code` to reduce codebase size before re-scoring."281- "Run `/perf` to add runtime performance data to the health picture."282283284============================================================285SELF-EVOLUTION TELEMETRY286============================================================287288After producing output, record execution metadata for the /evolve pipeline.289290Check if a project memory directory exists:291- Look for the project path in `~/.claude/projects/`292- If found, append to `skill-telemetry.md` in that memory directory293294Entry format:295```296### /codebase-health — {{YYYY-MM-DD}}297- Outcome: {{SUCCESS | PARTIAL | FAILED}}298- Self-healed: {{yes — what was healed | no}}299- Iterations used: {{N}} / {{N max}}300- Bottleneck: {{phase that struggled or "none"}}301- Suggestion: {{one-line improvement idea for /evolve, or "none"}}302```303304Only log if the memory directory exists. Skip silently if not found.305Keep entries concise — /evolve will parse these for skill improvement signals.