plugin-doctor

Diagnose and fix quality issues in marketplace components with automated safe fixes and prompted risky fixes

SKILL.md

GitHub

Plugin 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.py command
  • Agents must record lessons via manage-lessons skill, not self-invoke commands (agent-lessons-via-skill)
  • Only doctor-marketplace.py is registered in the executor. _analyze.py, _validate.py, and _fix.py are separate verb-bearing entry points whose verbs are NOT doctor-marketplace subcommands; 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

  1. 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-inventory
    
  2. Load Component Reference (progressive disclosure)

    Read: references/{component}-guide.md

  3. Discover 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-roots op; Claude: .claude/{component}/)
  4. 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 --name to 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 a subdocuments key 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

  1. Auto-Apply Safe Fixes — Apply immediately using Edit tool without AskUserQuestion. Track success/failure.

  2. 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

  1. 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.

  2. 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 --help output 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 rules
  • llm-optimization-guide.md - Cross-cutting LLM optimization patterns
  • fix-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 (in plan-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 the verification-feedback envelope 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 of marketplace/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 in cmd_quality_gate so a drifted mirror fails the build, and also reported under analyze; fenced-code-no-language is auto-fixable; provides-method-table-drift detects drift between a plan-marshall-plugin extension.py provides_*() overrides and the SKILL.md "Extension API" table mirror — see scripts/_analyze_provides_method_table.py; canonical-enum-choices-drift compares a documented {a|b|c} enum in a ## Canonical invocations block against the flag's live argparse choices=; readme-skill-registration-drift compares a bundle README's skill enumeration against the set its plugin.json registers)
  • Content: checklist-pattern
  • PM-Workflow: pm-implicit-script-call through pm-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-patterns
  • Skill(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 files
  • Edit(//marketplace/**) - Apply fixes to components
  • Glob(//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]