# Doctor

> Validate framework configuration, check runtime dependencies, and report issues. Use when something isn't working or after setup.

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

---

______________________________________________________________________

## doctor

Run a comprehensive health check on the framework configuration and project setup.

## 1. Command Verification

Read CLAUDE.md Commands section. For each configured command (test, lint, format, build, typecheck):

<IF condition="command is configured (not placeholder)">
Run the command in dry-run or check mode (e.g., `npm test --dry-run`, `ruff check --quiet .`).
Report: PASS if it executes, FAIL if it errors, SKIP if not configured.
</IF>
<ELSE>
Report: NOT CONFIGURED — suggest running `/bootstrap` to detect.
</ELSE>

## 2. Hook Dependencies

For each hook in `.claude/settings.json`:

- Verify the hook script file exists and is executable
- For `post-edit-format.sh`: check if at least one formatter is installed (prettier, biome, ruff, black, rustfmt, gofmt)
- For shell hook scripts: verify git is available (used by stop.sh, session-start.sh)
- Optional: check if jq is available (hooks fall back to sed without it)

Report: PASS/WARN (missing optional tools)/FAIL (missing required tools)

## 3. Rule Relevance

For each rule in `.claude/rules/`:

- Read the YAML frontmatter `paths:` field
- Check if any files in the project match those patterns
- Report: ACTIVE (matches found) / DORMANT (no matches — rule will never trigger)
- Check `docs/sessions/.activity-log.jsonl` for rule trigger frequency over the last 5 sessions
- Rules that are ACTIVE but have zero trigger events in 5+ sessions: report as REVIEW (candidate for retirement)
- The "pull their weight" test: if a rule never changes AI behavior, it wastes context budget

## 4. Skill Dependencies & Cross-References

For each skill with `depends-on:` in YAML frontmatter:

- Verify each dependency skill exists in `.claude/skills/`
- For skills with `requires:` — check binaries, commands, and files
- Report: PASS/WARN (optional dependency missing)/FAIL (required dependency missing)

For each skill with `calls:` in `skills-registry.json`:

- Verify each called skill exists in `.claude/skills/`
- Report any broken references (skill calls a non-existent skill)
- Report orphaned skills (not called by any other skill AND not user-invocable) as INFO — may be intentionally standalone

## 5. Documentation Freshness

Check key framework files:

- CLAUDE.md: Is "Current Focus" section filled (not placeholder)?
- docs/progress.md: Has it been updated this sprint?
- docs/reference/BACKLOG_INDEX.md: Are status counts current?
- docs/reference/GROUND_RULES.md: Does it exist and have principles?

Report: CURRENT/STALE/MISSING for each

## 6. Git State

- Branch naming follows convention (`feat/*`, `fix/*`, `hotfix/*`, `refactor/*`, `docs/*`, `test/*`, `chore/*`, or `sprint-*`)?
- Any stale branches (merged but not deleted)?
- Any unmerged branches with no commits in the last 2 weeks?
  ```bash
  git for-each-ref --sort=-committerdate --format='%(refname:short) %(committerdate:relative)' refs/heads/ | while read branch date; do echo "$branch — last commit $date"; done
  ```
  Flag branches with no commits in >14 days as "potentially stale — consider merging or deleting"
- Remote configured and accessible?

## 7. Skill Conformance

Execute `scripts/validate-skills.sh` directly — do NOT read source first.

```bash
bash .claude/skills/doctor/scripts/validate-skills.sh
```

Reports per-skill conformance: YAML frontmatter, line budget, required sections, reference budgets, registry version match. Include results in the health report under a "Skill Conformance" section.

## 8. Skill Usage Analytics

Parse `docs/sessions/.activity-log.jsonl` for entries with `"type":"skill"`:

```bash
# Extract skill invocation data from activity log
grep '"type":"skill"' docs/sessions/.activity-log.jsonl 2>/dev/null || echo "No skill data"
```

- Count invocations per skill name over all available log data
- Find the most recent invocation timestamp per skill
- List all skill directories from `.claude/skills/` (excluding SKILLS_INVENTORY.md, SKILL_TEMPLATE.md, and non-directory entries)
- Cross-reference invocations with available skills to classify:
  - **ACTIVE:** Invoked at least once in the log
  - **DORMANT:** Skill directory exists, user-invocable, but never invoked
  - **FREQUENT:** Invoked 5+ times (top skills)
- Note: Skills not in the log may still be useful — they may not have been needed yet. DORMANT is informational, not a problem.

## 9. Profile & Hook Status

Report the current project profile and hook configuration:

```bash
echo "Project profile: $(cat .claude/hooks/state/project-profile 2>/dev/null || echo 'standard (default)')"
echo "EXOSUIT_PROJECT_PROFILE=${EXOSUIT_PROJECT_PROFILE:-<not set, reading from CLAUDE.md>}"
echo "EXOSUIT_HOOK_PROFILE=${EXOSUIT_HOOK_PROFILE:-<derived from project profile>}"
echo "EXOSUIT_DISABLED_HOOKS=${EXOSUIT_DISABLED_HOOKS:-<none>}"
echo "EXOSUIT_EXPLAIN_MODE=${EXOSUIT_EXPLAIN_MODE:-brief}"
echo "EXOSUIT_STOP_MAX_ITERATIONS=${EXOSUIT_STOP_MAX_ITERATIONS:-5}"
```

