Health Check — Project Health Assessment
Run a comprehensive health assessment across all project dimensions. Report findings and flag items that need attention. Done when the report below is presented, every row carrying a status, and the offer to act on it is answered or defaulted.
Checks (run as many in parallel as possible)
The build, test and lint commands come from docs/context/CONVENTIONS.md. Where it names none, use the ones the project's own manifest or build file defines (such as package.json scripts or a Makefile), and mark the row ⚠️ with "no command found" when there is none, so a missing command never reads as a pass.
1. Build Status
[build command from CONVENTIONS.md]
Pass: Build completes without errors or warnings Fail: Note the error/warning output
2. Test Status
[test command from CONVENTIONS.md]
Pass: All tests pass, note total count Fail: List failing tests by name
3. Lint Status
[lint command from CONVENTIONS.md]
Pass: No lint errors or warnings Fail: Note error count and most common categories
4. Dependency Health
# Check for outdated dependencies (npm/yarn/pip/etc.)
[outdated command]
# Check for known vulnerabilities
[audit command]
Pass: No critical/high vulnerabilities, deps reasonably current Fail: List critical vulnerabilities and severely outdated deps
5. Convention Compliance
Read docs/context/CONVENTIONS.md. Spot-check the 5 most recently changed files against the conventions. Note any violations.
6. Documentation Freshness
Check if key docs are up to date:
# When were context docs last modified?
ls -la docs/context/STATUS.md docs/context/GOALS.md docs/context/CONVENTIONS.md 2>/dev/null
# When was the Session Continuity section last updated?
grep "Last session:" docs/context/STATUS.md
Pass: Docs updated within last 7 days Warning: Docs older than 7 days Fail: Key docs missing
7. Backlog Health
Read BACKLOG.md:
- Count items in Inbox (untriaged)
- Count items in Triaged
- Flag any P0/critical items not being worked on
8. Git Health
# Uncommitted changes
git status --short
# Unpushed commits
git log @{u}..HEAD --oneline 2>/dev/null
# Stale branches (master, or the remote's default, where the project has no main)
git branch --merged main | grep -v main | grep -v '*'
Report Format
## Project Health Report
| Area | Status | Details |
|------|--------|---------|
| Build | ✅/⚠️/❌ | [brief note] |
| Tests | ✅/⚠️/❌ | [X passing, Y failing] |
| Lint | ✅/⚠️/❌ | [error count] |
| Dependencies | ✅/⚠️/❌ | [vulns/outdated count] |
| Conventions | ✅/⚠️/❌ | [violations found] |
| Documentation | ✅/⚠️/❌ | [freshness] |
| Backlog | ✅/⚠️/❌ | [untriaged count] |
| Git | ✅/⚠️/❌ | [uncommitted/unpushed] |
### Items Needing Attention
1. [Most critical finding]
2. [Second finding]
3. [Third finding]
### Recommended Next Actions
1. [First action]
2. [Second action]
Present the report, then offer to address the findings.
Asking the user. Ask with your question tool if you have one, offering at most three options; otherwise ask in plain text with a numbered list. In a headless or unattended run nobody will answer: take the default named below, say so in your output, and log it in the run state's decisions if there is a run state.
Options: 1. address the items needing attention, most critical first; 2. address only the items the user picks; 3. leave everything as it is. Default when nobody answers: option 3, because a health check reports and changes nothing unasked.