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.

7. Report Results

Summarize:

• What the bug was and why it happened
• What code was changed and why
• That the test now passes
• Any edge cases or related issues noticed
• For a tracking issue, which checklist items this PR completes and which items remain unchecked

Ask me to review the changes and iterate based on any feedback.

8. Open PR

Once I approve the fix, commit the changes and open a PR to main. Use the make-pr skill at .agents/skills/make-pr/SKILL.md for the PR body and command, and link the issue in the Development sidebar.

• For a regular issue, include Closes #NNNN in the description.
• For a tracking issue, use Part of #NNNN instead. Never use a closing keyword while any implementation-plan checkbox is unchecked.

9. Record Merged Tracking-Issue Progress

Update a tracking issue only after the corresponding PR has merged:

1. Verify the PR has a non-null mergedAt with gh pr view <number> --repo remix-run/remix --json number,url,state,mergedAt.
2. Fetch the issue body again immediately before editing so concurrent progress is preserved.
3. For each checklist item fully completed by the PR, preserve its wording, change [ ] to [x], and append a Markdown link to the merged PR, for example ([#1234](https://github.com/remix-run/remix/pull/1234)).
4. If a merged PR advances an item without completing it, append the PR link but leave the item unchecked. Check it only when its stated outcome is fully complete; include every merged PR needed to document the completed work.
5. Edit the issue with gh issue edit <number> --repo remix-run/remix --body-file <file>, then read it back with gh issue view and verify the checklist, links, and issue state.

If unchecked items remain, leave the tracking issue open and report the remaining items so another agent can continue from the issue. Before closing, fetch the current body once more and scan it for unchecked task-list items. If none remain, verify that every checked item links to the merged PR or PRs that completed it, then close the issue explicitly with gh issue close <number> --repo remix-run/remix. Never close a tracking issue with unchecked implementation-plan boxes.

If the workflow ends before the PR merges, leave its boxes unchecked and report that updating the tracking issue after merge is still required. Do not cite an open, draft, or closed-unmerged PR as completed work.