doctor

Doctor

Audit a project's Beislið workflow config end-to-end. Read <repo>/.beislid/workflow.md, probe each configured capability against the current host session, write a probe cache that orchestrators consume, and print a conversational audit.

Doctor is read-only on the repo and write-only on the cache. It does not modify workflow.md, install or remove skills, post comments, or invoke other orchestrators.

Pass --refresh to force a full re-probe even when the cache is fresh.

---

1. Precheck — git repo required

Run via Bash:

git rev-parse --show-toplevel

If exit code ≠ 0, hard-fail with this prose and stop:

🛑 Doctor needs a git repository. Beislið workflow config lives at <repo>/.beislid/workflow.md. Run git init here, make at least one commit, then re-run /doctor.

Capture the repo root path for later steps ($git_root).

Also verify there is at least one commit:

git rev-list --max-parents=0 HEAD | head -1

If exit ≠ 0 or output is empty, hard-fail with the same prose pattern adjusted to "make at least one commit." No path-hash fallback.

2. Read inputs

Read three files in this order:

1. $git_root/.beislid/workflow.md — the config under audit. If the Read fails (file does not exist), hard-fail with the two-clause prose and stop:

   🛑 No workflow.md found in .beislid/. If this is a fresh project, run /setup to create one. If you moved your config, restore it to <repo>/.beislid/workflow.md.

2. probe-semantics.md (relative to this SKILL.md, resolved through the per-skill symlink). If the Read fails (broken symlink), hard-fail:

   🛑 Doctor's probe-semantics aux is unreadable — likely a broken symlink. Re-run ~/Projects/beislid/install.sh to repair it.

3. workflow-md-format.md (relative to this SKILL.md, same pattern). Same broken-symlink message tailored to the format spec.

3. Validate the version stamp

The first line of workflow.md MUST match exactly:

<!-- beislid-workflow: v1 -->

If the first line is missing the stamp or shows a different version, hard-fail with prose that names what was found and offers two options:

⚠️ This workflow.md is <found> but doctor only knows v1. Update Beislið (current version is X.Y), or downgrade workflow.md by hand to v1 syntax. Doctor will not silently mis-parse.

Stop. Do not write a cache file.

4. Compute hashes

Two values are needed: the repo identity (used in the cache filename) and the workflow content hash (used to detect drift).

repo_hash=$(git rev-list --max-parents=0 HEAD | sort | head -c 12)
workflow_hash=$(git hash-object .beislid/workflow.md)

Sort makes multi-root histories deterministic. git hash-object is portable across Linux/macOS/BSD without depending on sha256sum.

State directory: ${BEISLID_STATE_DIR:-$HOME/.local/state/beislid}/probes/. Cache filename: <repo_hash>.json.

5. Load existing cache

Read the cache file if it exists. Three outcomes:

• No file — proceed to fresh full probe at step 7.
• JSON parse fails — treat as no file. Don't surface in default mode (only in verbose).
• schema field is anything other than 1 — treat as no file. Reprobe and write fresh at schema: 1. Don't surface.

If the file parses as schema: 1 and --refresh was NOT in the user's invocation:

• If workflow_hash in the cache matches the freshly computed hash AND (now - doctor_run_at) < ttl_hours from workflow.md or the cache (whichever is fresher), narrate that the cache is fresh and exit:

  🩺 Workflow check on <project_name>. Cache is fresh from <human time, e.g. "2 hours ago"> — nothing has changed since. Run /doctor --refresh to force a full re-probe.

  Stop. No re-write needed.

• Otherwise (hash mismatch or stale): full reprobe at step 7.

If --refresh is in the invocation, skip the freshness check entirely and reprobe.

<project_name> is the basename of $git_root: git rev-parse --show-toplevel | xargs basename.

6. Prepare the cache target

mkdir -p "${BEISLID_STATE_DIR:-$HOME/.local/state/beislid}/probes/"

Don't write the cache file yet — write at step 10 after probing completes.

7. Walk workflow.md section by section

