oat-doctor

name	oat-doctor
version	1.0.2
description	Use when you need to diagnose your OAT setup, check for outdated skills, identify misconfigurations, or get a summary of installed tools and config. Runs health checks and recommends corrective actions.
argument-hint	[--summary]
disable-model-invocation	true
user-invocable	true
allowed-tools	Read, Bash, Glob, Grep, AskUserQuestion

OAT Doctor

Diagnose your OAT setup at both project and user levels. Checks for skill updates, identifies misconfigurations, summarizes what's installed, and recommends corrective actions.

Prerequisites

• OAT CLI installed and available as oat in PATH.
• At least one oat init has been run (project or user level).

Mode Assertion

OAT MODE: Doctor (Diagnostic)

Purpose: Inspect OAT setup and report findings with actionable fix commands. Never modify files or configuration.

BLOCKED Activities:

• No editing configuration files, skills, or templates.
• No running oat init, oat sync, oat tools update, or any mutating commands.
• No creating, modifying, or deleting any files.

ALLOWED Activities:

• Running oat CLI commands with --json flag for read-only data gathering.
• Reading files to inspect configuration state.
• Reading ~/.oat/docs/ for config key explanations.
• Presenting diagnostic findings and recommendations to the user.

Self-Correction Protocol: If you catch yourself:

• About to run a mutating command → STOP and present it as a recommendation instead.
• Editing a file to fix a problem → STOP and tell the user the fix command.

Recovery:

1. Return to read-only diagnostic mode.
2. Present the needed fix as an actionable recommendation.

Progress Indicators (User-Facing)

Print a phase banner once at start:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ OAT ▸ DOCTOR ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

Check Mode (default)

• [1/4] Gathering installed tools…
• [2/4] Checking for outdated skills…
• [3/4] Inspecting configuration…
• [4/4] Reporting findings…

Summary Mode (--summary)

• [1/6] Gathering installed tools…
• [2/6] Checking for outdated skills…
• [3/6] Inspecting configuration…
• [4/6] Discovering available packs…
• [5/6] Checking sync status…
• [6/6] Building dashboard…

Process

Step 0: Determine Mode

Read $ARGUMENTS:

• If $ARGUMENTS contains --summary → summary mode
• Otherwise → check mode (default)

Step 1: Gather Installed Tools

TOOLS_JSON=$(oat tools list --json --scope all 2>/dev/null || echo '{"tools":[]}')

Parse the JSON output. Each tool has: name, type (skill/agent), scope (project/user), version, bundledVersion, pack (core/docs/ideas/workflows/utility/project-management/research/custom), status (current/outdated/newer/not-bundled).

Step 2: Check for Outdated Skills

OUTDATED_JSON=$(oat tools outdated --json --scope all 2>/dev/null || echo '{"tools":[]}')

Parse the JSON output. Each entry has name, version (installed), bundledVersion (available), pack, scope.

Step 3: Inspect Configuration

CONFIG_JSON=$(oat config list --json 2>/dev/null || echo '{"configs":[]}')

Check for issues:

• Stale activeProject pointer: If activeProject is set, verify the directory exists. If not, warn.
• Stale activeIdea pointer: If activeIdea is set, verify the directory exists. If not, warn.
• Missing projects.root: If not configured and no default exists, warn.

For config key explanations, read from the bundled docs at ~/.oat/docs/. Check reference/file-locations.md and guide/cli-reference.md for authoritative descriptions.

Step 4: Check Mode — Report Findings

If in check mode, output a terse, brew doctor-style checklist.

Format:

Your OAT setup has {N} warning(s).

⚠  {N} outdated skill(s)
   Run: oat tools update --scope {scope}

⚠  Stale activeProject pointer: {path} does not exist
   Run: oat config set activeProject ""

⚠  Stale activeIdea pointer: {path} does not exist
   Run: oat config set activeIdea ""

⚠  {pack} pack not installed at {scope} scope
   Run: oat init tools

If no warnings:

Your OAT setup looks good. No issues found.

Stop here for check mode.

Step 5: Summary Mode — Discover Available Packs

For summary mode, compare installed skills against the full manifest to identify available-but-uninstalled packs and skills.

Bundled skill manifest (source of truth):

Core pack skills:

• oat-docs, oat-doctor

Workflow pack skills:

• oat-project-capture, oat-project-clear-active, oat-project-complete
• oat-project-design, oat-project-discover, oat-project-document
• oat-project-implement, oat-project-import-plan, oat-project-new
• oat-project-open, oat-project-plan, oat-project-plan-writing
• oat-project-pr-final, oat-project-pr-progress, oat-project-progress
• oat-project-promote-spec-driven, oat-project-quick-start
• oat-project-reconcile, oat-project-revise, oat-project-review-provide
• oat-project-review-receive, oat-project-review-receive-remote
• oat-project-spec, oat-project-summary
• oat-repo-knowledge-index, oat-worktree-bootstrap, oat-worktree-bootstrap-auto

