| name | project-health |
| description | Unified project health review for docs, workflow, and operational readiness. Use this when the user says "project health", "is this project healthy". Produces a decision-driven health report with optional fixes, always asking for numbered confirmation (1,2,3,4, all, skip) before each action.
|
Project Health
Run a full health pass across project documentation, workflows, and operational signals.
Output style:
- Show findings first (highest risk first)
- For each phase, ask what to run:
1, 2, 1,3, all, or skip
- Never apply edits until user confirms
Phase 0 — Scope Confirmation
Ask:
- Target scope: docs-only, ops-only, or full health
- Mode: audit-only or audit+apply
- Time window for freshness checks: 7 / 30 / 90 days
If user already specified these, proceed directly.
Phase 1 — Documentation Health
Sub-tasks:
- Link integrity in
SESSION.md, INSIGHTS.md, CLAUDE.md
.reference/ metadata completeness (Purpose, When to use, Source of truth, Owner, Confidence, Last reviewed)- Freshness drift (
Last reviewed vs chosen time window)
INSIGHTS.md status quality (done/open/stale mix and archive hygiene)TODO.md structure compliance (open tasks format and done history consistency)
Prompt:
Which documentation checks should run?
1,2,3,4,5 | all | skip
Report:
- Critical issues
- Warnings
- Healthy checks
- Suggested fixes (no edits yet)
Phase 2 — Workflow Health
Sub-tasks:
- Skill naming consistency (
project-* prefix where intended)
- Skill trigger clarity (description includes clear "Use when" trigger phrases)
- Skill drift check (overlapping scopes, duplicate responsibilities)
- CLAUDE.md alignment (local vs global guidance conflicts)
- Recurrence hygiene (monthly/quarterly tasks represented in TODO or skill checklists)
Prompt:
Which workflow checks should run?
1,2,3,4,5 | all | skip
Report:
- Conflicts/duplicates found
- Missing triggers or weak descriptions
- Recommended consolidation actions
Phase 3 — Operational Readiness (Project-level)
Sub-tasks:
- Verify runbook discoverability (
.reference/INDEX.md matches actual files)
- Verify incident learnings promoted (
SESSION.md key learnings reflected in CLAUDE/reference where appropriate)
- Verify release guardrails documented (confirm before release, change-control rules, rollback notes)
- Verify monitoring hooks exist (health scripts/aliases documented and discoverable)
Prompt:
Which readiness checks should run?
1,2,3,4 | all | skip
Report:
- Missing operational safeguards
- Gaps likely to cause repeat incidents
- Promotion candidates (.ai-notes -> .reference)
Phase 4 — Advanced Checks (Optional)
Use this phase when the user wants deeper project-health signals.
Sub-tasks:
- Operational health checks
- Stale credential detection
- Change-branch audit
- Skill usage metrics
- Deployment health
- Memory/notes system health
- Shell alias validation
Prompt:
Which advanced checks should run?
1,2,3,4,5,6,7 | 1,3,6 | all | skip
Execution guidance:
Task 1 — Operational health checks (Medium)
- Run live system checks when server scope is enabled:
- Disk space
- Database lag or queue depth (if applicable)
- Cache memory usage
- Runtime cache fullness (if applicable)
- Running scheduled jobs / scheduler health
- If server scope is disabled, report as skipped with reason.
Task 2 — Stale credential detection (Low)
- Scan shell profile files,
.env*, and memory files for likely credential keys.
- Flag secrets that appear stale (>90 days) using file timestamps/history signals.
- Never print secret values; only print key names and locations.
Task 3 — Change-branch audit (Low)
- List stale branches (>30 days since last commit) when VCS is present.
- Separate local and remote branches.
- Recommend cleanup candidates without deleting anything.
Task 4 — Skill usage metrics (Low)
- Check recent
SESSION.md entries for skill mentions.
- Report skill usage frequency and underused skills.
- Suggest consolidation where overlap is high.
Task 5 — Release health (Medium)
- Check latest release traces:
- Recent push status
- Cache purge evidence (if expected)
- Hook/checkpoint success notes
- Rollback indicators
- Output confidence as Confirmed / Partial / Unknown.
Task 6 — Memory/notes system health (Low)
- If a memory system is configured, verify expected memory scope structure and usage.
- If no memory system is configured in this environment, mark as skipped: "not configured".
- Optionally check project-local notes hygiene (
NOTES.md, .ai-notes/, .reference/) instead.
- Flag orphaned or duplicate notes where applicable.
Task 7 — Shell alias validation (Low)
- Validate key aliases in the shell aliases file resolve to real commands/scripts.
- Report broken aliases and likely fix paths.
Report per selected task:
### [Task N] [Name]
Status: ✅ Healthy | ⚠️ Needs attention | ❌ Failing | ⏭️ Skipped
Findings:
- ...
Recommended action:
- ...
Phase 5 — Prioritized Health Score
Build a simple scorecard:
- Docs Health: 0-100
- Workflow Health: 0-100
- Operational Readiness: 0-100
- Overall: weighted average
Severity buckets:
- P1: Breaks workflow or causes risky decisions
- P2: Degrades maintainability
- P3: Cosmetic or low-risk drift
Also provide:
- Top 3 actions with highest impact
- Estimated effort per action (S/M/L)
Phase 6 — Apply Fixes (Only on Confirmation)
For each selected fix category, ask explicitly before editing:
- Link fixes
- Metadata updates
- INSIGHTS archival updates
- TODO structure fixes
- CLAUDE.md gap additions
- Skill description/trigger improvements
- Advanced checks remediation (where safe and approved)
Prompt:
Which fix categories should be applied?
1,2,3,4,5,6,7 | all | skip
After applying, provide:
- Files changed
- What changed and why
- Residual risks
Completion Criteria
A health run is complete when:
- Requested checks are executed and reported
- Findings are severity-ranked
- User-approved fixes are applied
- Final summary includes residual risks and next review cadence
- Advanced-check findings are either remediated or explicitly deferred
Suggested Cadence
- Weekly: docs + workflow quick pass
- Monthly: full
project-health run
- Quarterly: deep archive and structural cleanup
Related Skills
Use with:
project-insights for focused INSIGHTS triageproject-cleanup for heavy cleanup/application workflow
Use project-health first when unsure where drift exists.
