# Doctor

> Doctor

- Skill: `shwetank/doctor` (Agent Skill)
- Install (CLI): `npx skillmds@latest add shwetank/doctor`
- Raw SKILL.md: https://api.skillmd.com/api/skills/shwetank/doctor/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: shwetank (https://skillmd.com/u/shwetank)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/shwetank/doctor

---


# Doctor

Years of reflections, wins, and decision context live in one plaintext directory. This skill is the trust layer: it verifies that directory is healthy, catches corruption or drift early, and makes sure the user has a backup before they need one.

**Read-only by default.** Run every check without modifying anything, present findings, then offer fixes one at a time. Never bulk-fix without approval. Never delete user content — quarantine (rename with a `.orphaned` suffix or move to an `_attic/` subfolder) is the strongest action available, and only with approval.

## Locate the data

Root is `$BETTERSENSE_WORK_REFLECTIONS_HOME` if set, else `~/bettersense-work-reflections/`. If the directory doesn't exist at all, this isn't an error — the user just hasn't set up yet. Say so and point to `start`. Don't create anything.

## The checks

Run all of them; report as a single table (✅ / ⚠️ / ❌ per check).

### 1. Registry integrity

- `stakeholders.json` parses as JSON, has `version` and a `stakeholders` array.
- Every entry has `name`, `category`, and a slug; `category` is one of `managing-up`, `managing-across`, `managing-down`, `teams`.
- No duplicate slugs.

If the JSON is corrupt: report the parse error and offer to rebuild the registry by scanning the category directories (each stakeholder file's frontmatter has the authoritative name/category). Show the rebuilt version for approval before writing; save the corrupt original as `stakeholders.json.bak` first.

### 2. Registry ↔ files consistency

- **Missing files:** registry entries whose `<category>/<slug>.md` doesn't exist. Offer to create a stub or remove the entry.
- **Orphaned files:** `.md` files in category directories with no registry entry (common after hand-editing or a partial `stakeholder-manage` operation). Offer to re-register (preserves all reflection history) or quarantine.
- **Category mismatches:** file's frontmatter `category:` disagrees with the directory it sits in. The directory a reflect/due scan uses is the one that matters — offer to reconcile.

### 3. Layout drift

- Expected structure present where content implies it: `profile.md`, `self/`, `wins.md`, `strategy/`, `pulses/<area>/`, `team-charters/` — absence is fine (feature not used yet), but *misplacement* is flagged (e.g., a `pulse-2026-*.md` at the root, a stakeholder file outside any category dir).
- Pulse files match the `pulse-YYYY-MM-DD.md` naming that `pulse-synthesize` depends on; misnamed pulses are invisible to synthesis.
- Dated entries inside reflection files use real dates (a `## 2026-13-40` heading breaks due-ness math).

### 4. Privacy posture

- `.gitignore` exists in the root (created by `user-profile`; protects against the directory being swept into a repo). If missing, offer to write it (`*` + `!.gitignore`).
- Warn — don't block — if the directory is inside a cloud-synced folder (Dropbox/iCloud/OneDrive paths): syncing is a legitimate backup choice, but the user should be making it knowingly for career-sensitive plaintext.
- Confirm the root `README.md` privacy note exists; offer to write it if missing.

### 5. Backup status

The check most likely to matter someday:

- Is the directory a git repo with a remote? When did it last commit?
- If not: report the total size and age of the data ("214 entries across 9 files since 2026-01"), and offer one of:
  - **Snapshot:** `tar -czf ~/bettersense-backup-YYYY-MM-DD.tar.gz -C ~ bettersense-work-reflections` — one command, done.
  - **Versioned:** `git init` inside the directory + first commit, with a note that any remote must be **private** and that pushing sends the data to that host — the user's call, stated plainly.
- If a backup exists but is older than ~30 days of new entries, flag it.

## Output format

```
# bettersense doctor — YYYY-MM-DD

| Check | Status | Detail |
|---|---|---|
| Registry integrity      | ✅ | 7 stakeholders, valid JSON |
| Registry ↔ files        | ⚠️ | 1 orphaned file: managing-down/alex-kim.md |
| Layout                  | ✅ | |
| Privacy posture         | ✅ | .gitignore present; local-only path |
| Backup                  | ❌ | No backup found; 214 entries at risk |

## Proposed fixes (each needs your OK)
1. Re-register alex-kim.md into stakeholders.json (keeps all 12 entries)
2. Create tonight's snapshot: tar -czf ~/bettersense-backup-2026-07-11.tar.gz ...
```

Then walk fixes one at a time. End by suggesting a cadence: *"Run me again whenever something feels off, after hand-editing files, or before a machine migration."*

## Anti-patterns

- **Fixing silently.** Every write is announced first, even trivial ones. The user's trust in this directory is the product.
- **Alarmism.** An empty directory, an unused feature, or a missing optional file is not a warning. Only flag what would actually lose data or break a skill.
- **Backup nagging beyond once.** State the risk once per run, plainly, and respect the answer.

## Composition

- `start` / `user-profile` — where to send a user with no data directory yet
- `stakeholder-manage` — for intentional lifecycle changes doctor shouldn't guess at (archiving someone who left, renames)
- `weekly` — a healthy directory is what makes the weekly ritual's scans trustworthy