React Doctor

React Doctor v2 - CLI aimed at catching low-quality React patterns across Next.js, Vite, and React Native; marketed as fixing apps quickly when agents ship sloppy React.

Current Version Snapshot

Source: GitHub API; npm registry, 2026-07-02

Invoke

npx react-doctor@latest

Run after major agent-authored UI refactors or before release branches. Complements Ultracite/oxlint (style + correctness) with React-specific diagnostics. Part of the Doctor Pattern - the enforcement layer between per-file lint and CI that catches systemic drift. Source: User announcement summary, 2026-05-11

Kevin's executable route is now skills/engineering/react-doctor/SKILL.md. Use the skill when the task is to run, fix, and report a React Doctor or React Security Doctor pass; use this page for capability facts, version snapshots, and historical evidence.

The reviewed /react-doctor launch video shows the intended agent-skill flow inside Claude Code: run /react-doctor fix my code, scan issues such as synced state from props, missing error boundaries, unnecessary rerenders, large components, and direct DOM mutation, then move from a low/critical score to 100 / 100 Great. Treat the video as workflow evidence, while npm/GitHub remain the version authority. Source: X/@aidenybai, 2026-05-26; Source: npm registry and GitHub API, 2026-07-02

Aiden's own "Codex /goal + React Doctor" endorsement is text-only, but it is useful as source-author confirmation for the workflow Kevin already uses: set a goal, run React Doctor, fix until the score is clean, and preserve review/no-shortcut guardrails around the loop. No new skill or version check is needed for this row; execution remains skills/engineering/react-doctor/SKILL.md. Source: X/@aidenybai, 2026-05-27

Diagnostics

Six categories scored independently, aggregated to a 0-100 health score:

1. State & Effects - derived state in useEffect, fetch in useEffect, unstable deps
2. Performance - unnecessary re-renders, missing memoization, constructed context values
3. Architecture - component nesting, barrel file bloat, circular imports
4. Security - dangerouslySetInnerHTML, unvalidated inputs, exposed secrets
5. Accessibility - missing ARIA, click handlers without keyboard, image alt text
6. Dead code - unused exports, unreachable branches, phantom dependencies

Source: npm react-doctor, 2026-05-17

Scoring methodology

The 0-100 score uses a fixed formula, verified against the docs: Source: react-doctor "Understanding Scores", https://www.mintlify.com/millionco/react-doctor/guides/understanding-scores, 2026-06-13

score = 100 − 1.5 × (unique error rules) − 0.75 × (unique warn rules)   # rounded, clamped to ≥0

The defining choice: it counts unique rule violations, not total occurrences — a rule broken 200 times costs the same as once, which incentivizes systemic fixes over whack-a-mole. Errors weigh 2× warnings, so fixing error rules first yields the biggest score gains. This formula and the unique-rule principle are the parts worth copying into any home-grown doctor — see Doctor Pattern. Source: react-doctor docs, 2026-06-13

Fix loop

npx react-doctor . --fix runs an agent loop (the reusable methodology behind "run until score 100"): errors are fixed serially with a typecheck after each and a revert-on-failure; warnings are fixed in a batch validated once at the end (falling back to serial to isolate an offender); the scan re-runs to confirm the score rose. It also estimates the post-fix score (assuming ~85% of errors / ~80% of warnings are auto-fixable) and tracks score history over time. Source: react-doctor agent playbook, https://www.react.doctor/prompts/react-doctor-agent.md, 2026-06-13

The independent Codex prompt bookmark is useful because it captures the operator-facing version of the same loop: set a goal to run npx react-doctor@latest, fix issues until the score reaches 100, and explicitly forbid shortcuts. The replies add the missing caution: follow with cleanup, reasoning/model quality matters, and do not let agents loose on production code without review. Kevin's executable route is therefore still react-doctor plus no-sus-code-doctor/review, not blind auto-fix. Source: X/@weswinder, 2026-05-29

Agent Integration

React Doctor installs rules directly into Cursor and Claude Code agents. After running npx react-doctor@latest, it can emit a .cursor/rules/react-doctor.mdc or .claude/rules/react-doctor.md so the agent avoids the same anti-patterns on future edits. This creates a feedback loop: doctor diagnoses → rules prevent → next doctor run scores higher. Source: X/@aidenybai, 2026-05-08

GitHub Action (CI gate)

Jun 2026 launch thread promotes a GitHub Action to block bad React from prod: run locally first (npx react-doctor@latest), then install the Action from the open-source repo linked in @aidenybai's thread. 815 likes, 580 bookmarks. Source: X/@aidenybai thread, 2026-06-11

The docs route has two install shapes. The CLI path is npx react-doctor@latest install, which can add .github/workflows/react-doctor.yml and a doctor package script. The manual Action path uses millionco/react-doctor@v2, checks PR changed files, posts a sticky summary/inline comments when permissions allow it, and scans main pushes for score trend. First rollout should use advisory mode (blocking: none, optionally scope: full) to map old debt before enforcing the default changed-file gate. Source: React Doctor GitHub Actions docs, 2026-06-30

Fits Doctor Pattern Layer 3: between agent rules and Playwright CI. Pair with Ultracite for style + React-specific health score on every PR.

React Security Doctor (Jun 2026)

