Power Project Health Check

Analyze overall project health by evaluating code quality, delivery velocity, team balance, and dependency status, then produce a scored report with actionable recommendations.

When to Use This Command

Run this command when...

• You want a single comprehensive health score (0-100) for your project covering code quality, delivery, team, and dependencies
• You need to assess technical debt indicators like test coverage trends, code complexity, and outdated packages
• You are preparing for a quarterly review and need metrics on commit frequency, PR turnaround, and contributor distribution
• You want to detect knowledge concentration risks where a single contributor owns too much of the codebase
• You need a dependency health audit including security vulnerabilities, outdated packages, and license compliance

Quick Start

Copy
# .claude/commands/power-project-health-check.yaml
name: Power Project Health Check
description: Comprehensive project health analysis with scored report
inputs:
  - name: period
    description: "Evaluation period in days"
    default: "30"

Copy
# Default 30-day health check
claude "power-project-health-check"

# Check health over the last quarter
claude "power-project-health-check --period 90"

Output:
  [scan] Analyzing 30-day project health...
  Overall Health Score: 72/100 (Good)
  ┌─────────────────────┬───────┬────────┐
  │ Dimension           │ Score │ Status │
  ├─────────────────────┼───────┼────────┤
  │ Code Quality        │ 78    │ Good   │
  │ Delivery Performance│ 65    │ Fair   │
  │ Team Health         │ 80    │ Good   │
  │ Dependency Health   │ 64    │ Fair   │
  └─────────────────────┴───────┴────────┘
  3 recommendations generated. Report saved.

Core Concepts

Concept	Description
Health Score	A 0-100 composite score weighted across four dimensions: quality, delivery, team, and dependencies
Code Quality	Measures test coverage, complexity, security vulnerabilities, and technical debt indicators
Delivery Performance	Tracks commit frequency, PR review turnaround, bug-to-feature ratio, and velocity trends
Team Health	Evaluates work distribution balance, knowledge concentration risk, and contributor activity
Dependency Health	Audits outdated packages, security advisories, license compliance, and external service dependencies

Health Dimensions:
  ┌────────────────────────────────────────────┐
  │           Overall Health: 72/100           │
  ├───────────┬───────────┬──────────┬─────────┤
  │  Quality  │ Delivery  │   Team   │  Deps   │
  │   78/100  │  65/100   │  80/100  │ 64/100  │
  │  ██████░░ │ █████░░░░ │ ████████ │ █████░░ │
  └───────────┴───────────┴──────────┴─────────┘

Configuration

Parameter	Type	Default	Description
period	integer	30	Number of days to evaluate for trend analysis
output	string	"stdout"	Output destination: stdout, markdown file, or JSON file
dimensions	string	"all"	Specific dimensions to evaluate: quality, delivery, team, deps
threshold	integer	50	Minimum acceptable score; items below trigger warnings
compare	string	""	Compare against a previous report file for trend analysis

Best Practices

1. Run monthly and track trends -- A single health check is a snapshot. Monthly checks with --compare reveal whether the project is improving or declining over time.
2. Address critical findings first -- Focus on dimensions scoring below 50 before optimizing areas already in the green. Low scores indicate systemic risks that compound over time.
3. Share reports with the team -- Health check reports are most valuable when the entire team sees them. Use --output report.md and commit the file or share it in team channels.
4. Set thresholds per dimension -- Not all projects need perfect scores everywhere. A documentation project may tolerate lower delivery velocity scores that would be alarming in a production API.
5. Combine with dependency audits -- Run npm audit or equivalent before the health check so the dependency dimension has fresh vulnerability data to incorporate.

Common Issues

1. Insufficient git history -- Projects with fewer than 30 days of commits produce unreliable velocity and trend metrics. Use a shorter --period or wait until the project has more history.
2. No test coverage data -- The quality dimension relies on test coverage reports. If no coverage tool is configured, that sub-score defaults to zero and drags down the overall score.
3. Single-contributor skew -- Solo projects will always show high knowledge concentration risk. This is expected and can be acknowledged rather than treated as a problem to solve.