Identify section headings (## <Topic>) and the typed-key fenced blocks within each. The format spec at workflow-md-format.md defines canonical section names and capability keys.

For each fenced block with info string beislid:<key>:

1. Duplicate check. If this <key> was already encountered earlier in the file, the first occurrence wins. Add an inline ⚠️ warning to the output narrating "found a second beislid:<key> block on line N — using the first one." Skip this block. Use grep -n '^\``beislid:' .beislid/workflow.md` to map blocks to lines.

2. Unknown key check. If <key> is not in the canonical keys list (per the format spec), add an inline 💭 note: "I don't know what beislid:<key> is — skipping. If this is a new capability, check the format spec." Continue.

3. Disabled-state check. If the section's prose says "Disabled for this project" (or similar) AND no fenced block follows, record status: disabled, probe_supported not set, no probe run.

4. Probe. Otherwise, dispatch on type (or the key's canonical probe kind per probe-semantics.md) and run the probe. Record the result in the cache schema below.

5. Parse failure. If the YAML inside the fenced block doesn't parse, run grep -n '^\``beislid:' .beislid/workflow.md` to find the block start line, add the YAML parse-error offset within the block to compute the file line, and surface in prose:

   ⚠️ The beislid:<key> block on line N doesn't parse as YAML — <one-line description of the parse error, e.g. "looks like a tab where there should be spaces.">

   Mark this capability as status: failed, probe_supported: true, reason: "YAML parse error at line N: <details>". Continue probing other capabilities.

8. Detect paired-half-missing and soft pairs

For each hard paired set (today: domain_expert.agent ↔ knowledge_store.path), check whether exactly one half is configured. If so, surface in prose (non-blocking):

⚠️ domain_expert.agent is set but knowledge_store.path isn't — domain capture/recording steps will skip where they require the pair.

Both halves probed independently and recorded in the cache; no special status — the warning is purely narrative.

Also check the PR review soft pair:

• pr_review_source alone is valid. Narrate it as read-only PR feedback handling; replies/re-request review will be manual if pr_review_update is absent or type: manual.
• pr_review_update without pr_review_source is a warning: update is configured without a source, so heard-chef can only use it after pasted PR feedback.
• pr_review_source.type: paste with pr_review_update configured is valid with a note: update is usable after pasted PR feedback.
• pr_review_update.type: manual is ok/no-probe; narrate it as manual-by-design, not missing.

9. Cache schema

Read doctor-templates.md for the canonical cache JSON example and field-level rules (status enum semantics, when probe_supported: false applies, when value and reason are omitted, etc.).

Always write the cache, including failures. Orchestrators need full state for lazy-probing decisions.

10. Write the cache

Marshal the schema to JSON and write to <state_dir>/probes/<repo_hash>.json. Overwrite atomically if possible.

If the write fails (permissions, disk full, etc.), surface in prose with the path:

⚠️ Couldn't write the probe cache to <path>: . The audit ran fine, but orchestrators won't see the cached results until you fix the underlying issue.

Continue to step 11 — the audit narration is still useful even without a cache write.

11. Print the conversational audit

Default mode (no BEISLID_VERBOSE) emits prose narration. Char budgets:

• Success path: ≤500 chars total.
• Failure path: ≤700 chars total. Use the three-clause shape: name what's wrong → name what's still working → name what to do.

Open with 🩺 **Workflow check on <project_name>.** then narrate what's configured, what was probed, and the cache status. Keep it conversational — no tables, no fixed-width columns, no checkmark grids.

Read doctor-templates.md for doctor's success and failure templates (worked examples). The three-clause failure shape (the rule), the 12-emoji palette, and the rules for placing inline ⚠️ and 💭 notes inside the narration come from output-templates.md.

12. Verbose mode

When BEISLID_VERBOSE=1 is set in the environment, append structured stamps under the prose, separated by ---. Stamps are diagnostic, not narrative.

Read output-templates.md for the universal verbose-stamps layout rule (--- divider; "augment, don't replace"). Read doctor-templates.md for doctor's per-capability stamp layout and the stamp-symbol legend (✓ / ✗ / —). Verbose mode is gated entirely on the env var; default mode shows only the prose, never the stamps.

---

Common mistakes

• Treating pr_review_source/pr_review_update as unknown keys. They are Phase 3 workflow.md keys. Source-only is valid; update-only is a warning; manual/paste variants are configured no-op probes.
• Writing a cache file before validation completes. All hard-fail conditions (missing workflow.md, missing git repo, version mismatch, broken aux symlinks) exit before any cache write.
• Using line numbers from Read tool output. That formatting differs across hosts. Always compute line numbers via grep -n '^\``beislid:' .beislid/workflow.md` plus the YAML parse offset.
• Re-probing inside the same run. Each capability is probed once per /doctor invocation. Stale cache invalidates the whole file; doctor doesn't reprobe per-capability mid-flight.
• Silently using a different repo-hash on multi-root histories. git rev-list --max-parents=0 HEAD without sort gives non-deterministic order across runs. Always pipe through sort before truncating.
• Skipping the version-stamp check. Doctor never silently mis-parses an unknown workflow.md version.

Key principles

• Read-only on workflow.md, write-only on cache. Doctor never edits the user's config.
• Conversational over CI-style. Prose narration with the 12-emoji palette. No tables or fixed-width columns in default mode.
• Hard-fail loudly when assumptions break. No git repo, no commits, no workflow.md, broken aux symlinks, unknown version stamp — all stop with a clear pointer to the fix.
• Verbose mode adds, never replaces. Stamps go under the prose, separated by ---. Default-mode users never see them.