plugin-doctor
Diagnose and fix quality issues in marketplace components with automated safe fixes and prompted risky fixes
SKILL.mdmarketplace/bundles/pm-plugin-development/skills/plugin-doctor/SKILL.md
GitHubPlugin Doctor Skill
Comprehensive diagnostic and fix skill for marketplace components. Combines diagnosis, automated safe fixes, prompted risky fixes, and verification into a single workflow.
Enforcement
Execution mode: Select workflow based on scope parameter and execute immediately. Do not explain — execute.
Prohibited actions:
- Do not prompt for safe fixes — apply them automatically without AskUserQuestion
- Agents cannot use the Task tool (agent-task-tool-prohibited — unavailable at runtime)
- Only maven-builder agent may execute Maven commands (agent-maven-restricted)
- Do not invent script notations — use only documented notations from the skill being called
Constraints:
- Load prerequisite skills and the component reference guide before analyzing
- Every workflow step that performs a script operation must have an explicit bash code block with the full
python3 .plan/execute-script.pycommand - Agents must record lessons via manage-lessons skill, not self-invoke commands (agent-lessons-via-skill)
- Only
doctor-marketplace.pyis registered in the executor._analyze.py,_validate.py, and_fix.pyare separate verb-bearing entry points whose verbs are NOTdoctor-marketplacesubcommands; a workflow needing one invokes the script directly, and no executor form may be documented for them. See § External Resources - Prose instructions adjacent to script calls must reference parameter values consistent with the script API (workflow-prose-parameter-inconsistency)
Exit-code convention for every script call
The exit-code contract for every python3 .plan/execute-script.py call in this document — of EVERY notation, not only manage-* — is stated once in tools-script-executor/standards/exit-code-convention.md; it is not restated here.
Purpose
Provides unified doctor workflows following the pattern: Diagnose → Auto-Fix Safe → Prompt Risky → Verify
Dispatch shape: invoked via verification-feedback with producer=plugin-doctor
The plugin-doctor analyses no longer earn their own dispatch role. The marketplace rule iteration, scope filtering, and per-violation finding emission described in "Common Workflow Pattern" below run inside verification-feedback.md § Step 1 when producer=plugin-doctor. The level resolves under phase-6-finalize.verification-feedback (since the slash command + the project:finalize-step-plugin-doctor wrapper both fire from phase-6-finalize).
This skill stays loaded inside the verification-feedback envelope as the rule catalog + per-rule prose holder — every rule analysis below is executed in-context by the dispatched subagent. scope continues to select which rule subset fires; rules iterate in-context (no per-rule fan-out). Bundling matches granularity Heuristic 2: every rule reads the same marketplace tree, shares the same plugin-doctor skill loads, and contributes findings to the same per-plan findings store. See the dispatch-granularity standard under plan-marshall:extension-api § 5.1 for the phase-scoped resolution + producer-mode bundling rule.
Workflow Decision Tree
Select workflow based on input and execute immediately.
If scope = "agents" or agent-name specified
→ EXECUTE Workflow 1: doctor-agents (jump to that section)
If scope = "commands" or command-name specified
→ EXECUTE Workflow 2: doctor-commands (jump to that section)
If scope = "skills" or skill-name specified
→ EXECUTE Workflow 3: doctor-skills (jump to that section)
If scope = "metadata"
→ EXECUTE Workflow 4: doctor-metadata (jump to that section)
If scope = "scripts" or script-name specified
→ EXECUTE Workflow 5: doctor-scripts (jump to that section)
If scope = "skill-content" or skill-path specified with content analysis
→ EXECUTE Workflow 6: doctor-skill-content (jump to that section)
If scope = "marketplace" (full marketplace health check)
→ EXECUTE Workflow 7: doctor-marketplace (jump to that section)
If scope = "plan-marshall"
→ EXECUTE Workflow 8: doctor-plan-marshall (jump to that section)
If scope = "skill-knowledge" or skill-path specified with knowledge review
→ EXECUTE Workflow 9: doctor-skill-knowledge (jump to that section)
If scope = "test-conventions"
→ EXECUTE Workflow 10: doctor-test-conventions (jump to that section)
Progressive Disclosure Strategy
Load only the reference guide(s) needed per workflow (not all at once):
| Workflow | Diagnosis Reference | Fix Reference |
|---|---|---|
| doctor-agents | agents-guide.md |
fix-catalog.md |
| doctor-commands | commands-guide.md |
fix-catalog.md |
| doctor-skills | skills-guide.md |
fix-catalog.md |
| doctor-metadata | metadata-guide.md |
fix-catalog.md |
| doctor-scripts | scripts-guide.md |
fix-catalog.md |
| doctor-plan-marshall | plan-marshall-guide.md (in plan-marshall bundle) |
fix-catalog.md |
| doctor-skill-knowledge | llm-optimization-guide.md |
fix-catalog.md |
| doctor-skill-content | content-classification-guide.md + content-quality-guide.md |
fix-catalog.md |
| doctor-marketplace | (batch: uses all guides via report) | fix-catalog.md |
Cross-cutting reference (loaded by all workflows): llm-optimization-guide.md
Context Efficiency: ~800 lines per workflow vs ~4,000 lines if loading everything.
Common Workflow Pattern
All 9 workflows follow the same pattern:
Phase 1: Discover and Analyze
Load Prerequisites
Load these skills before proceeding:
Skill: plan-marshall:persona-plan-marshall-agent Skill: pm-plugin-development:plugin-architecture Skill: pm-plugin-development:tools-marketplace-inventoryLoad Component Reference (progressive disclosure)
Read:
references/{component}-guide.mdDiscover Components (based on scope parameter)
- marketplace scope: Use marketplace-inventory
- global scope: Glob the user-global deployment root (resolved via the shared layout helper; Claude:
~/.claude/{component}/) - project scope: Glob the active target's project-local skill roots (resolved via the platform-runtime
layout skill-rootsop; Claude:.claude/{component}/)
Analyze Components (using doctor-marketplace)
Use the batch analyze command with appropriate filters:
python3 .plan/execute-script.py pm-plugin-development:plugin-doctor:doctor-marketplace analyze \ --bundles {bundle} --type {component_type} [--name {name}]Use
--nameto filter by component name (e.g.,--name phase-4-plan) instead of fetching all components and filtering manually.This performs markdown analysis, coverage extraction, and reference validation for all matching components. For skills, it also analyzes sub-documents (
references/*.md,standards/*.md,workflow/*.md,templates/*.md) for bloat, forbidden metadata, and hardcoded script paths. The output includes per-component analysis results in TOON format with asubdocumentskey for skills.
Phase 1.5: LLM Optimization Check
Load references/llm-optimization-guide.md and review analyzed components for low-value patterns (checklists of obvious rules, motivational text, redundant emphasis, duplicated content). For skills, review both SKILL.md and sub-documents from the subdocuments key.
Phase 2: Categorize Issues
Categorize each issue as safe or risky per references/fix-catalog.md. Safe fixes are auto-applied; risky fixes require user confirmation.
Phase 3: Apply Fixes
Auto-Apply Safe Fixes — Apply immediately using Edit tool without AskUserQuestion. Track success/failure.
Prompt for Risky Fixes ONLY
AskUserQuestion: question: "Apply fix for {issue}?" options: - label: "Yes" description: "Apply this fix" - label: "No" description: "Skip this fix" - label: "Skip All" description: "Skip remaining risky fixes"
Phase 4: Verify and Report
Verify Fixes
Re-run analysis to verify fixes resolved issues:
python3 .plan/execute-script.py pm-plugin-development:plugin-doctor:doctor-marketplace analyze \ --bundles {bundle} --type {component_type} [--name {name}]Compare issue counts before and after to verify resolution.
Generate Summary Generate a cross-bundle summary report with metrics: bundles processed, total components, issues by severity (clean/warnings/critical), fixes applied (safe/risky), and per-bundle breakdown.
Workflow 1: doctor-agents
Follows common workflow pattern. See standards/doctor-agents.md for agent-specific checks and thresholds.
Workflow 2: doctor-commands
Follows common workflow pattern. See standards/doctor-commands.md for command-thin-wrapper checks and fix patterns.
Workflow 3: doctor-skills
Follows common workflow pattern. See standards/doctor-skills.md for enforcement block, foundation skill, and skill-naming-noun-suffix validations.
Workflow 4: doctor-metadata
Follows the common workflow pattern. Reference guide: metadata-guide.md.
Metadata-specific checks:
- Verify JSON syntax of each
plugin.json - Check required fields (name, version, description)
- Validate component arrays (commands, skills, agents)
- Cross-check declared components vs actual files on disk
Discovery: Glob: pattern="**/plugin.json", path="marketplace/bundles"
Safe fixes: Missing required fields, extra entries (files don't exist), missing entries (files exist but not listed).
Workflow 5: doctor-scripts
Follows the common workflow pattern. Additional prerequisite: Skill: pm-plugin-development:plugin-script-architecture.
Script-specific checks:
- Verify SKILL.md documents the script
- Check test file exists in
test/directory - Verify
--helpoutput is functional - Check stdlib-only compliance (no external dependencies)
Discovery: Glob: pattern="scripts/*.{sh,py}", path="marketplace/bundles/*/skills"
Workflow 6: doctor-skill-content
See standards/doctor-skill-content.md for the complete workflow.
Workflow 7: doctor-marketplace
See standards/doctor-marketplace.md for the complete workflow.
Workflow 8: doctor-plan-marshall
Follows common workflow pattern. PM-001 through PM-006 validation rules and reference guide have moved to plan-marshall:plan-marshall-plugin bundle (see doctor-plan-marshall.md and plan-marshall-guide.md there).
Workflow 9: doctor-skill-knowledge
Reviews knowledge skill content quality. See standards/doctor-skill-knowledge.md for correctness, consistency, structure, and LLM optimization checks.
Workflow 10: doctor-test-conventions
Test-tree conventions enforced across the test/ directory, at two severities. See standards/doctor-test-conventions.md for the full rule definitions and the validator registry schema.
Build-failing (error) — four rules: unique fixture-module basenames, subprocess.run PYTHONPATH propagation (AST-based), identifier-validator regex vs. corpus, and helper module given a collected name.
Reporting (warning) — three structural house-style rules: test-module line budget (400 lines), hand-rolled import preamble (spec_from_file_location / deep Path(__file__).parent chain or parents[N]), and historical citations in test docstrings and comments.
status is derived from error-severity findings only, so warning_count can be non-zero while status: pass. Severity is per rule and conditional: a rule ships at warning while the tree still violates it and is flipped to error once its own count reaches zero — test-helper-module-misnamed has already made that transition. This scope is not part of quality-gate.
External Resources
Scripts (scripts/)
Only doctor-marketplace.py is registered in the executor.
_analyze.py, _validate.py, and _fix.py are separate verb-bearing entry
points, each with its own argparse surface and if __name__ == '__main__' block.
Their verbs are NOT doctor-marketplace subcommands: doctor-marketplace
declares list-components, analyze, fix, report, quality-gate,
test-conventions, validate-contracts, while _analyze.py declares markdown,
structure, coverage, cross-file; _validate.py declares references,
cross-file, inventory, extension; and _fix.py declares extract,
categorize, apply, verify. No doctor-marketplace verb name appears among
them, and doctor-marketplace.py imports none of the three.
⛔ Unregistered, so no executor form may be written for them — here or in any
consuming doc. A workflow that needs one of these verbs
invokes the script directly and says so; the doctor-skill-content workflow does
exactly that for _analyze.py cross-file (see
content-quality-guide.md § Integration).
An unregistered third part does still resolve through the executor's filename
fallback, but that resolution is not a sanctioned form and documenting it as an
invocation is a lint violation. The consequence for extension specifically is
worked through in
plan-marshall:extension-api extension-contract.md § Validation.
Registered Script (callable via executor):
| Script | Subcommand | Mode | Purpose |
|---|---|---|---|
doctor-marketplace.py |
list-components |
EXECUTE | Batch discovery / enumeration of components (--bundles, --paths); runs no rules |
doctor-marketplace.py |
analyze |
EXECUTE | Batch analysis of all components for issues (--bundles, --type, --name) |
doctor-marketplace.py |
fix |
EXECUTE | Auto-apply safe fixes across marketplace (--bundles, --type, --name, --dry-run) |
doctor-marketplace.py |
report |
EXECUTE | Generate comprehensive report for LLM review |
doctor-marketplace.py |
quality-gate |
EXECUTE | Run invariant rules as a build gate; optional --paths scoping (exit 1 on findings) |
doctor-marketplace.py |
test-conventions |
EXECUTE | Run test-tree convention rules (exit 1 on error-severity findings; warnings reported only) |
doctor-marketplace.py |
validate-contracts |
EXECUTE | Validate extension-POINT contract compliance (EC-01…EC-50); population selected by directory-name prefix |
Notation: pm-plugin-development:plugin-doctor:doctor-marketplace {subcommand}
Internal Modules (unregistered — no sanctioned executor form):
| Module | Purpose |
|---|---|
_analyze.py |
Dispatcher declaring markdown, structure, coverage, cross-file — imports the four _analyze_* modules below; no verb reachable as a doctor-marketplace subcommand |
_analyze_markdown.py |
Markdown structure analysis |
_analyze_coverage.py |
Tool coverage extraction |
_analyze_structure.py |
Skill directory structure validation |
_analyze_crossfile.py |
Cross-file duplication analysis |
_validate.py |
Dispatcher declaring references, cross-file, inventory, extension — no verb reachable as a doctor-marketplace subcommand |
_fix.py |
Dispatcher declaring extract, categorize, apply, verify — no verb reachable as a doctor-marketplace subcommand |
Hybrid Batch Processing
Subcommands: list-components → analyze → fix → report. See standards/doctor-marketplace.md for the complete two-phase (script + LLM) workflow, report output format, and directory structure.
list-components --paths (Explicit Path Mode)
The list-components subcommand enumerates components and runs no rules — use quality-gate for linting. It accepts --paths to enumerate explicit component paths instead of discovering from the marketplace. This is mutually exclusive with --bundles.
# Enumerate a marketplace skill by path
python3 .plan/execute-script.py pm-plugin-development:plugin-doctor:doctor-marketplace list-components \
--paths marketplace/bundles/plan-marshall/skills/phase-4-plan
# Enumerate project-local skills
python3 .plan/execute-script.py pm-plugin-development:plugin-doctor:doctor-marketplace list-components \
--paths .claude/skills/my-custom-skill
# Enumerate multiple paths (mixed marketplace and project-local)
python3 .plan/execute-script.py pm-plugin-development:plugin-doctor:doctor-marketplace list-components \
--paths marketplace/bundles/plan-marshall/skills/phase-4-plan \
marketplace/bundles/pm-dev-java/agents/java-verify-agent.md \
.claude/skills/project-local-skill
When --paths is provided:
- Each path is resolved to absolute (relative paths resolve against cwd)
- Component type is auto-detected from directory structure (SKILL.md presence, frontmatter patterns, parent directory name)
- Marketplace root validation is skipped entirely
- Invalid or missing paths produce a warning on stderr and are skipped
Note: --paths and --bundles are mutually exclusive. Use --bundles for bundle-scoped discovery, --paths for targeting specific components. list-components enumerates only — to run the invariant rule set scoped to specific paths, use quality-gate --paths {dir}....
Worktree-Aware Invocation
Use the --marketplace-root flag when verifying SKILL.md / agent.md / command.md edits made inside a plan worktree mid-execution, before the worktree merges back to main. The flag pins discovery to the worktree's marketplace tree so analysis sees the in-progress edits instead of the main checkout.
python3 .plan/execute-script.py pm-plugin-development:plugin-doctor:doctor-marketplace analyze \
--marketplace-root /abs/path/to/.plan/local/worktrees/{plan_id}/marketplace \
--name foo
Important: the value passed to --marketplace-root is the marketplace root, i.e., the parent directory of bundles/ (e.g., /abs/path/to/.plan/local/worktrees/{plan_id}/marketplace), NOT bundles/ itself. The script validates this by checking for a bundles/ subdirectory under the supplied path; if missing, it errors out with a clear message. Resolution precedence is: --marketplace-root flag → PM_MARKETPLACE_ROOT env var → script-relative discovery → cwd fallback.
References (references/)
Loaded per workflow via Progressive Disclosure table above. Key files:
rule-catalog.md- Rule definitions for all validated rulesllm-optimization-guide.md- Cross-cutting LLM optimization patternsfix-catalog.md,safe-fixes-guide.md,risky-fixes-guide.md,verification-guide.md- Fix workflow- Per-component guides:
agents-guide.md,commands-guide.md,skills-guide.md,metadata-guide.md - plan-marshall-specific:
plan-marshall-guide.md(inplan-marshall:plan-marshall-plugin/references/, includes extension validation) - Content analysis:
content-classification-guide.md,content-quality-guide.md
Assets (assets/)
fix-templates.json- Fix templates and rules
Templates (templates/)
tool-coverage-results.toon- TOON template for aggregating tool-coverage analysis results (produced by the plugin-doctor tool-coverage rule, which runs in-line inside theverification-feedbackenvelope when its scope covers tool-coverage)
Output
plugin-doctor returns per-workflow shapes (see Workflows 1-10 above). The minimum contract every workflow doc that implements ext-point-execution-context-workflow MUST return is:
status: pass | fail | error
display_detail: "<{N} components scanned, {findings} findings>"
total_issues: {N}
display_detail shape: "{components} components scanned, {findings} findings" (e.g. "42 components scanned, 0 findings"); ≤80 chars, ASCII, no trailing period. Per-workflow returns layer additional rules_run[] / issues[] rows on top of these mandatory fields.
Suppression Model
Real-file finding suppression flows through one declarative substrate with three composing granularities; a finding is suppressed when any granularity matches. The substrate replaces the scattered per-analyzer inline doctor-ignore markers and hardcoded allowlists.
- Granularity-1 (shipped default) —
config/default-suppression.yml, bundle-resident, maps each rule-id to a list ofmarketplace/bundles/-relative path prefixes. - Granularity-2 (project config) —
.plan/plugin-doctor.yml, git-controlled at the project root, same path-prefix shape; lets a consuming project register exemptions without touching the bundle. - Granularity-3 (per-file frontmatter) — the file's own
plugin-doctor-disable: [rule-id, ...]YAML key, scoped to that single file.
The matching, precedence ordering, and config-parsing logic are owned by scripts/_analyze_shared.py (is_rule_suppressed) — the enforcement-critical source of truth, also authoritative for the constrained stdlib-parseable flat-YAML config subset. The full model, the canonical rule-id list, and the per-rule suppression notes are documented in references/rule-catalog.md § Declarative Suppression Substrate. This substrate is distinct from the zero-match-rule detector's EXEMPT_RULE_IDS.
Rule Definitions
See references/rule-catalog.md for the catalog of rules that plugin-doctor validates (agent, workflow, command, skill, script, content, and PM-workflow rules). It does not cover every emitted rule id; references/rule-provenance.md is the per-rule registry.
Representative rule ids by category:
- Agent:
agent-task-tool-prohibited,agent-maven-restricted,agent-lessons-via-skill,agent-skill-tool-visibility - Workflow:
workflow-hardcoded-script-path,workflow-prose-parameter-inconsistency,prose-verb-chain-consistency - Skill:
skill-naming-noun-suffix - Script:
argparse_safety,notation-staleness,script-call-drift - Manage-invocation:
manage-findings-invocation-invalid,manage-invocation-invalid,missing-canonical-block(see scripts/_analyze_manage_invocation.py for the generalized analyzer) - Mirror-drift:
provides-method-table-drift,literal-count-drift,canonical-enum-choices-drift,readme-skill-registration-drift,broken-relative-link,fenced-code-no-language(build-failing — registered incmd_quality_gateso a drifted mirror fails the build, and also reported underanalyze;fenced-code-no-languageis auto-fixable;provides-method-table-driftdetects drift between aplan-marshall-pluginextension.pyprovides_*()overrides and the SKILL.md "Extension API" table mirror — see scripts/_analyze_provides_method_table.py;canonical-enum-choices-driftcompares a documented{a|b|c}enum in a## Canonical invocationsblock against the flag's live argparsechoices=;readme-skill-registration-driftcompares a bundle README's skill enumeration against the set itsplugin.jsonregisters) - Content:
checklist-pattern - PM-Workflow:
pm-implicit-script-callthroughpm-contract-non-compliance - Test-Conventions (
error):unique-fixture-basenames,subprocess-pythonpath,identifier-validator-corpus,test-helper-module-misnamed(see standards/doctor-test-conventions.md) - Test-Conventions (
warning):test-module-line-budget,test-module-preamble-boilerplate,test-docstring-historical-prose(same standard)
Non-Prompting Requirements
This skill is designed to run without user prompts for safe operations. Required permissions:
Skill Invocations (covered by bundle wildcards):
Skill(plan-marshall:*)- diagnostic-patternsSkill(pm-plugin-development:*)- plugin-architecture, marketplace-inventory
Script Execution:
- Script paths resolved from
.plan/scripts-library.toon(system convention) - Permissions managed by
tools-setup-project-permissions
File Operations (covered by project permissions):
Read(//marketplace/**)- Read marketplace filesEdit(//marketplace/**)- Apply fixes to componentsGlob(//marketplace/**)- Discover components
Prompting Behavior:
- Safe fixes: Applied automatically WITHOUT prompts (no AskUserQuestion)
- Risky fixes: ONLY these require AskUserQuestion confirmation
- All other operations (read, analyze, glob) are non-prompting
Ensuring Non-Prompting for Safe Operations:
- All file reads/edits use relative paths within marketplace/
- Script paths resolved from
.plan/scripts-library.toon(system convention) - Skill invocations use bundle-qualified names covered by
Skill({bundle}:*)wildcards - AskUserQuestion is ONLY used for risky fix confirmations
Canonical invocations
The canonical argparse surface for doctor-marketplace.py. The plugin-doctor missing-canonical-block rule checks that this section is PRESENT, matching its heading only — the body is never read; manage-invocation-invalid derives its accept-set from a live --help walk rather than from this section. Consuming docs xref this section by name instead of restating the command inline. See pm-plugin-development:plugin-script-architecture cross-skill-integration.md § "Script invocation in documentation".
list-components
python3 .plan/execute-script.py pm-plugin-development:plugin-doctor:doctor-marketplace list-components \
[--bundles BUNDLES | --paths PATHS [PATHS ...]] [--marketplace-root MARKETPLACE_ROOT]
--bundles and --paths are mutually exclusive. list-components enumerates components only and runs no rules — use quality-gate to lint.
analyze
python3 .plan/execute-script.py pm-plugin-development:plugin-doctor:doctor-marketplace analyze \
[--bundles BUNDLES] [--type TYPE] [--name NAME] [--marketplace-root MARKETPLACE_ROOT] \
[--rules RULES] [--enable-argument-naming] [--enable-verb-chain]
fix
python3 .plan/execute-script.py pm-plugin-development:plugin-doctor:doctor-marketplace fix \
[--bundles BUNDLES] [--type TYPE] [--name NAME] [--dry-run] [--marketplace-root MARKETPLACE_ROOT]
report
python3 .plan/execute-script.py pm-plugin-development:plugin-doctor:doctor-marketplace report \
[--bundles BUNDLES] [--output OUTPUT] [--marketplace-root MARKETPLACE_ROOT]
quality-gate
python3 .plan/execute-script.py pm-plugin-development:plugin-doctor:doctor-marketplace quality-gate \
[--paths PATHS [PATHS ...]] [--marketplace-root MARKETPLACE_ROOT]
--paths scopes the file-anchored findings to the supplied component paths (the same invariant rule set runs). No flag = marketplace-wide. TWO classes are always reported unfiltered even under --paths: validate_extension_contracts, and any finding anchored at the marketplace ROOT — the anti-vacuity guards anchor that way, and the root is a parent of every scope dir, so the scope test could never admit one. The manually-maintained-mirror rules (provides-method-table-drift, literal-count-drift, canonical-enum-choices-drift, readme-skill-registration-drift, broken-relative-link, fenced-code-no-language) are part of this build-failing gate — they are registered in cmd_quality_gate (the markdown-mirror pair via the marketplace-wide analyze_markdown_mirror_rules pass) and also surface under analyze. Their findings carry absolute file paths, so --paths scoping applies to them uniformly.
test-conventions
python3 .plan/execute-script.py pm-plugin-development:plugin-doctor:doctor-marketplace test-conventions \
[--test-root TEST_ROOT] [--registry REGISTRY] [--marketplace-root MARKETPLACE_ROOT]
validate-contracts
python3 .plan/execute-script.py pm-plugin-development:plugin-doctor:doctor-marketplace validate-contracts \
[--extension-type EXTENSION_TYPE] [--skill SKILL] [--marketplace-root MARKETPLACE_ROOT]