project-health

name	project-health
description	Use when correctness, completeness, or consistency of a project needs verification — "is the project healthy?", "pre-release check", "do a health check", "check docs are in sync", invokes /project-health. NOT for improvement suggestions (use project-refine for that).

Project Health

Answer the question: is this project correct, complete, and consistent?

Runs universal quality checks that apply to every project type, then runs type-specific health checks inline based on the project type declared in CLAUDE.md.

---

Step 0 — Read Project Type

Before any checks run, read the project type:

python3 ~/.claude/skills/project-init/ctx.py

Read PROJECT_TYPE from the output.

Extract the type: skills | java | blog | custom | generic

If PROJECT_TYPE is empty, treat as generic and note it as a config finding.

Store the type — type-aware checks (primary-doc, artifacts, conventions, framework) use it throughout this skill.

---

Step 1 — Determine Tier

Parse flags from the invocation:

Flag	Tier	What runs
--commit	1	validate_all.py --tier commit only
--standard	2	Universal quality checks
--prerelease	3	Universal + type-specific quality checks
--deep	4	All of tier 3 + refinement questions
--tier N	N	Explicit tier (1–4)

If no tier flag is given, prompt:

How thorough should this check be?

1 — Quick — validators only (~30s) 2 — Standard — universal quality checks (~5 min) 3 — Full — universal + type-specific quality (~15 min) 4 — Deep — everything + refinement questions (~30 min)

Enter 1–4 (default: 2):

Wait for response. If no response, use tier 2.

Also parse:

• --save → write report to YYYY-MM-DD-health-report.md after output
• Category names (e.g. docs-sync consistency) → run only those categories
• If categories specified without --tier, run at tier 2

---

Step 2 — Tier 1: Run Automated Validators

Always run first (all tiers include this):

python scripts/validate_all.py --tier commit

If this script doesn't exist, note it as a config finding and skip.

Report output. If CRITICAL findings from validators → flag them.

For tier 1, stop here. Present findings and exit.

---

Step 3 — Build Document Scan List

For tier 2+, build the scan scope before running checks.

Always included:

• All .md files (recursive) under doc/, docs/, documentation/ (case-insensitive)
• Root-level .md files matching: readme, overview, summary, index, contributing, governance, code_of_conduct, changelog, history, release, architecture, design, decisions, vision, philosophy, principles, api, schema, glossary, security, deployment, install, usage, troubleshooting, roadmap, spec, requirements, quality (case-insensitive match on filename stem)
• Any root .md not on the list is still scanned
• Any README.md, CHANGELOG.md, CONTRIBUTING.md, ARCHITECTURE.md anywhere in the tree

Type-specific additions (use detected type from Step 0):

• skills → all SKILL.md files in direct subdirectories
• java → pom.xml, build.gradle, Javadoc comments in src/
• blog → _config.yml, _posts/, _layouts/, _includes/
• custom → primary document path declared in CLAUDE.md

User-configured additions: Read ## Health Check Configuration from CLAUDE.md:

Additional doc paths: wiki/, design/

Add any listed paths to the scan scope.

---

Step 4 — Read CLAUDE.md Health Configuration

grep -A 10 "## Health Check Configuration" CLAUDE.md 2>/dev/null

Parse:

• Default checks: → limit to these categories if no categories specified on invocation
• Skip: → exclude these categories even if requested
• Additional doc paths: → already applied in Step 3

If no configuration section, use built-in defaults: run all universal categories.

---

Step 5 — Run Universal Checks

Run the applicable check categories at the requested tier. Skip categories listed in Skip: from CLAUDE.md. If specific categories were requested, run only those.

For tier 2: quality items only (pass/fail checks). For tier 4: quality items + refinement questions (judgment items).

Read check-categories.md for the full quality and refinement checklists for all 12 universal categories before running checks: docs-sync, consistency, logic, config, security, release, user-journey, git, primary-doc, artifacts, conventions, framework.

---

Step 6 — Run Type-Specific Checks (Tier 3+)

At tier 3 and 4, after universal checks complete, read the type-specific content file and execute the checks it describes. Type-specific findings are prefixed with [type] (e.g. [java]).

Project type	File to read
skills	~/.claude/skills/project-health/skills-repo.md
java	~/.claude/skills/project-health/java.md
blog	~/.claude/skills/project-health/blog.md
custom	~/.claude/skills/project-health/custom.md
python	~/.claude/skills/project-health/python.md
ts / TypeScript detected	~/.claude/skills/project-health/typescript.md
generic	Skip — universal checks only

Read the file, then execute the checks described in it.

If the project type is generic but TypeScript or Python files are found, suggest running the relevant section manually.

---

Step 7 — Present Report

## project-health report — [categories run] — tier [N]

### CRITICAL (must fix)
- [category] finding description

### HIGH (should fix)
- [category] finding description

### MEDIUM (worth fixing)
- [category] finding description

### LOW (nice to fix)
- [category] finding description

### PASS
✅ category1, category2, ...

Universal findings have no extra prefix. Type-specific findings are prefixed with [type] (e.g. [java]). If no findings in a severity level, omit that section.

---

Step 8 — Offer Auto-Fix (Mechanical Issues Only)

For mechanical findings (wrong count in README, stale version number, missing commands/<name>.md), offer:

Auto-fixable findings detected.

Would you like me to apply mechanical fixes now?

• [list of specific fixes]

(YES / NO — judgment calls are never auto-applied)

Wait for response. Apply only on YES. Never auto-apply.

---

Step 9 — Save Report (if --save)

If --save was passed, write findings to a date-prefixed file:

# Format: YYYY-MM-DD-health-report.md

Tell user:

Report saved to YYYY-MM-DD-health-report.md. This file is gitignored by default.

Verify .gitignore includes *-health-report.md or similar. If not, suggest adding it.

---

Common Pitfalls

Mistake	Why It's Wrong	Fix
Running type-specific checks before reading project type	Checks have no context	Always read project type in Step 0 first
Reporting "plans to implement" as bugs	Intentional design language	Distinguish docs describing intent vs. describing current state
Auto-fixing judgment findings	Judgment calls require human decision	Only auto-fix mechanical findings, always with YES confirmation
Skipping type-specific section at tier 3+	Incomplete health picture	Run the type-specific section — it's mandatory at tier 3+ unless type is generic
Treating all findings as equal	CRITICAL blocks release, LOW does not	Use severity consistently
Running docs-sync without reading the actual source files	Can't verify claims without reading	Read code and docs together

---

Success Criteria

Health check is complete when:

• ✅ Project type read from CLAUDE.md before any checks ran
• ✅ Tier confirmed (via flag or prompt)
• ✅ All applicable universal categories checked at the requested tier
• ✅ Type-specific section run at tier 3+ (or skipped for generic)
• ✅ Report presented with findings grouped by severity
• ✅ Mechanical auto-fix offered (not applied without YES)
• ✅ Report saved if --save was passed

Not complete until all applicable categories checked and report presented.

---

Skill Chaining

Invoked by:

• User says "health check", "is the project healthy", "pre-release check", or invokes /project-health
• Other skills (e.g. git-commit) can suggest /project-health --commit after significant changes

Companion skill:

• [project-refine] — once health is green, use project-refine for improvement opportunities (bloat, structure, deduplication). They share the same CLAUDE.md Health Check Configuration section.