project-health-report

name	project-health-report
description	Comprehensive whole-project health report across code quality, architecture, testing, dependencies, and documentation. Use for a breadth-first snapshot of the entire repo. For PR-scope diffs use /review-pipeline; for one dimension use the specific /*-audit.
user-invocable	true

Project Health Report

Core Rule

Aggregate other audit findings into a stable scorecard. Don't invent metrics — only roll up signals other skills produced. Output must be reproducible.

When to Use

Invoke with /project-health-report when:

• Due diligence assessment of a codebase (acquisition, handoff, audit)
• Periodic project health check (quarterly review)
• New team lead onboarding to assess project state
• Planning a major initiative and need to understand the baseline
• Stakeholder reporting on technical health

Default Behavior

When the user asks to audit, scan, review, or "give me a report" for project health, produce the full project-health-report report automatically using the Process and Output Format sections below. Do not require the user to specify fields.

Only modify files when the user explicitly requests implement / fix / apply / refactor. By default, this skill is report-only.

Process

Phase 1: Inventory (first-pass leads)

This pass produces candidates, not findings. Treat counts as leads for deeper inspection in later phases. Do not report Phase 1 raw output as the final result.

Gather basic project information:

1. Tech stack — languages, frameworks, databases, infrastructure
2. Project size — lines of code, number of files, number of modules
3. Age & activity — git history depth, commit frequency, contributor count
4. Build & deploy — build system, CI/CD pipeline, deployment targets

Phase 2: Multi-Dimensional Assessment

Run a condensed version of each specialized audit:

Code Quality (from /code-quality-audit)

• Top 3-5 code smell categories
• Error handling consistency
• Naming and readability assessment
• Overall maintainability score

Architecture (from /architecture-review)

• Architectural pattern identification
• SOLID compliance summary
• Module coupling assessment
• Scalability concerns

Testing (from /testing-audit)

• Test coverage level (estimated from test file presence and density)
• Test quality assessment
• Testing strategy gaps
• CI integration status

Dependencies (from /dependency-audit)

• Dependency count and freshness
• Known vulnerability count
• License compatibility status
• Bloat/redundancy issues

Documentation (from /documentation-audit)

• README quality
• API documentation coverage
• Inline documentation quality
• Doc-code sync status

Performance (from /performance-audit)

• Obvious bottleneck patterns
• Resource management issues
• Caching strategy assessment

Phase 3: Risk Assessment

Identify project-level risks:

• Bus factor — how many people understand the critical paths?
• Technical debt — accumulated shortcuts and workarounds
• Dependency risk — critical dependencies that are unmaintained or vulnerable
• Scalability risk — architectural limits that will hit at growth
• Security risk — vulnerability surface area

Phase 4: Scoring

Rate each dimension on a 5-point scale:

Score	Meaning
5	Excellent — exemplary practices
4	Good — solid with minor issues
3	Fair — functional but has notable gaps
2	Poor — significant issues affecting development
1	Critical — fundamental problems requiring immediate attention

Output Format

# Project Health Report

## Project Overview
| Attribute | Value |
|-----------|-------|
| Tech Stack | [languages, frameworks] |
| Size | [~N lines, M files] |
| Age | [first commit date] |
| Contributors | [N active] |

## Health Dashboard

| Dimension | Score | Status | Key Finding |
|-----------|-------|--------|-------------|
| Code Quality | N/5 | 🟢/🟡/🔴 | ... |
| Architecture | N/5 | 🟢/🟡/🔴 | ... |
| Testing | N/5 | 🟢/🟡/🔴 | ... |
| Dependencies | N/5 | 🟢/🟡/🔴 | ... |
| Documentation | N/5 | 🟢/🟡/🔴 | ... |
| Performance | N/5 | 🟢/🟡/🔴 | ... |
| **Overall** | **N/5** | **🟢/🟡/🔴** | |

## Top Risks
1. [Risk + impact + likelihood]
2. ...
3. ...

## Top Recommendations
### Immediate (this week)
1. ...

### Short-term (this month)
1. ...

### Long-term (this quarter)
1. ...

## Detailed Findings

### Code Quality
[Summary of findings, top issues]

### Architecture
[Summary of findings, structural concerns]

### Testing
[Summary of findings, coverage gaps]

### Dependencies
[Summary of findings, update priorities]

### Documentation
[Summary of findings, gaps]

### Performance
[Summary of findings, bottlenecks]

## Conclusion
[1-2 paragraph executive summary: overall health, biggest risk, top priority action]

Notes

• This is a breadth-first report — for depth on any dimension, use the specialized audit skill
• Scores are relative assessments, not absolute metrics — a 3/5 for a startup MVP has different implications than for enterprise software
• The report is a snapshot — recommend periodic re-assessment (quarterly for active projects)
• For due diligence, combine this report with manual code review of critical paths