project-health

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:

1. Target scope: docs-only, ops-only, or full health
2. Mode: audit-only or audit+apply
3. Time window for freshness checks: 7 / 30 / 90 days

If user already specified these, proceed directly.

---

Phase 1 — Documentation Health

Sub-tasks:

1. Link integrity in SESSION.md, INSIGHTS.md, CLAUDE.md
2. .reference/ metadata completeness (Purpose, When to use, Source of truth, Owner, Confidence, Last reviewed)
3. Freshness drift (Last reviewed vs chosen time window)
4. INSIGHTS.md status quality (done/open/stale mix and archive hygiene)
5. 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:

1. Skill naming consistency (project-* prefix where intended)
2. Skill trigger clarity (description includes clear "Use when" trigger phrases)
3. Skill drift check (overlapping scopes, duplicate responsibilities)
4. CLAUDE.md alignment (local vs global guidance conflicts)
5. 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:

1. Verify runbook discoverability (.reference/INDEX.md matches actual files)
2. Verify incident learnings promoted (SESSION.md key learnings reflected in CLAUDE/reference where appropriate)
3. Verify release guardrails documented (confirm before release, change-control rules, rollback notes)
4. 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:

1. Operational health checks
2. Stale credential detection
3. Change-branch audit
4. Skill usage metrics
5. Deployment health
6. Memory/notes system health
7. 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:

1. Link fixes
2. Metadata updates
3. INSIGHTS archival updates
4. TODO structure fixes
5. CLAUDE.md gap additions
6. Skill description/trigger improvements
7. 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:

1. Requested checks are executed and reported
2. Findings are severity-ranked
3. User-approved fixes are applied
4. Final summary includes residual risks and next review cadence
5. 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 triage
• project-cleanup for heavy cleanup/application workflow

Use project-health first when unsure where drift exists.