# Specter Health

> Generate a codebase health report showing complexity hotspots, dead code, and overall metrics Use when this capability is needed.

- Skill: `tomevault-io/specter-health` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/specter-health`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/specter-health/raw
- Safety review: pending (external: skill-scanner PASS, skillspector PASS)
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/specter-health

---


# Specter Health

Get a comprehensive health report for your codebase.

## When to Use

- Starting work on an unfamiliar codebase
- Planning refactoring priorities
- Before a code review or architecture discussion
- Regular health check-ins on long-running projects

## How to Run

```bash
npx specter-mcp health
```

Or with options:

```bash
# Show more hotspots
npx specter-mcp health --limit 20
```

## What It Shows

### Health Score (0-100)
- 🟢 80-100: Healthy codebase
- 🟡 60-79: Some attention needed
- 🔴 0-59: Significant technical debt

### Complexity Distribution
Breaks down functions by complexity level:
- **Low (1-5)**: Simple, easy to understand
- **Medium (6-10)**: Reasonable complexity
- **High (11-20)**: Consider refactoring
- **Very High (21+)**: Should be broken down

### Complexity Hotspots
Lists the most complex functions/methods with:
- File path and line number
- Function/method name
- Cyclomatic complexity score

## Understanding Complexity

Cyclomatic complexity counts decision points:
- Each `if`, `else`, `switch case`, `for`, `while` adds 1
- Ternary operators (`? :`) add 1
- Logical operators (`&&`, `||`) add 1
- `catch` blocks add 1

**Rule of thumb:**
- 1-5: Simple function
- 6-10: Moderate complexity
- 11-20: High complexity, hard to test
- 21+: Very high, should be refactored

## Recommendations

If you have many high-complexity functions:
1. Extract helper functions
2. Use early returns to reduce nesting
3. Replace complex conditionals with lookup tables
4. Split god functions into focused modules

## Using with Specter Agent

After running health, ask the specter agent:
- "Tell me about my complexity hotspots"
- "What should I refactor first?"
- "Which functions are hardest to maintain?"

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/forbiddenlink) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-13 -->