@aidenybai shipped React Security Doctor — the Security diagnostic category (category 4 above) promoted to a first-class mode that scans for and fixes security exploits in a React app (dangerouslySetInnerHTML sinks, unvalidated inputs, exposed secrets, unsafe URL/href handling). Same CLI, runs locally or in GitHub Actions, fully open source. Source: X/@aidenybai, 2026-06-15

npx react-doctor@latest          # security scanning included

• Repo: github.com/millionco/react-doctor (13.2K stars as of 2026-06-29)
• Docs: react.doctor/security

For Kevin this is the React-specific security complement to repo-wide agent vuln scanners (deepsec), and it slots into the same detect -> triage -> fix -> verify loop the wiki's own Security and Review Skills / Self-Maintaining Systems machinery uses — now for the security class on React surfaces. Workflow fit: add the GitHub Action as a CI gate on Dedalus/loop frontends; pair with Doctor Pattern Layer 3.

When to Run

• After agent-authored React edits (5+ component files touched)
• Before merging React PRs in CI
• On monorepo bootstrap to baseline health
• When React app feels sluggish or buggy without obvious cause

---

Timeline

• 2026-07-04 | Reviewed Aiden's text-only "Codex /goal + React Doctor" bookmark. Added it as author confirmation for the existing /goal fix-until-clean loop; no new tool, version snapshot, or duplicate skill was needed. Source: X/@aidenybai, 2026-05-27
• 2026-07-02 | Deep-reviewed the /react-doctor launch demo and refreshed current version authority. react-doctor remains 0.5.8 latest, but the dev channel and repo HEAD moved to d241e51; repo count is 13,335 stars / 422 forks. No duplicate skill created because skills/engineering/react-doctor/SKILL.md already owns execution. Source: X/@aidenybai, 2026-05-26; Source: npm registry and GitHub API, 2026-07-02
• 2026-06-30 | Deep-reviewed the GitHub Action and React Security Doctor bookmark rows. Repaired local media, embedded the CI/security artifacts, verified react-doctor@0.5.8, millionco/react-doctor HEAD 0b64af58b16329c5cae7a210463d2842e34b150d, and kept the executable skill route active rather than creating a duplicate doctor. Source: X/@aidenybai, 2026-06-11 and 2026-06-15; npm registry; GitHub API
• 2026-06-30 | Deep-reviewed the Wes Winder Codex /goal prompt bookmark and local image. Decision: preserve it as independent evidence for the score-to-100 loop and operator caution, update this page and the dev-tools hub, but create no new skill because skills/engineering/react-doctor/SKILL.md already owns execution. Source: X/@weswinder, 2026-05-29; Source: npm/GitHub, 2026-06-30
• 2026-06-29 | Promoted skills/engineering/react-doctor/SKILL.md so the React Doctor / React Security Doctor workflow is executable from the runtime skill index. Rechecked npm: react-doctor@0.5.8 remains latest. Source: npm registry, 2026-06-29
• 2026-06-30 | Added the original React Doctor v2 launch tweet artifact and refreshed npm/GitHub snapshot: react-doctor@0.5.8, plugin packages 0.5.8, repo HEAD 0b64af58b16329c5cae7a210463d2842e34b150d. Source: X/@aidenybai, 2026-05-08; npm registry and GitHub API, 2026-06-30
• 2026-06-29 | Refreshed the version snapshot: react-doctor@0.5.8, latest GitHub release oxlint-plugin-react-doctor@0.5.8, repo 13.2K stars, pushed 2026-06-29. Source: GitHub API; npm registry, 2026-06-29
• 2026-06-15 | @aidenybai launched React Security Doctor — security-exploit scanning/fixing as a first-class mode of react-doctor (CLI + GitHub Actions, open source; docs at react.doctor/security). Repo millionco/react-doctor at 12.8K stars. Source: X/@aidenybai, 2026-06-15
• 2026-06-13 | Documented the verified scoring formula (100 − 1.5e − 0.75w on unique rules) and the errors-serial/warnings-batch fix loop from react.doctor docs. This methodology was folded into Doctor Pattern and applied to Security and Review Skills (0-100 score + history). Source: react.doctor docs, 2026-06-13
• 2026-06-12 | GitHub Action promoted in launch thread — "Prevent bad React code from breaking prod"; install locally first (npx react-doctor@latest), then CI gate. Open source repo linked in thread. 580 bookmarks on announcement tweet. Source: X/@aidenybai, 2026-06-12
• 2026-05-27 | @ParthJadhav8's Codex goal prompt made the fix loop explicit: run npx react-doctor@latest and keep fixing until score 100. 2,214 likes, 3,498 bookmarks. Source: X/@ParthJadhav8, 2026-05-27
• 2026-05-26 | /react-doctor launched as an installable agent skill (@aidenybai, 5,967 likes, 6,866 bookmarks). The Codex "/goal run npx react-doctor@latest and fix until score 100" fix-loop pattern went wide (@ParthJadhav8, @weswinder). Source: X/@aidenybai, 2026-05-26
• 2026-05-17 | Promoted to Tier 1. Expanded with diagnostic categories, agent integration details, and Doctor Pattern context. Source: User, 2026-05-17
• 2026-05-08 | React Doctor v2 launched. Announced by @aidenybai (5161 likes). Works with Next.js, Vite, React Native. "Your agent writes bad React code, this catches it." Source: X/@aidenybai, 2026-05-08
• 2026-05-11 | Registered in wiki tooling layer. Source: User, 2026-05-11