superpowers-doctor

Superpowers Doctor

Modeled after: brew doctor — but meaner. Created: 2026-03-18 | Upgraded: 2026-03-20

Wrong skill? Structural lint only → skill-health-check. Writing/authoring skills → skill-authoring. Updating skills → update-superpowers.

Industrial-grade integrity check. Iterates across every installed skill with 27 checks across 4 severity tiers. No skill escapes scrutiny.

When to Use

• User says "run superpowers doctor" or "check skill health"
• Before releasing a new skill version
• After bulk skill edits to catch regressions
• Periodic deep-clean audit
• After install.sh to verify deployment integrity
• When skills behave unexpectedly (wrong triggers, missing content)
• After cloning on Windows/WSL to detect CRLF or BOM issues

Modes

Mode	Behavior
Default (no flags)	Report-only — detect and display all findings
--fix-safe	Fix non-destructive issues only (sync drift, CRLF, BOM, name mismatch, stale checkout)
--fix	Detect + auto-fix all issues including destructive (junk cleanup) — excludes orphan removal
--fix --yes	Auto-fix all without confirmation prompt — excludes orphan removal
--fix --purge-orphans	Also remove orphaned installs (skills not in any source repo)
--summary-only	One-line pass/fail (used by post-install hook)

11 checks are auto-fixable (3, 8, 9, 12, 14, 16, 17, 18, 19, 20, 27). The remaining 12 require human judgment.

Graduated intervention:

• --fix-safe fixes: 3 (name), 9 (drift), 16 (ref drift), 17 (CRLF), 18 (BOM), 19 (stale checkout pull), 27 (agent drift) — non-destructive
• --fix adds: 12 (deprecated triggers), 14 (junk removal), 20 (dirty checkout stash+clean) — destructive
• --purge-orphans adds: 8 (orphan removal) — requires explicit opt-in because locally-created skills are not necessarily garbage

All fixes create backups in ~/.codex/doctor-backups/YYYY-MM-DD_HH-MM-SS-PID/ before modifying anything. Backups are verified for completeness before any fix is applied.

How to Execute

# Run from superpowers-plus repo root
./tools/doctor-checks.sh              # Diagnose only
./tools/doctor-checks.sh --fix-safe   # Fix non-destructive issues
./tools/doctor-checks.sh --fix        # Fix all auto-fixable issues
./tools/doctor-checks.sh --fix --yes  # Fix all without prompts

The script auto-discovers source repos via SPP_SOURCE_DIR / SP_OVERLAY_SOURCE_DIR env vars or well-known paths. See references/checks.md for the full check summary table.

Severity Tiers

Tier	Meaning	Action
🔴 CRITICAL	Skill is broken or corrupted	Fix immediately
🟠 ERROR	Skill is degraded	Fix before next release
🟡 WARNING	Quality/hygiene issue	Fix when convenient
🔵 INFO	Recommendation	Consider improving

Cross-Platform Notes

• WSL/Windows: Doctor detects CRLF line endings (Check 17) and UTF-8 BOM (Check 18). Both are auto-fixable.
• NTFS mounts: Doctor warns when skills are installed on /mnt/c/... where chmod is silently ignored.
• Prevention: The repo includes .gitattributes enforcing LF line endings. Configure git config --global core.autocrlf input on Windows.

Failure Modes

Failure	Recovery
No source repos found	Set SPP_SOURCE_DIR / SP_OVERLAY_SOURCE_DIR env vars
YAML parsing fails	The parse failure IS the finding (Check 1)
Network unavailable	Checks 13, 19 skipped — re-run when online
Backup fails	Fix is skipped automatically — resolve disk space or permissions
Skills on NTFS mount	Move to native Linux path (WSL only)
python3 not found	Check 21 (TODO smoke test) skipped
node not found	Check 22 (reviewer-dispatch) skipped
git < 2.13	Check 20 stash fallback uses git stash save