Skip to content

egregore-labs/egregore / .claude/skills/checkup

checkup

Verified

Run diagnostics on an Egregore environment and render a health report, repairing safe local Runtime problems when possible. Use for /checkup, a health check, or when something is broken and the root cause is unclear.

FileKindSize
SKILL.mdskill md7.7 KB
---
name: checkup
description: "Run diagnostics on an Egregore environment and render a health report, repairing safe local Runtime problems when possible. Use for /checkup, a health check, or when something is broken and the root cause is unclear."
---

# Egregore checkup

Diagnose the Egregore Runtime first. Treat canonical Markdown and its
instance-owned Local Retriever as the product baseline. Graph, control-plane,
and notification probes are explicit Connected integrations; their failure
must never make canonical Local Runtime state look unavailable.

## When to invoke

Run diagnostics on an Egregore environment and render a health report, repairing safe local Runtime problems when possible. Use for /checkup, a health check, or when something is broken and the root cause is unclear.

## Procedure

Detect mode without attempting a network call:

```bash
bash bin/config-get.sh mode
```

Use the printed value as `{mode}`; quote it in single quotes when you use it in a command, and write any single quote inside the value as `'\''`. If it prints `local`, skip Connected
integrations; if it prints `connected`, include them after the local checks.

Run three sequential batches. Parallelize only within a batch.

1. Runtime and local configuration.
2. Connected integrations, only when `{mode}` is `connected`.
3. Workspace and Git checks.

Never run Connected network probes beside local checks; a timeout must not
cancel or obscure the Runtime result.

## Batch 1: canonical Runtime

Read the one typed Runtime health surface as JSON:

```bash
EGREGORE_ROOT="$PWD" PYTHONSAFEPATH=1 PYTHONPATH="$PWD${PYTHONPATH:+:$PYTHONPATH}" \
  python3 -m egregore_runtime.harness_cli status --json
```

Do not invoke `qmd`, inspect QMD process tables, guess ports, or read another
instance's runtime directory. The adapter owns those mechanics. Interpret the
returned fields as follows:

- `canonical_state_ready` — foundational. Fail only when canonical memory is
  unavailable.
- `adapter=qmd-local`, `collection`, and `index_path` — the resolved
  instance-owned Local Retriever. Display these without exposing another
  instance or deriving ownership yourself.
- `runtime_state`, `runtime_pid`, and `runtime_endpoint` — owned worker
  readiness. `semantic_ready` is healthy; `semantic_index_building` is a
  warning with lexical fallback; `runtime_unavailable` is repairable.
- `bm25_ready` — local keyword readiness. Warn when false.
- `semantic_ready` and `embedding_state` — semantic readiness. A warming or
  missing model is degraded, not canonical data loss.
- `index_spec_version`, `index_revision`, and `source_revision` — freshness.
  Report drift; never repair it by editing index files.
- `warnings` — show concise, redacted messages.

Also validate `egregore.json`, the canonical `memory` link/repository, and the
mode-appropriate key names in `.env`. Never print secret values. Local mode
requires no control-plane key.

If the Runtime worker or indexes are unavailable while canonical memory is
ready, run the safe Runtime lifecycle adapter once:

```bash
bash bin/search.sh start
```

Then re-read Runtime health once. This starts or reuses only the worker owned
by this Egregore instance and schedules semantic warming behind the adapter.

## Batch 2: Connected integrations

Skip this batch completely in local mode. In connected mode, label every row
as an integration, keep it outside the foundational Runtime verdict, and run:

```bash
timeout 10 bash bin/graph-projection.sh verify --enable 2>&1; echo "EXIT:$?"
timeout 10 bash bin/notification.sh status 2>&1; echo "EXIT:$?"
```

- **Hosted relationship index** — pass when the gateway accepts the
  configured credentials and the projection is reachable. Offline, auth, or
  stale projection results are Connected warnings; canonical Markdown remains
  authoritative.
- **Notification adapter** — read the sanitized Runtime `status` field. Treat
  `ok` (connected) or `configured` (local) as healthy. Telegram is optional
  and never part of Runtime readiness.

Do not auto-replace API keys, repair graph state, publish, or send a
notification. Report the exact integration boundary that failed.

## Batch 3: workspace

Check locally:

- the configured base branch exists and compare it with `origin/<base>` only
  when an origin is already configured;
- the current worktree and memory repository are clean or clearly report their
  dirty-file counts;
- the framework version is readable locally. Do not fetch merely to render a
  health report;
- the shell launcher points at this instance when a launcher is configured.

Never mutate Git, canonical memory, or framework files during diagnosis.
Offer `$pull`, `$update`, or `$setup` as the next Egregore action when relevant;
do not tell the user to construct repair commands manually.

## Rendering

Render one compact diagnostic box. In connected mode add a separate
`CONNECTED INTEGRATIONS` section after `RUNTIME`; in local mode omit it.

```text
┌──────────────────────────────────────────────────────────────────────┐
│  ⊕ CHECKUP                                          {date}         │
├──────────────────────────────────────────────────────────────────────┤
│  CONFIG                                                              │
│  ✓ Instance — {org} ({mode})                                        │
│                                                                      │
│  RUNTIME                                                             │
│  ✓ Canonical memory — ready · source {source_revision}              │
│  ✓ Local Retriever — qmd-local {adapter_version} · owned            │
│  ⚠ Semantic index — warming · lexical fallback ready                │
│  ✓ Worker — pid {pid} · {endpoint}                                  │
│                                                                      │
│  CONNECTED INTEGRATIONS                                              │
│  ⚠ Hosted relationship index — offline · local memory ready         │
│  ✓ Telegram — connected                                             │
│                                                                      │
│  WORKSPACE                                                           │
│  ✓ Memory repository — clean                                        │
│  ✓ Git — {base} synced                                               │
├──────────────────────────────────────────────────────────────────────┤
│  Runtime ready · {warnings} warnings · integrations {state}         │
└──────────────────────────────────────────────────────────────────────┘
```

Use `✓`, `⚠`, and `✗` for pass, degraded, and unavailable. State the Runtime
verdict independently from Connected integration health. After a safe Runtime
repair, append only the rechecked result.

## Rules

- Never expose raw JSON, tokens, environment values, or unformatted probes.
- Never use Graph or a control-plane response as canonical health authority.
- Never call QMD directly; instance ownership belongs to Egregore Runtime.
- Never send, publish, commit, pull, or push as part of checkup.
- Emit telemetry only through the normal command wrapper, best-effort.
slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack."Stars: 198kUpdated Claude CodeCodexVerifiedInstall
ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report.Stars: 194kUpdated Claude CodeCodexVerifiedInstall
ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt.Stars: 194kUpdated Claude CodeCodexVerifiedInstall