/react-doctor

Run react-doctor on the current project and act on the findings.

Mode

Argument: $ARGUMENTS — pick a mode (default diff when no arg given):

Arg	Command	When to use
diff	npx -y react-doctor@latest . --diff --json --offline	Default. Only files changed vs the base branch
staged	npx -y react-doctor@latest . --staged --json --offline	Pre-commit check on staged files
full	npx -y react-doctor@latest . --json --offline	Whole-codebase scan
score	npx -y react-doctor@latest . --score --offline	Just the number, nothing else

--offline skips telemetry. --json produces a parsable report so you can summarise cleanly — every other line of human output is suppressed when --json is set.

Steps

1. Detect: is this a React/Next/Vite/React Native project? If not (e.g. pure backend, plain Node lib), say so and stop — running react-doctor here would be noise.
2. Ensure .notes/react-doctor/ exists at the repo root (mkdir -p .notes/react-doctor). Verify .notes/ (or .notes/react-doctor/) is gitignored — check .gitignore and run git check-ignore -q .notes/react-doctor to confirm. If it isn't ignored, stop and warn before writing anything.
3. Run the command for the chosen mode and save the JSON report to:

   • .notes/react-doctor/<UTC-timestamp>-<mode>.json (timestamped archive)

   • .notes/react-doctor/latest.json (overwritten each run — handy for diffing)

   • Use tee to capture and parse in one pass, e.g.:

     mkdir -p .notes/react-doctor
     TS=$(date -u +%Y%m%dT%H%M%SZ)
     npx -y react-doctor@latest . --diff --json --offline \
       | tee ".notes/react-doctor/${TS}-diff.json" ".notes/react-doctor/latest.json"
     

   • For score mode, write plain text instead of JSON to .notes/react-doctor/score.txt.

4. Report the score first (e.g. 82 — Great), then group diagnostics by severity (error → warning → info) and by rule id. Cap at top 10 issues; mention the total if more.
5. For each issue: file path + line, the rule, one-line "why this matters."
6. End with the saved report path so the user can re-open it later (e.g. Report saved → .notes/react-doctor/20260511T123000Z-full.json).
7. Offer next actions:
   • Fix the top-severity issues now (ask before editing).
   • Add suppressions where genuinely warranted (// react-doctor-disable-next-line <rule>) — explain why before adding.
   • Drop a react-doctor.config.json ignore entry if a rule consistently doesn't apply to this codebase.
8. If score mode: print the number, save to .notes/react-doctor/score.txt, stop.

Notes

• Don't auto-fix. Always show findings first and confirm before editing.
• If the project has a react-doctor.config.json or "reactDoctor" key in package.json, mention any overrides that influenced the run.
• A regression-mode variant exists in the react-doctor skill (auto-triggers post-edit). This slash command is for explicit, user-initiated runs.
• Never reference saved reports from .notes/ in PRs, issues, or commit messages — that folder is intentionally untracked.