Loop React Doctor

Loop: React Doctor

Drive every React app in the repository to a freshly verified react-doctor score of 100/100 — or to a documented, user-approved justification for whatever stands between the current score and 100. This is a run-until-done loop: it has a finish line, unlike scheduled maintenance loops.

Loop contract

Every run ends in exactly one of these states and must report which:

Hard rules for the whole loop:

• Never hide findings. No rule exclusions, ignore files or comments, severity/config relaxation, or deleting used behavior to silence a rule. Removing genuinely dead code that the dead-code analysis flags is a fix; deleting a live feature to make a finding disappear is cheating. The only exits for a finding are a verified fix or a user-approved justification.
• Pin the scanner version per run — every new run starts from latest. At baseline, resolve the current latest once (npm view react-doctor version), then invoke npx react-doctor@<version> for the rest of the run. This is not about freezing on an old version: each fresh run picks up whatever is newest. It is about intra-run measurability — @latest re-resolves on every invocation, and react-doctor is pre-1.0 and releases often, so a mid-run release with new rules would make a correct fix look like a regression or trip the stall detector.
• One root cause per iteration. A root cause may span many files (the same anti-pattern repeated); it may not bundle unrelated rules.
• Preserve unrelated work. Never commit, revert, or stash changes that existed before the loop started.

Phase 0 — Preconditions (fail fast)

1. Inventory app roots. Find every production React app: workspace packages and directories whose package.json depends on react (skip pure tooling/config packages). npx react-doctor@<version> -y scans all workspace projects; use --project to target specific ones. Confirm the inventory with the user if ambiguous.
2. Identify the verification commands for each app: typecheck, lint, tests, build — read them from package.json scripts or CI config; don't guess.
3. Green baseline. Run those commands once before any change. If they already fail, you can't attribute regressions to your fixes → BLOCKED, report what's broken.

If there are no React apps or the scanner won't run → BLOCKED.

Phase 1 — Baseline scan

For each app root, record:

npx react-doctor@<version> --json --verbose <dir>

• The pinned scanner version and scan timestamp.
• Per-app score and the full finding list (rule, file, count).
• Keep the JSON output (--json-out) as the baseline artifact.

Phase 2 — Plan by root cause

Group findings across apps by root cause (same rule + same underlying pattern), not by file. Rank by: score impact, blast radius of the fix (prefer contained), and risk of behavior change (prefer none). Work strictly from the top.

Phase 3 — Fix (one root cause per iteration)

Apply the smallest credible change that resolves the root cause everywhere it occurs. Behavior must be preserved — these are health/pattern fixes, not features. If a fix genuinely requires a behavior change or a risky refactor, stop and ask first.

Phase 4 — Verify (tiered, to control cost)

• After every fix: typecheck + the affected app's tests + re-scan the affected app(s) with the pinned version. The targeted findings are gone, the score did not drop anywhere, and no new findings appeared.
• Every ~5 fixes and before claiming any terminal state: the full battery — full scan of every app plus lint, full tests, and build for each. A terminal state claimed without a fresh full battery is invalid.

Keep the change only if its tier passes; otherwise revert and count the attempt.

Phase 5 — Stall detection and justification

• Two remediation attempts per root cause: if both fail verification, revert, mark it contested, move to the next root cause.
• Two consecutive iterations with no score improvement → stop: terminal state STALLED. Report the contested findings, what was tried, and why it failed. Do not grind.
• Justification path: when a finding is a false positive or flags an intentional, documented pattern, write the justification (rule, location, why the code is correct as-is) and present it to the user. Only user approval moves it off the worklist. Approved justifications make JUSTIFIED reachable — this is the pressure valve that keeps the 100/100 target from deadlocking against reality.

Final report

1. Terminal state (PERFECT / JUSTIFIED / STALLED / BLOCKED).
2. Score table: per app, baseline → final, with the pinned scanner version and both timestamps.
3. Fixes applied: root cause, files touched, and the verification tier output proving each.
4. Justifications approved by the user, in full.
5. Contested/stalled findings with attempt history, if any.

Fresh command output is the only acceptable proof. Show the final scan.

Re-running later

This loop finishes — but the score decays as both the code and the scanner evolve, and new rules in newer scanner versions are exactly the findings you want surfaced. The cheap maintenance variant: periodically (or in CI) run npx react-doctor@latest --score per app and compare against the last report:

• Same scanner version as the last report: a score drop means the code regressed → trigger a new full run.
• Newer scanner version: don't read a drop as a code regression — re-baseline with the new version (a fresh Phase 1) and treat any new findings as new work for a full run. Record the new version in that run's report.

Either way the maintenance check always scans with latest; pinning only ever applies inside a single remediation run.