Ideas pack skills:

• oat-idea-new, oat-idea-ideate, oat-idea-summarize, oat-idea-scratchpad

Docs pack skills:

• oat-agent-instructions-analyze, oat-agent-instructions-apply
• oat-docs-analyze, oat-docs-apply

Utility pack skills:

• create-agnostic-skill
• oat-repo-maintainability-review, oat-review-provide
• oat-review-receive, oat-review-receive-remote

Project management pack skills:

• oat-pjm-add-backlog-item, oat-pjm-update-repo-reference
• oat-pjm-review-backlog

Research pack skills:

• analyze, compare, deep-research
• skeptic, synthesize

For each pack, determine:

• Installed: all pack skills found in installed tools list
• Partially installed: some but not all pack skills found
• Not installed: no pack skills found
• Missing skills: specific skills in the manifest but not in installed list (highlights newly-added skills after CLI upgrades)

Step 6: Summary Mode — Check Sync Status

If in a project directory (.oat/ exists):

SYNC_STATUS=$(oat sync --dry-run --json --scope project 2>/dev/null || echo '{}')

Report whether provider views are in sync or have pending changes.

Step 7: Summary Mode — Build Dashboard

Output a full dashboard:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
OAT ▸ DOCTOR SUMMARY
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

## Installed Packs

| Pack      | Scope   | Skills | Status   |
| --------- | ------- | ------ | -------- |
| core      | user    | 2/2    | current  |
| docs      | project | 4/4    | current  |
| workflows | project | 26/26  | current  |
| ideas     | user    | 4/4    | current  |
| project-management | project | 3/3 | current |
| research  | project | 5/5    | current  |
| utility   | project | 5/5    | outdated |

## Outdated Skills

| Skill                   | Installed | Available | Scope   |
| ----------------------- | --------- | --------- | ------- |
| oat-project-implement   | 1.1.0     | 1.2.0     | project |

## Available But Not Installed

- **docs** pack: oat-docs-analyze, oat-docs-apply, oat-agent-instructions-analyze, oat-agent-instructions-apply (4 skills available)
  → Run: oat tools install docs --scope {scope}
- **project-management** pack: oat-pjm-add-backlog-item, oat-pjm-update-repo-reference, oat-pjm-review-backlog (3 skills available)
  → Run: oat tools install project-management --scope {scope}
- **research** pack: analyze, compare, deep-research, skeptic, synthesize (5 skills available)
  → Run: oat tools install research --scope {scope}

## Configuration

| Key                  | Value                     | Source  |
| -------------------- | ------------------------- | ------- |
| activeProject        | .oat/projects/shared/foo  | local   |
| activeIdea           | (not set)                 | -       |
| projects.root        | .oat/projects/shared      | default |
| documentation.root   | (not set)                 | -       |
| worktrees.root       | (not set)                 | -       |

### Config Key Explanations

Read config key descriptions from `~/.oat/docs/reference/file-locations.md` and `~/.oat/docs/guide/cli-reference.md`. If docs are not available, use these fallback descriptions:

- **activeProject:** Path to the currently active OAT project. Set automatically by project skills.
- **activeIdea:** Path to the currently active idea. Set by oat-idea-new.
- **lastPausedProject:** Path to the last paused project for quick resume.
- **projects.root:** Base directory for all OAT projects. Default: `.oat/projects/shared`.
- **documentation.root:** Root directory for documentation. Used by docs skills.
- **documentation.config:** Path to docs config file (e.g., mkdocs.yml).
- **documentation.tooling:** Docs tooling in use (e.g., mkdocs, fumadocs).
- **documentation.requireForProjectCompletion:** Whether docs update is required before project completion.
- **workflow.autoReviewAtHillCheckpoints:** When true, completing a HiLL checkpoint auto-triggers the lifecycle review. Default unset. This does not control Tier 1 per-phase `oat-reviewer` gates. Can be overridden per-project via `oat_auto_review_at_hill_checkpoints` in plan.md frontmatter. Legacy `autoReviewAtCheckpoints` and `oat_auto_review_at_checkpoints` are still read as fallbacks.
- **worktrees.root:** Base directory for git worktrees. Used by worktree-bootstrap skills.

## Sync Status

{In sync / N pending changes across M providers}

## Warnings

{Same warnings as check mode, if any}

## Recommendations

- Run `oat tools update` to update outdated skills.
- Run `oat init tools` to install newly available packs.
- Run `oat sync --scope project` to sync provider views.

Adapt the dashboard to show only sections with relevant data. Omit empty sections.

Success Criteria

• ✅ Check mode reports all warnings with actionable fix commands.
• ✅ Summary mode shows a complete dashboard of installed packs, config, and available skills.
• ✅ Outdated skills are detected and update commands are provided.
• ✅ Stale config pointers are identified.
• ✅ Available-but-uninstalled packs/skills are surfaced (discovery gap closed).
• ✅ No files are modified — purely diagnostic output.