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.

1. CI first. A broken pipeline blocks everything else; it must be visible up front.
2. 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.

1. Consolidated report. Accumulate each step's findings into a single summary table

at the end so the user has one artifact to act on.

1. 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.