agentleFS
davekilleendavekilleen/Dex/.agents/skills/dex-doctor/SKILL.md

dex-doctor

Skill509 starsChanged 3 months agoMITView on GitHub

Whole-system checkup: verifies every Dex feature honestly (working/off/broken/couldn't-check), self-heals what's provably safe, guides the rest. Use when the user says 'is Dex healthy', 'something's broken', 'check my setup', 'run diagnostics'. Not for discovering unused *features*; use `dex-level-up`. Not for applying an update; use `dex-update`.

The file

Show its rules and text

We split this skill into the rules it gives an agent

31 rules. About 0 are common, 12 are distinctive, and 19 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈12

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 19

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Distinctive:

    After an update, migration, or machine change

    line 23
  2. Distinctive:

    Never hide "couldn't check": If a probe failed to run, say so prominently.

    line 30
  3. Very specific:

    If prepare_history_cleanup returns optional-tool-unavailable or optional-platform-unsupported, surface its guidance verbatim and stop.

    line 63
  4. Very specific:

    Call apply_history_cleanup only after the user types that string exactly.

    line 70
  5. Very specific:

    Read System/usage_log.md. Make this offer only when Health telemetry: pending or the line is missing:

    line 127
  6. Very specific:

    If the user explicitly says yes, replace the line with Health telemetry: opted-in (or add it under a ## Health Telemetry Consent heading …

    line 131
  7. Distinctive:

    Never read or change the separate analytics consent while handling this choice.

    line 134
  8. Very specific:

    If yes: run with --deep and merge results.

    line 145
  9. Very specific:

    Never describe a guided MCP safety check as an automatic block.

    line 161
  10. Very specific:

    Read the collector's top-level adoption object and render its groups in the exact order returned.

    line 172
  11. Distinctive:

    Keep that rephrasing to one plain-English line per group in this register: "Here's exactly what this changes for you" and, for recovery, "I …

    line 181
  12. Very specific:

    If adoption.verdict is OFF, say calmly that adoption reporting is off because no release catalog is installed.

    line 190
  13. Very specific:

    Never offer an action the engine does not expose.

    line 197
  14. Very specific:

    If completeness is UNKNOWN with partial: true, the installed baseline was still verified.

    line 228
  15. Very specific:

    If completeness is UNKNOWN without partial: true, render only the verdict and each incomplete_reasons code.

    line 232
  16. Very specific:

    When blocked_count is greater than zero, the first summary sentence must state that blocked count.

    line 234
  17. Distinctive:

    Always close this section with the exact line:

    line 246
  18. Distinctive:

    Do not say the record can't be trusted or was rejected.

    line 263
  19. Distinctive:

    Do not stop at "I can't tell you what you've changed." Offer the starting-version repair below.

    line 271
  20. Distinctive:

    Instead, give the user the exact command to run themselves in their own terminal window, from their vault folder:

    line 279
  21. Distinctive:

    When Doctor could not verify which version is installed at all, offer this starting-version repair instead of the dead-end above.

    line 292
  22. Distinctive:

    After the user reports back (or on the next Doctor run), re-read the deep assessment rather than assuming the outcome.

    line 310
  23. Very specific:

    When present, also render every recovery_actions record's phase, capsule_id, proposal_id, and exact action verbatim.

    line 325
  24. Very specific:

    When pending is true, render this guidance exactly:

    line 329
  25. Very specific:

    When any validation.status is not OK, say plainly: "The preserved evidence cannot be verified." Route the user to /dex-update guidance and …

    line 333
  26. Very specific:

    When pending_rebuild is true, say the protected rebuild is waiting to continue through /dex-update.

    line 337
  27. Very specific:

    Update System/usage_log.md per the usage-tracking convention.

    line 373
  28. Distinctive:

    If the run surfaced something that is a defect in Dex itself — not the user's setup — offer once, lightly: "I've patched this for you, but …

    line 376
  29. Distinctive:

    Fresh vault, onboarding incomplete: run anyway but expect many OFFs.

    line 384
  30. Very specific:

    If yes, invoke the /feedback skill with the repeat-BROKEN evidence.

    line 394
  31. Very specific:

    disable-model-invocation: true: only stops Claude from auto-invoking the skill.

    line 402

≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md
<!-- Generated from `.claude/skills/dex-doctor/SKILL.md` by `scripts/generate-agents-skills.py`. Do not edit. -->

/dex-doctor — Full System Checkup

Diagnose everything, heal what's safe, guide the user through the rest.

Purpose

One honest answer to "is my Dex actually working?" Built against the failure modes found in the July 2026 audit: checks that never ran, checks that probed an easier path than the real feature, "off" reported as "broken", and background jobs that died silently for months.

When to Run

  • User asks "is everything working?", "what's broken?", "check my setup"
  • Something feels off — features silently not happening
  • After an update, migration, or machine change
  • User invokes /dex-doctor directly

Cardinal rules

  1. Never report "off" as a problem. A feature the user never enabled is healthy. List it under "Off — that's fine", once, without nagging.
  2. Never hide "couldn't check". If a probe failed to run, say so prominently. An unknown presented as a pass is how watchdogs go blind.
  3. Never claim a heal worked without re-checking it.
  4. Heal conservatively. Tier 1 only automatically. Tier 2 only after an explicit yes, one item at a time. Tier 3 is always the user's hands. Never delete or overwrite user data; never touch credentials.

Credential scan mode

Credential scanning is local and read-only. Inspect the worktree, index, approved Git common directory and primary object database, reachable refs, stashes, tags, and only archives the user explicitly selects. Report opaque redacted finding IDs plus explicit inspected and uninspected scope categories; never print paths or matched values. Existing .mcp.json is scan/report-only and remains byte-identical.

Render migration, security, active .mcp.json residual, and optional history hygiene as separate deterministic states using render_credential_status; do not paraphrase it. Provider revoke/rotate is always user-driven. Replacement health is read-only and runs only after the user explicitly chooses a remediation check. History cleanup is optional privacy hygiene, never a current-danger warning or prerequisite. Use only a preinstalled git-filter-repo, after verified restrictive bundle backup and typed consent; never install it, push, or force-push. If migration capability fails, scanning and guidance remain available and Doctor names the failed capability with manual move/validation/rewind steps.

For an optional cleanup request, use the in-process contracts in core.utils.history_hygiene; never interpolate revoked values into a shell command. Run prepare_history_cleanup only when security is remediated, after the user explicitly chooses the exact refs/heads/*, refs/tags/*, or refs/stash/* refs and confirms either verified external-backup evidence or no-external-backup acknowledgement. Show the returned opaque transaction ID, selected refs, recovery-bundle evidence, and this exact consent string:

CLEAN OPTIONAL HISTORY <transaction-id>

If prepare_history_cleanup returns optional-tool-unavailable or optional-platform-unsupported, surface its guidance verbatim and stop; both are calm honest states, never a current-danger warning. optional-platform-unsupported means this operating system lacks the directory file-descriptor substrate the guided path needs (it runs on Linux, including WSL2 or a Linux container; macOS is not supported). No recovery state was created; offer the manual advanced path and note that history cleanup is optional privacy hygiene.

Call apply_history_cleanup only after the user types that string exactly. Preparation must have already produced and verified the mode-0700 transaction directory and mode-0600 history.bundle, objects.json, and manifest.json under System/.dex/adoption/history-backups/<transaction-id>/, while passing the 10 GiB shared-cap and 1 MiB free-space margin checks. Apply must preserve Git remote configuration and never fetch, push, force-push, install software, or call a provider.

The verified bundle and manifest cover every restorable ref, not only selected refs, and include restrictive config/index recovery artifacts plus opaque HEAD/index/tracked-worktree/remote state authority. Apply still passes only the explicitly selected refs to git-filter-repo. Any changed unselected branch, tag, stash, remote-tracking, replace, notes, backup, or other ref—or any HEAD, index, tracked-worktree, or remote-config collateral—must return recovery-required, never a clean result. Credential equality is memory-only; no value-derived digest or replacement file may be persisted.

Render the post-cleanup rescan result exactly as history-clean, history-cleanup-pending, or history-scope-unknown. If apply is interrupted or reports recovery-required, lead with “Do not push.” Preserve the bundle and call rewind_history_cleanup only through its exact-ref guard. If that guard refuses, give the returned manual verified-bundle recovery guidance; do not improvise ref updates. Always state that history rewind does not reverse provider rotation.

Retention is a separate explicit operation. preview_retention protects the newest history bundle and selects only verified bundles older than 90 days with two later successful release activations and valid backup posture. Call delete_retention_candidates only with the unchanged candidate tuple and exact-set SHA-256 that the user acknowledged. Never auto-delete or upload a recovery bundle.

Execution

Step 1: Run the collector (quick mode + safe auto-heals)

if [ -x "$VAULT_PATH/.venv/Scripts/python.exe" ]; then
  DEX_DOCTOR_PYTHON="$VAULT_PATH/.venv/Scripts/python.exe"
elif [ -x "$VAULT_PATH/.venv/bin/python" ]; then
  DEX_DOCTOR_PYTHON="$VAULT_PATH/.venv/bin/python"
else
  DEX_DOCTOR_PYTHON="python3"
fi
cd "$VAULT_PATH" && "$DEX_DOCTOR_PYTHON" core/utils/doctor.py --heal \
  || python3 core/utils/doctor.py --heal

This returns JSON on stdout: every check with a verdict (OK / OFF / BROKEN / UNKNOWN), any Tier-1 heals already applied, and an instruments block saying whether the doctor itself ran completely. While it runs, stderr prints Apply safe Tier-1 repairs before checking. then Checking this Dex install (read-only)..., then names each check as it starts (for example Checking core.drift...). JSON stays on stdout until the end. If a run sits still, the last named check is the one that is stuck. --verbose is not a flag.

If the collector itself fails to run: that IS the finding. Report it first, with the error, and continue with whatever manual checks you can do — do not present a partial picture as a full one.

Step 1a: Offer anonymous health telemetry once

Read System/usage_log.md. Make this offer only when **Health telemetry:** pending or the line is missing:

"Want to help catch bad releases early? Dex can send anonymous nightly health counts — no names, notes, or file contents, ever. Share them? (y/N)"

If the user explicitly says yes, replace the line with **Health telemetry:** opted-in (or add it under a ## Health Telemetry Consent heading when missing). If the user says no, skips, or accepts the default, record **Health telemetry:** opted-out. Once either decision is recorded, do not offer again. Never read or change the separate analytics consent while handling this choice.

Step 2: Offer the deep scan

Quick mode checks configuration, wiring, and background-job freshness. Deep mode additionally contacts live services (Granola API, Calendar via the configured source, enabled integrations). Ask:

"Quick check done. Want the deep scan too? It contacts your connected services (Granola, Calendar) to prove the real query paths work — takes ~30 seconds."

If yes: run with --deep and merge results.

Step 3: Render the report

Order: instruments first if anything failed, then BROKEN, then UNKNOWN, then OFF (one compact line each, labelled "off — that's fine"), then healthy collapsed to a single line ("✓ N checks healthy"). Fill every displayed count from the collector JSON — use the current report's summary values and checks array rather than a hardcoded quick or deep total, because the check registry can change.

For each BROKEN item: what it means for the user in one plain sentence (what stopped working, since when if known), then the fix path.

For Agent harness capabilities, use the saved receipt as the authority. Name every selected harness and keep the collector's four delivery labels exact: automatic, on_demand, guided, and unavailable. Explain on_demand as "available when asked". Never describe a guided MCP safety check as an automatic block; only a verified pre-tool interceptor earns that claim. If the check is OFF, calmly offer /setup to detect or choose harnesses. If it is BROKEN, do not guess from installed commands—use the returned repair.

For the Entity engine check, keep the rendering short and plain: say whether entity creation is working, off, or needs attention, include the contact/observation counts, and call out unresolved verification results or quarantined pages. Mention stale verification or a stale/missing People index as a follow-up signal.

Step 3a: Render the adoption section

Read the collector's top-level adoption object and render its groups in the exact order returned. It always contains these five groups: new-and-safe, needs-your-review, preserved-for-now, continue-or-recover, and receipts-and-rewind.

Authority fields are not prose. Render every item id, item version, action, status, verdict, count, transaction id, reason, path, and rewindable boolean verbatim. Never change an action or verdict, combine authority records, infer a missing record, or hide a zero count. The collector's surface line is the only field that may be rephrased. Keep that rephrasing to one plain-English line per group in this register: "Here's exactly what this changes for you" and, for recovery, "I found an interrupted update — resume or undo?"

needs-your-review normally contains conflict actions. If the deterministic planner returns action: unknown, keep that item and its reasons in this group verbatim, render the group's UNKNOWN verdict, and say the evidence needs rechecking; never silently drop it or translate it into a conflict.

If adoption.verdict is OFF, say calmly that adoption reporting is off because no release catalog is installed. If it is UNKNOWN, say what could not be verified and do not turn empty authority arrays into proposed actions. For ledger recovery, reproduce continue-or-recover.ledger.repair_command exactly; this is the existing python3 -m core.lifecycle.cli --vault-root <vault> rebuild-state command, not a prompt to improvise ledger repair.

Never offer an action the engine does not expose. An interrupted transaction may be described only from its returned transaction authority; do not call Transaction.resume while rendering Doctor. A receipt is rewindable only when the collector says rewindable: true and rewind_verdict: OK. Rewind only through the existing receipt-backed lifecycle flow: load that exact receipt, derive its exact acknowledgement with the rewind-acknowledgement helper in the Python lifecycle engine (core/lifecycle/engine.py), then perform the rewind through that same engine module's receipt-backed rewind function. There is no lifecycle rewind shell command, so do not invent one. If rewindable: false with rewind_verdict: OK, say the retained snapshot was pruned. If rewind_verdict: UNKNOWN, say the receipt, current bytes, committed journal, or snapshot could not be verified. In both cases, do not offer rewind.

Step 3b: Render the customization assessment

Deep reports include a top-level customization_assessment object. Render its four groups in the exact order returned: update-replaceable-location, update-untouched-location, needs-interpretation, and blocked.

This section follows the same authority/surface split as adoption. Reproduce every customization id, count, kind, group, verdict, path, release state, edge count, edge kind, confidence, completeness value, and exclusion verbatim. Do not merge records, hide zero counts, or promote an inferred edge to proved. Only each group's surface line may be rephrased, in plain English: "lives in a location Dex updates can replace" or "lives in a location updates leave alone."

CLAUDE.md differences are file-level evidence, never an orphan-line list. Do not tell the user to move any differing line into CLAUDE-custom.md. Show the modified file as needing review and route any comparison or resolution through /dex-update.

If completeness is UNKNOWN with partial: true, the installed baseline was still verified. Render the observed count and record list explicitly as partial, followed by every exclusion path, reason, and guidance line. Never present the observed count as the complete total, and do not offer a Capsule write until completeness is OK. If completeness is UNKNOWN without partial: true, render only the verdict and each incomplete_reasons code; do not state or infer a customization count. When blocked_count is greater than zero, the first summary sentence must state that blocked count.

Example register:

I found 3 customizations. One lives in a location Dex updates can replace, one lives in a location updates leave alone, and one is blocked by a missing folder reference.

cust-a1b2c3d4e5f6 · custom-script · .scripts/custom-plan.py · update-untouched-location · canonical-customization

Nothing has changed — this is an inventory only.

Always close this section with the exact line:

Nothing has changed — this is an inventory only.

Offering the release re-anchoring repair

<!-- FOUNDER COPY - DRAFT PENDING APPROVAL (re-anchoring design ruling 5): everything in this subsection is tester-visible guidance; the founder approves the verbatim wording before release. -->

The assessment's release_baseline object carries anchor_state:

  • verified — say the release anchor proves the vault's release-owned files; nothing to offer.
  • rejected because the record still names the previous version — this is the expected leftover after an update, not a broken record. Surface the probe's "needs refreshing" wording verbatim, including the one command. Do not say the record can't be trusted or was rejected.
  • rejected for any other reason — surface the probe's warning verbatim (it names the exact error) and offer the re-anchor flow below to regenerate the anchor.
  • absent with release-identity-unproved exclusions present — offer the re-anchor flow below. This is the guided repair those exclusions' guidance points at.
  • identity not VERIFIED (Doctor says it couldn't verify which version is installed) — this is the older-fork case, not the unproved-files case. Do not stop at "I can't tell you what you've changed." Offer the starting-version repair below. Never run it yourself.

The re-anchor flow is deliberately interactive: it asks for an explicit yes before it runs and again before it writes, and it refuses anything that is not a real terminal — so you cannot run it from here, and no flag or token substitutes for the person's yes. Never attempt to run it through Bash, never suggest piping answers into it, and never present its refusal as an error. Instead, give the user the exact command to run themselves in their own terminal window, from their vault folder:

Dex can't prove some of its own files came with your installed version. There's a guided repair that checks them against the official release record — it asks for your yes before it does anything. Open the Terminal app in your Dex vault folder and run:

python3 -m core.update.reanchor_cli

It shows you everything before saving anything, and if it can't prove your version from what's on this computer it stops without changing a thing.

When Doctor could not verify which version is installed at all, offer this starting-version repair instead of the dead-end above. Same rules: the person runs it in their own terminal; you never run it, never pipe answers into it, and never treat its refusal as an error:

Dex can't tell which version is installed in this vault, so the protected update stays closed. There's a guided repair that sets a starting version from the official record — it only writes the version paperwork, never your notes or the files you have changed. Open the Terminal app in your Dex vault folder and run:

python3 -m core.update.reanchor_cli --dry-run

That only looks, and lists every file it compared. If the list looks right, run the same command without --dry-run (add --baseline VERSION if you know the official version). It asks for your yes before it saves anything.

After the user reports back (or on the next Doctor run), re-read the deep assessment rather than assuming the outcome. If the flow said it couldn't prove the release from local sources, say plainly that the vault stays honestly unproved for now — do not route the user through /dex-update to fix it, and do not suggest editing the anchor file by hand.

Step 3c: Render the customization migration status

Deep reports include a top-level customization_migration_status object. Render every capsule_id, state, validation.status, validation.mismatches, pending, and truncated value verbatim. For each canonical Capsule, also render staging.proposals, every proposal's verification_verdict, the verification_verdicts summary, pending_rebuild, activation.state, activation.reason, activation_receipt_present, and rewindable verbatim. These are authority fields; only a short consequence or surface line may be rephrased. When present, also render every recovery_actions record's phase, capsule_id, proposal_id, and exact action verbatim. The action is already bound to recovery_token; never shorten, rebuild, or improvise it.

When pending is true, render this guidance exactly:

Continue via the registered Customization Migration MCP status tool / /dex-update; never edit capsule files directly.

When any validation.status is not OK, say plainly: "The preserved evidence cannot be verified." Route the user to /dex-update guidance and reproduce the returned mismatch authority. Do not invent a repair, search for capsule files, or edit them directly.

When pending_rebuild is true, say the protected rebuild is waiting to continue through /dex-update. A BLOCKED verification verdict stays blocked and an UNKNOWN verdict stays unknown. Say activation is receipt-backed only when activation_receipt_present is true, and say rewind is available only when rewindable is true. A recovery-required staging or activation state is a stop condition, not permission to repair Capsule files directly. For interrupted staging, activation, or rewind, offer only the exact phase-specific recovery_actions.action returned by Doctor after a fresh explicit acknowledgement.

Step 4: Heal, tiered

  • Tier 1 (already applied by the collector): report plainly — "Fixed automatically: recreated the missing Ideas folder."
  • Tier 2 (needs a yes): propose one at a time with the exact action and why it's safe: "Your changelog-checker background job is installed but not running. Want me to load it? (One command, reversible.)" Apply only on explicit yes, then re-run that check and confirm from the fresh result.
  • Tier 3 (user's hands): give exact steps and the right setup skill — e.g. "Granola needs an API key: run /granola-setup" / "macOS is blocking calendar access: System Settings → Privacy & Security → Calendars → enable your terminal app."

Step 5: Close with the four-bucket summary

🩺 Doctor's summary
   Fixed automatically: 2
   Needs your OK:       1  (waiting above)
   Needs your hands:    1  (steps above)
   Healthy:             N · Off (fine): M · Couldn't check: U

Here N, M, and U come directly from summary.ok, summary.off, and summary.unknown in the collector JSON. If everything is healthy: one line — "Everything checks out. N checks healthy, M features off by choice." No ceremony.

Step 6: Track usage (silent) and offer to report Dex bugs

Update System/usage_log.md per the usage-tracking convention. If learnings surfaced (e.g. a check that should exist but doesn't), suggest capturing via capture_idea.

If the run surfaced something that is a defect in Dex itself — not the user's setup — offer once, lightly: "I've patched this for you, but it looks like a bug in Dex itself. Want me to report it so it gets fixed properly for everyone?" If yes, invoke the /feedback skill; the Doctor findings you just gathered become the report's machine-state and investigation ingredients, so the user does nothing but approve.

Edge cases

  • Fresh vault, onboarding incomplete: run anyway but expect many OFFs; say "you're early in setup — this is normal" rather than alarming.
  • Non-macOS: launchd checks, and Apple Calendar checks, come back UNKNOWN with a note; don't present them as failures. Google Calendar is still checked when it is the configured calendar source.
  • User says "just fix everything": Tier 1 is already done; walk Tier 2 items one confirmation at a time anyway — batch-yes is how wrong heals happen. Tier 3 cannot be batched by definition.
  • Repeated BROKEN on the same item across runs: suggest reporting it — "this looks like a Dex bug, not your setup; want me to report it to the Dex team?" If yes, invoke the /feedback skill with the repeat-BROKEN evidence.

Turning a skill off

Claude Code's /skill-doctor reports unused skills and says where to turn them off. Match that path — do not invent another.

  • Project or personal skill Claude Code loaded (.claude/skills/, ~/.claude/skills/, .claude/commands/): open /skills, highlight the skill, press Space until it is off, then save. That writes skillOverrides in .claude/settings.local.json. You can write the same map by hand: {"skillOverrides": {"the-skill": "off"}}.
  • Do not write disabledSkills. Claude Code does not honor that key. A silent no-op is not a disable.
  • disable-model-invocation: true only stops Claude from auto-invoking the skill. It stays in the / menu unless skillOverrides is off.
  • Plugin skills (including Dex when installed as a plugin): turn them off from /plugin. skillOverrides does not apply.
  • User skills under .claude/skills-custom/: Claude Code does not load that folder, so they do not appear in /skills or /skill-doctor. Turning one off means stop asking for it, or remove that folder. Do not offer /{name} for it.

Related Commands

  • /granola-setup, /calendar-setup, /google-workspace-setup, /enable-semantic-search — Tier-3 fix paths
  • /dex-update — often the fix for package/version drift
  • /feedback — when a finding is a genuine Dex bug (not the user's setup), report it to the Dex team; the Doctor evidence becomes the report and the user only approves
  • /xray — understand what the doctor checked and why
  • /skills and /skill-doctor — Claude Code's own skill list and unused-skill report; disable guidance above must match them

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.