ragnar-pwninskjold/tech-snacks/react-refactor-tournament

react-refactor-tournament

Harvest React/Next.js performance refactor candidates straight from the vercel-react-best-practices skill, persist them as a tracked backlog keyed to the skill's real rule ids and impact tiers, rank the most contested tiers, then auto-fix the worst N (each in an isolated git worktree, with tests, committed but not pushed). This runs a bundled dynamic workflow that fans out skill-backed reviewers in parallel, then ranks and fixes under a hard 500k-output-token cap.

It only proposes and fixes on isolated worktree branches — it never pushes or merges, and it refuses to run at all if the vercel-react-best-practices skill isn't installed (no hand-written stand-in).

Requirements (check first)

This skill drives Claude Code's dynamic workflows feature. Before running, confirm:

• Claude Code v2.1.154+ and a paid plan (Pro/Max/Team/Enterprise) or API access.
• Workflows are enabled (/config → Dynamic workflows, or disableWorkflows not set,

and CLAUDE_CODE_DISABLE_WORKFLOWS unset).

• The `vercel-react-best-practices` skill is installed (project or user scope, .claude/skills

or .agents/skills). The workflow's first phase hard-checks this and aborts with an actionable message if it's missing — do not try to work around it.

If workflows are disabled, the Workflow tool call below will fail. If it does, tell the user to enable Dynamic workflows in /config and re-run — do not fall back to doing the review inline (the whole point is the parallel skill-backed harness + token cap).

Resolve the bundled workflow path

The orchestration script ships inside this plugin. Resolve its absolute path now — this works whether the plugin is installed at the personal, project, or plugin level, and regardless of the current working directory:

echo "${CLAUDE_SKILL_DIR}/../../workflows/react-refactor-tournament.workflow.js"

Use the path printed above as the scriptPath argument. Do not retype or guess it.

Gather inputs

Determine the workflow args before launching:

• `repoPath` (optional): absolute path to the repo root to review. Default to the current

project root (${CLAUDE_PROJECT_DIR} or the cwd) unless the user named a different repo.

• `n` (optional, default 3): how many top-ranked candidates the fix loop processes.

n=0 ranks only and skips the fix loop entirely.

• `scope` (optional): a glob/dir hint to constrain the review (e.g. src/components/dashboard).

Omit to auto-detect the React component areas.

If repoPath is ambiguous, ask the user once. Otherwise proceed with the current project.

Run it

Call the `Workflow` tool with:

• scriptPath: the absolute path resolved above.
• args: an object, e.g. { "n": 3 }, { "n": 0 } for rank-only, or

{ "n": 3, "scope": "src/components", "repoPath": "/abs/path/to/repo" }.

The run executes in the background across these phases:

1. Preflight — resolve the vercel-react-best-practices skill install path; abort if missing.
2. Scope — detect the framework and group React component dirs into disjoint review areas.
3. Discover — parallel reviewers invoke the skill and emit candidates keyed to real rule ids

(async-parallel, bundle-barrel-imports, …), with severity = the rule's impact: tier.

1. Backlog — dedup, assign stable ids, and write .pro-brown/refactors/BACKLOG.{json,md}.
2. Rank — order by impact tier (free); a single lazy tie-break ranker re-orders only an

over-subscribed tier (more candidates than remaining fix slots).

1. Fix (skipped when n=0) — fix the top N in isolated worktrees, write tests where feasible,

and commit each (no push, no merge).

Watch progress with /workflows. When it finishes, present the ranking + backlog paths to the user. Fixes live on isolated worktree branches — point the user at git worktree list / git branch to review, and let them merge/PR. Do not push or merge on their behalf.

What counts as a good candidate

A candidate qualifies only if it is a genuine violation of a specific vercel-react-best-practices rule, pinned to a real file:line, with ruleId taken from the skill (never invented) and severity taken from that rule's static impact:. Generic React hygiene the skill doesn't cover (naming, alt text, design-system nits) does not qualify. Quality over quantity — a clean codebase reporting zero candidates is a valid result.