im-shashanks/claude-plugins / shaktra/skills/shaktra-doctor
shaktra-doctor
VerifiedDiagnose Shaktra framework health. Validates plugin structure, project configuration, and design constraints. Read-only — never modifies files.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.8 KB |
SKILL.md
View on GitHub---
name: shaktra-doctor
description: >
Diagnose Shaktra framework health. Validates plugin structure, project configuration,
and design constraints. Read-only — never modifies files.
user-invocable: true
---
# /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
```
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 323k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |