# Shaktra Doctor

> Diagnose Shaktra framework health. Validates plugin structure, project configuration, and design constraints. Read-only — never modifies files.

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

---


# /shaktra:doctor — Framework Health Check

Read-only diagnostic. Runs 10 checks across 3 categories. Never creates, modifies, or deletes any file.

Use `${CLAUDE_PLUGIN_ROOT}` to locate the installed plugin directory for all plugin structure checks.

---

## Category 1: Plugin Structure

Checks the installed plugin at `${CLAUDE_PLUGIN_ROOT}`.

### Check 1 — Agent Files

Glob `${CLAUDE_PLUGIN_ROOT}/agents/*.md`. Verify all 15 agent files exist and each has valid YAML frontmatter (opening and closing `---` with at least `name` field).

**Expected agents:**
shaktra-adversary, shaktra-architect, shaktra-bug-diagnostician, shaktra-cba-analyzer, shaktra-cr-analyzer, shaktra-developer, shaktra-incident-analyst, shaktra-memory-curator, shaktra-memory-retriever, shaktra-product-manager, shaktra-scrummaster, shaktra-sw-engineer, shaktra-sw-quality, shaktra-test-agent, shaktra-tpm-quality

PASS: All 15 files exist with valid frontmatter.
FAIL: List missing files or files with invalid frontmatter.

### Check 2 — Skill Directories

Glob `${CLAUDE_PLUGIN_ROOT}/skills/*/SKILL.md`. Verify all 20 skill directories exist and each SKILL.md has valid YAML frontmatter (opening and closing `---` with at least `name` and `description` fields).

**Expected skills:**
shaktra-adversarial-review, shaktra-analyze, shaktra-bugfix, shaktra-dev, shaktra-doctor, shaktra-general, shaktra-help, shaktra-incident, shaktra-init, shaktra-memory, shaktra-memory-stats, shaktra-pm, shaktra-quality, shaktra-reference, shaktra-review, shaktra-status-dash, shaktra-stories, shaktra-tdd, shaktra-tpm, shaktra-workflow

PASS: All 20 skill SKILL.md files exist with valid frontmatter.
FAIL: List missing skills or invalid frontmatter.

### Check 3 — Python Scripts

Glob `${CLAUDE_PLUGIN_ROOT}/scripts/*.py`. Verify all expected scripts exist. For hook scripts, use Bash `test -x` to confirm they are executable.

**Expected hook scripts (must be executable):**
block_main_branch.py, check_p0_findings.py, validate_schema.py, validate_story_scope.py

**Expected utility scripts:**
check_version.py, memory_retrieval.py, migrate_memory.py, update_plugin.py

PASS: All 8 scripts exist, all hook scripts executable.
FAIL: List missing or non-executable scripts.

### Check 4 — Sub-File References

For each SKILL.md that references sub-files (files within the same skill directory), verify those files actually exist. Read each SKILL.md that has a "Sub-Files" section or references relative `.md` files. For each referenced file, confirm it exists at the expected path under `${CLAUDE_PLUGIN_ROOT}/skills/<skill-name>/`.

PASS: All referenced sub-files exist.
FAIL: List each dangling reference with the SKILL.md that references it and the missing file path.

### Check 10 — Python Dependencies

Run `python3 -c "import yaml"` via Bash. Check the return code.

PASS: PyYAML is installed and importable.
FAIL: PyYAML is not installed → run: pip install pyyaml

---

## Category 2: Project Health

Checks the `.shaktra/` directory in the current working directory.

**If `.shaktra/` does not exist**, skip all Category 2 checks and report: "`.shaktra/` not found — run `/shaktra:init` first. Skipping project health checks."

### Check 5 — Settings File

Read `.shaktra/settings.yml`. Verify it exists and contains the required top-level sections: `project`, `tdd`, `quality`, `review`, `analysis`, `refactoring`, `sprints`.

Within `project`, verify these fields are present and non-empty: `name`, `type`, `language`.

PASS: settings.yml exists with all required sections and populated project fields.
FAIL: List missing sections or empty required fields.

### Check 6 — Directory Structure

Verify these subdirectories exist within `.shaktra/`:

- `memory/`
- `stories/`
- `designs/`
- `analysis/`

PASS: All expected subdirectories exist.
FAIL: List missing directories.

**Memory file check:** If `.shaktra/memory/` exists, verify expected files:
- `principles.yml` — expected
- `anti-patterns.yml` — expected
- `procedures.yml` — expected
- `decisions.yml` — warn if present (legacy file, suggest running migration)
- `lessons.yml` — warn if present (legacy file, suggest running migration)

---

## Category 3: Design Constraints

Plugin-wide validation against Shaktra design rules. Run these checks against `${CLAUDE_PLUGIN_ROOT}`.

### Check 7 — File Line Limits

Use Bash `wc -l` on all `.md` and `.py` files under `${CLAUDE_PLUGIN_ROOT}`. Flag any file exceeding 300 lines.

PASS: No file exceeds 300 lines.
FAIL: List each file over 300 lines with its line count.

### Check 8 — Severity Taxonomy Uniqueness

The severity taxonomy (P0-P3 definitions) must be defined in exactly one file: `skills/shaktra-reference/severity-taxonomy.md`.

Grep `${CLAUDE_PLUGIN_ROOT}` for the pattern `## P0` (heading-level severity definitions). The pattern should match only in `severity-taxonomy.md`. Other files may *mention* severity levels (e.g., "P0 findings block merge") — that is fine. Only flag files that *redefine* the taxonomy with their own heading-level P0-P3 sections.

PASS: Severity taxonomy defined in exactly one file.
FAIL: List additional files that redefine severity levels.

### Check 9 — No Orphaned Files

Every `.md` file inside a skill directory (other than SKILL.md itself) must be referenced by that skill's SKILL.md. Glob all non-SKILL.md `.md` files under `${CLAUDE_PLUGIN_ROOT}/skills/`. For each, check that the parent skill's SKILL.md contains a reference to its filename.

PASS: All sub-files are referenced by their parent SKILL.md.
FAIL: List orphaned files not referenced by any SKILL.md.

---

## Output Format

Present results as a structured report:

```
## Shaktra Doctor Report

### Category 1: Plugin Structure
- [PASS] Check 1 — Agent Files: 15/15 agents found with valid frontmatter
- [PASS] Check 2 — Skill Directories: 20/20 skills found with valid frontmatter
- [PASS] Check 3 — Python Scripts: 8/8 scripts found, hooks executable
- [PASS] Check 4 — Sub-File References: All references resolve
- [PASS] Check 10 — Python Dependencies: PyYAML installed

### Category 2: Project Health
- [PASS] Check 5 — Settings File: All required sections and fields present
- [PASS] Check 6 — Directory Structure: All subdirectories present

### Category 3: Design Constraints
- [PASS] Check 7 — File Line Limits: All files under 300 lines
- [PASS] Check 8 — Severity Taxonomy: Defined in exactly 1 file
- [PASS] Check 9 — No Orphaned Files: All sub-files referenced

Summary: 10/10 checks passed
```

For any FAIL result, include actionable detail immediately after the check line:

```
- [FAIL] Check 3 — Hook Scripts: 1 issue
  - validate_schema.py is not executable → run: chmod +x scripts/validate_schema.py
```