---
name: react-doctor
description: Use when finishing a feature, fixing bugs, or reviewing code in a React project. Trigger after making React changes to catch security, performance, and correctness issues early.
---

# React Doctor

Scans your React codebase for security, performance, correctness, and architecture issues. Outputs a 0-100 score with actionable diagnostics.

## When to Use

Run react-doctor **after every execution step** — after implementing code, after fixing bugs, after completing an initiative. This catches regressions before they ship.

## Usage

```bash
npx -y react-doctor@latest . --verbose --diff
```

- `--verbose` shows affected files and line numbers
- `--diff` only scans files changed vs the base branch (faster, focused)

To scan the full project (e.g. first run or major refactor):

```bash
npx -y react-doctor@latest . --verbose
```

## Workflow

1. **Run the scan** after making changes
2. **Fix errors first** (errors weigh more than warnings)
3. **Re-run** to verify the score improved
4. **Target score: 75+** (Great). Below 50 is Critical — must fix before committing.

## What It Checks

- **60+ rules** across: state & effects, performance, architecture, bundle size, security, correctness, accessibility
- **Framework-specific**: Next.js, React Native, Vite, Remix
- **Dead code**: unused files, exports, types, duplicates

## Interpreting Scores

| Score | Label | Action |
|-------|-------|--------|
| 75-100 | Great | Ship it |
| 50-74 | Needs work | Fix errors before committing |
| 0-49 | Critical | Must fix — do not commit |

## Configuration

If the project has a `react-doctor.config.json`, respect it. Otherwise the defaults are fine.

## Rules

- ALWAYS run react-doctor after completing initiative execution, before committing.
- Fix all **errors**. Warnings are best-effort.
- If the score drops below 50, do NOT commit until it's fixed.
- Do NOT modify `react-doctor.config.json` unless the initiative specifically requires it.
