| name | project-health |
| description | Systematic project health audit with categorized read-only checks. Auto-detects project type (Python/FastAPI, Next.js, Flutter, Node) and runs relevant checks across: state files, test coverage, dependency health, CI/CD status, documentation freshness, deployment safety, repository hygiene. Produces scored report (PASS/WARN/FAIL/SKIP) with remediation suggestions. Triggers: "health check", "project health", "how healthy is this project", "/health", "run health audit", "quick health check", "pre-deploy check". NOT for: security audits (use /security-audit), deep spec audits (use /deep-audit), code quality reviews (use /qa-review), toolkit integrity (use /system-integrity).
|
| allowed-tools | ["Bash","Read","Glob","Grep"] |
Project Health Audit
Inspired by CHIHUAUDIT's methodology: categorized, read-only, scored checks applied to application-layer concerns instead of OS-level infrastructure.
Quick Reference
| Mode | Trigger | Time | What |
|---|
| Quick | /health or /health quick | ~30s | State files + test counts + CI status |
| Full | /health full | ~2min | All 7 categories, full report |
| Pre-deploy | /health deploy | ~1min | Deployment-critical checks only |
Execution Flow
Step 1: Detect Project Type
Run these checks in order; first match wins:
if [ -f "pubspec.yaml" ]; then TYPE="flutter"
elif [ -f "pyproject.toml" ]; then TYPE="python"
elif [ -f "next.config.ts" ] || [ -f "next.config.mjs" ] || [ -f "next.config.js" ]; then TYPE="nextjs"
elif [ -f "package.json" ]; then TYPE="node"
else TYPE="generic"; fi
Report the detected type at the top of output.
Monorepo/multi-stack projects: If the project has subdirectories with different stacks (e.g., portal/ with Next.js inside a Python project), detect and report both. Run checks for each detected stack. Display as "Type: python (+ nextjs portal)".
Step 2: Select Check Mode
- quick: Run only STATE-*, TEST-001/002/003, CICD-001, DEPLOY-001/002
- full: Run ALL checks from
references/check-catalog.md matching the project type
- deploy: Run only DEPLOY-* and CICD-* checks
Step 3: Execute Checks
For each applicable check from references/check-catalog.md:
- Run the bash command (read-only, timeout 5s per command)
- Capture the numeric result
- Compare against threshold from
references/scoring-rubric.md
- Assign status: PASS / WARN / FAIL / SKIP
- For FAIL/WARN: note the remediation action
Step 4: Generate Report
Output format:
=== Project Health Report ===
Project: {dirname} | Type: {type} | Date: {YYYY-MM-DD}
Mode: {quick|full|deploy}
Category Checks Pass Warn Fail Skip
-------------------------------------------------------
State Files 4 3 1 0 0
Test Coverage 5 4 0 1 0
CI/CD 4 4 0 0 0
Dependencies 3 2 1 0 0
Documentation 3 3 0 0 0
Deployment 3 3 0 0 0
Repository 3 2 1 0 0
-------------------------------------------------------
TOTAL 25 21 3 1 0
Overall: WARN (1 failure, 3 warnings)
FAILURES:
[TEST-002] Portal test:route ratio 45% (threshold: 60%)
Remediation: Add tests for uncovered routes
WARNINGS:
[STATE-002] workbook.md at 280/300 lines (93%)
Suggestion: Collapse old sessions into archive table
[DEPS-001] 7 npm packages have updates available
Suggestion: Run npm update for non-breaking changes
[REPO-001] 6 non-standard files in project root
Suggestion: Move or archive floating files
Step 5: Optional Save
If the user says --save or "save the report":
- Write to
docs-to-process/{YYYYMMDD}-health-{project-name}.md
Check Details
Full check catalog with IDs, commands, thresholds, and remediation:
see references/check-catalog.md
Scoring rules and overall status calculation:
see references/scoring-rubric.md
Mode-specific check subsets:
see workflows/quick-check.md, workflows/full-audit.md, workflows/pre-deploy.md
Differentiation
This skill checks infrastructure health (files, CI, deps, repo hygiene).
It does NOT overlap with:
/deep-audit — spec-vs-implementation alignment (heavier, 7+ agents)/qa-review — code quality across 8 categories/security-audit — vulnerability scanning (Gemini-powered)/system-integrity — Claude Code toolkit validation
