health-check

name

health-check

description

Periodic repo health check orchestrator. Runs four maintenance skills in sequence — CI status check (/diagnose-ci), CLAUDE.md staleness audit (/audit-claude-md), documentation accuracy audit (/audit-docs), and Obsidian Vault sync (/obsidian-vault-sync if a vault exists) — pausing for approval between steps and producing a single consolidated findings report at the end. Global and project-agnostic. Trigger when the user says "health check", "health-check", "repo health", "check repo health", "repo maintenance", "run a health check", "audit the repo", "check everything", "periodic maintenance", or "check if everything is up to date". SKIP when the user only wants to run one specific audit (send them directly to the relevant skill).

Repo health check (maintenance orchestrator)

Project-agnostic, global skill. It runs the four periodic maintenance checks every active repo needs — CI health, context docs, user-facing docs, and knowledge base — in a single guided pass, accumulating a consolidated findings list and pausing for approval at each step. It is the maintenance complement to /bootstrap-project (which sets a repo up); this skill keeps it healthy over time.

The sequence: /diagnose-ci (CI green?) → /audit-claude-md (context docs fresh?) → /audit-docs (user-facing docs accurate?) → /obsidian-vault-sync (vault in sync? — if one exists).

Operating principles

1. Orchestrate, don't reimplement. Each step is handled by its own skill; this skill sequences them, carries findings forward, and produces the final summary. Never duplicate a step's logic.
2. CI first. A broken pipeline blocks everything else; it must be visible up front.
3. Approval gate per step. Pause after each step; confirm before moving to the next. The user can skip any step. Never run the chain unattended.
4. Consolidated report. Accumulate each step's findings into a single summary table at the end so the user has one artifact to act on.
5. Restraint. Do not apply fixes automatically; let each delegated skill govern that. This orchestrator's job is triage and sequencing, not fixing.

Procedure

0. Orient (once, up front)

• Confirm the working directory is the repo root the user intends.
• Detect vault: check for <repo>/.obsidian-vault/. Note whether the vault step will run.
• Show the planned sequence (CI → CLAUDE.md → Docs → Vault) and let the user drop any steps before starting.

1. CI health → /diagnose-ci

• Check CI status first: run gh run list --branch $(git rev-parse --abbrev-ref HEAD) --status completed --limit 3 --json conclusion,workflowName,headBranch,url to get a quick read.
  • If all green: report "CI is passing" and offer to skip the full diagnose-ci.
  • If any failing: invoke /diagnose-ci to fetch logs, classify the failure, and propose a fix. Record the diagnosis in the consolidated findings.
• If gh is not installed or not authenticated: note this, skip to step 2.
• Pause for approval before continuing.

2. CLAUDE.md audit → /audit-claude-md

• Invoke the audit-claude-md skill to score all CLAUDE.md files for staleness and surface coverage gaps. Let it produce its ranked findings list.
• Record the count of stale / missing / orphaned files in the consolidated findings.
• Pause for approval before continuing.

3. Documentation audit → /audit-docs

• Invoke the audit-docs skill to extract and verify claims across all hand-authored docs, ranked by importance tier.
• Record the count of findings by severity in the consolidated findings.
• Pause for approval before continuing.

4. Obsidian Vault sync → /obsidian-vault-sync (if vault exists)

• If a vault was detected in step 0: invoke obsidian-vault-sync with --all to run all 11 checks.
• Record the count of high / medium / low findings in the consolidated findings.
• If no vault was detected: skip this step silently (no need to flag it).
• Pause for approval before continuing.

5. Consolidated report

Present a single summary table of all findings across every step:

Step              | Status   | Findings
------------------|----------|------------------------------------------
CI                | ✓ Green  | No failures  (or ✗ N jobs failing)
CLAUDE.md audit   | ✗ Issues | N stale, M missing, P orphaned
Docs audit        | ✗ Issues | N wrong, M missing, P unclear
Vault sync        | ✓ Clean  | 0 findings  (or N high / M medium / P low)

Then list any open action items that were not resolved during the steps (e.g., a diagnose-ci fix that was deferred, a CLAUDE.md that needs /init, a doc fix pending approval). Offer to save this report to .claude/health-check-<date>.md for tracking.

Guardrails

• Thin orchestrator only: delegate to each skill's logic; never duplicate it.
• CI step is first and skippable; never block the audit steps on CI resolution.
• Approval gate at every step; the user may skip any. Never run the chain unattended.
• Do not auto-apply fixes from any step — that is each delegated skill's decision gate.
• If a delegated skill is unavailable, say so explicitly rather than silently skipping.
• If gh is absent or unauthenticated, skip step 1 gracefully — don't abort the run.
• Never fabricate findings — base the consolidated report solely on what each skill actually returned.