Fix Issue

Fix Remix Issue

Fix the issue reported in the following GitHub issue: $ARGUMENTS

Branching

Bug fixes should start from a clean working tree. If there are changes, prompt me to resolve them before continuing.

Bugs should be fixed from main in a new branch using the format {author}/{semantic-branch-name} (i.e., brophdawg11/fix-route-pattern):

git fetch origin main
git branch {author}/{semantic-branch-name} origin/main
git checkout {author}/{semantic-branch-name}

Workflow

1. Fetch and Understand the Issue

Use gh issue view <number> --repo remix-run/remix or WebFetch to read the full issue.

Extract:

• Bug description and expected vs actual behavior
• Remix version and which package(s) are involved (e.g., remix/router, remix/route-pattern, remix/cli)
• Any code snippets in the issue
• Links to reproductions (StackBlitz, CodeSandbox, GitHub repo, etc.)
• Any implementation-plan checkboxes and the merged PRs already linked from them

If the issue contains implementation-plan checkboxes, treat it as a tracking issue and its checklist as the durable progress record:

• Do not redo checked work. Confirm linked PRs with gh pr view <number> --repo remix-run/remix --json state,mergedAt,url when their status matters.
• Choose one coherent set of unchecked items for the current PR. Do not expand the PR merely to finish the entire issue; long plans may require several PRs.
• State which checklist items the current PR intends to complete and which will remain for later work.

2. Validate the Reproduction

If there's a StackBlitz/CodeSandbox/online sandbox link:

• Use WebFetch to read the sandbox URL and extract the relevant code
• Identify the exact sequence of events that triggers the bug

If there's a GitHub repository link:

• Use WebFetch to read key files (package.json, relevant source files) from the raw GitHub URL
• Identify the reproduction architecture - routes, router, middleware, controllers, components, etc.

If no reproduction link exists:

• Search the issue comments with gh issue view <number> --repo remix-run/remix --comments
• Look for code snippets in comments
• Ask the user: "No reproduction was provided. Can you share a minimal reproduction or paste the relevant code?"

3. Identify the Affected Code

Remix is a pnpm monorepo with most product code under packages/<name>/src/. Each exports entry in a package's package.json maps to a top-level src/*.ts file; implementation lives in src/lib/. Use Grep, Glob, and the LSP tools to trace the relevant code paths and locate the owning package. See AGENTS.md for repo shape and cross-package import rules.

If the bug spans multiple packages, prefer fixing it in the owning package and avoid re-exporting the fix from another package.

4. Write a Failing Test

Tests are colocated with source as src/**/<name>.test.ts and run from source (no build step). Match the patterns in nearby test files and follow the conventions in the write-tests skill at .agents/skills/write-tests/SKILL.md.

Run a single test file inside the owning package:

cd packages/<package> && pnpm test src/**/<filename>.test.ts

Or use the changed-workspace runner (diffs against origin/main, includes uncommitted changes):

pnpm run test:changed

Write the test to reproduce the bug exactly — it must fail before the fix. Run it and confirm it fails.

5. Implement the Fix

• Make the minimal change needed to fix the bug
• Do not refactor unrelated code
• Confirm the fix addresses the root cause, not just the symptom
• Honor the platform stance: prefer Web APIs and standards-aligned primitives over Node-specific APIs
• Do not add cross-package re-exports or barrels in src/lib

Run the failing test again — it must now pass. Then validate locally:

pnpm run lint
pnpm run typecheck:changed
pnpm run test:changed

For broad cross-workspace changes, shared root config changes, or anything that could affect the whole repo, run the full validation:

pnpm test
pnpm run typecheck

6. Create a Change File

If the fix is user-facing, create packages/<package>/.changes/ on demand and add a change file there. Use the make-changes skill at .agents/skills/make-changes/SKILL.md — do not re-derive the naming, bump rules, or content rules here.

For 0.x packages, bug fixes are patch. For Remix export-only changes, update packages/remix/.changes/minor.remix.update-exports.md in place.