- Show current project profile and its source (env var, CLAUDE.md `**Profile:**` line, or default)
- Show derived hook profile and whether it was explicitly overridden
- Profile implications:
  - **lean**: minimal hooks, simplified story-cycle (Plan→Build→Verify), no quality agents, no sprint specs
  - **standard**: standard hooks, full 8-phase story-cycle, 3 quality agents, full docs
  - **strict**: strict hooks, all phases mandatory for all stories, 5 quality agents + integration-tester, audit trail
- List any disabled hooks
- Verify `lib/hook-guard.sh` exists and is executable
- Show effective stop iteration limit (strict defaults to 10)

## 10. Readiness Progress

If `docs/reference/READINESS_REPORT.md` exists, compare the bootstrap baseline against current project state:

1. Read and parse the readiness assessment table (Principle / Status / Detail)
2. For each principle classified as `⚠️ Risk` or `✗ Missing`, re-evaluate using data from sections 1–9:
   - **TDD-first** → Test command (§1) + run coverage tool if available
   - **Sprint-based / Git-disciplined** → Git state (§6)
   - **Verification-driven** → Test command passes (§1)
   - **CI-enforced** → Check for `.github/workflows/`, `.gitlab-ci.yml`, `.circleci/`, `Jenkinsfile`
   - **Secrets-aware** → Post-edit hook (§2) + `.env*` in `.gitignore`
   - **Anti-slop** → `code-slop.md` rule exists (§3)
   - **Quality gates** → Formatter + linter + coverage + typecheck all available (§1)
   - **Context-efficient** → Source files >500 LOC: `find . -name '*.{ext}' -not -path '*/node_modules/*' | xargs wc -l | awk '$1>500 && !/total$/' | wc -l`
   - **Documentation-lean** → Core docs populated (§5)
   - **Pre-commit hooks** → `.pre-commit-config.yaml`, `.husky/`, or `lefthook.yml` exists
   - **Type-safe** → Typecheck command works (§1)
   - **Contract-first / API-documented** → API spec files + `API_DOCUMENTATION.md` (skip if no API detected)
   - **Decisions-documented** → `docs/adr/` has ≥1 accepted ADR
3. Classify each as `✓ Ready`, `⚠️ Risk`, or `✗ Missing` using bootstrap's classification rules

If the file does not exist, report: "No readiness baseline — run `/bootstrap` to generate `docs/reference/READINESS_REPORT.md`."

## Output

```markdown
## Framework Health Report

### Commands
| Command | Status | Notes |
|---------|--------|-------|
| test | PASS/FAIL/NOT CONFIGURED | [details] |
| lint | PASS/FAIL/NOT CONFIGURED | [details] |
| ... | | |

### Hooks
| Hook | Status | Missing Tools |
|------|--------|---------------|
| post-edit-format.sh | PASS/WARN | [list] |
| ... | | |

### Rules
| Rule | Status | Matching Files |
|------|--------|----------------|
| testing.md | ACTIVE | [count] files |
| ... | | |

### Skills
| Check | Status | Details |
|-------|--------|---------|
| Dependency resolution | PASS/WARN | [details] |
| Prerequisites | PASS/WARN | [details] |

### Documentation
| File | Status | Last Updated |
|------|--------|-------------|
| CLAUDE.md | CURRENT/STALE | [date] |
| ... | | |

### Skill Conformance
| Skill | Frontmatter | Lines | References | Registry |
|-------|-------------|-------|------------|----------|
| [name] | PASS/FAIL | [count] | PASS/WARN | PASS/WARN |

### Skill Usage
| Skill | Invocations | Last Used | Status |
|-------|-------------|-----------|--------|
| story-cycle | 15 | 2026-03-25 | ACTIVE |
| manual-test | 0 | never | DORMANT |

### Profile & Hook Configuration
| Setting | Value | Source |
|---------|-------|--------|
| Project Profile | lean/standard/strict | env var / CLAUDE.md / default |
| Hook Profile | minimal/standard/strict | env var / derived from project |
| Disabled Hooks | none or list | EXOSUIT_DISABLED_HOOKS |
| Explain Mode | off/brief/verbose | EXOSUIT_EXPLAIN_MODE |
| Stop Iterations | 5/10/custom | EXOSUIT_STOP_MAX_ITERATIONS |
| Guard script | PASS/FAIL | lib/hook-guard.sh |

### Readiness Progress (if baseline exists)
| Principle | Bootstrap | Current | Progress |
|-----------|-----------|---------|----------|
| TDD-first | ✗ Missing | ✓ Ready | ↑ Fixed |
| CI-enforced | ⚠️ Risk | ⚠️ Risk | → Unchanged |

**Progress:** X of Y gaps addressed since bootstrap ({date})
_Only rows for principles that were Risk or Missing at bootstrap. Omit Ready principles._

### Overall: X/Y checks passed — [HEALTHY / NEEDS ATTENTION / ACTION REQUIRED]
```

## Next Steps

Based on findings, suggest:
- `/bootstrap` — if commands or hooks need configuration
- Specific fixes for any FAIL items
- `/weekly-maintenance` — if documentation is stale
- Foundation stories from `E00-foundation.md` — if readiness gaps persist