React Router RFC Implementer

Implement React Router RFC

Implement the RFC from the following GitHub discussion: $ARGUMENTS

Branching

RFC implementations should start from a clean working tree. If there are uncommitted changes, stop and ask me to resolve them before continuing.

• If you are already on a named branch that is at the same HEAD as main, use that branch.
• Otherwise, create a branch from main using the format {author}/rfc-{semantic-name}:

  git branch {author}/rfc-{semantic-name} main
  git checkout {author}/rfc-{semantic-name}

Workflow

1. Fetch and Understand the RFC

Use WebFetch to read the discussion URL. If a GitHub discussion number is given instead of a URL, construct: https://github.com/remix-run/react-router/discussions/<number>

Extract:

• Problem being solved: what pain point does this RFC address?

• Proposed API: exact function signatures, hook names, types, option shapes

• Affected modes: Declarative / Data / Framework / RSC Data / RSC Framework

• Breaking changes: does this change or remove existing public API?

• Open questions: anything explicitly marked as unresolved, "TBD", or asked as a question in the proposal

• Status: are there linked tracking issues? Look for links to other github issues and read them to see if there is additional context.

  gh issue view <number> --repo remix-run/react-router

2. Evaluate Community Feedback

Fetch all comments from the discussion:

Use WebFetch on https://github.com/remix-run/react-router/discussions/<number> and scroll through the full thread. Look for:

• Concerns or objections raised by community members or maintainers
• Alternative proposals or API shape suggestions
• Edge cases raised that the proposal does not address
• Positive signals — repeated praise for a specific approach signals it's the right direction
• Maintainer responses — Ryan Florence, Michael Jackson, or other core team members clarifying intent

Summarize the community sentiment into:

• Points of consensus (safe to proceed)
• Points of contention (need resolution before implementing)
• Unanswered questions from the original proposal

3. Resolve Outstanding Questions

Before writing any code, present me with a numbered list of every unresolved question — from both the RFC itself and from community feedback. For each question:

• State the question clearly
• Summarize relevant community input
• Offer a recommended answer with reasoning

Ask me to confirm, override, or skip each question. Do not proceed to implementation until all questions are either answered or explicitly deferred.

Example format:

## Unresolved Questions

1. **Should `useRouterState()` accept a path argument for scoped matching?**
   Community feedback: 3 comments in favor, 1 against (concerns about complexity).
   Recommendation: Yes — scoped matching improves type safety for nested routes.
   → Your decision: [confirm / override / defer]

2. **What should happen when the path doesn't match the current location?**
   Recommendation: Return `null` for active state (consistent with `useMatch()`).
   → Your decision: [confirm / override / defer]

Save the resolved decisions to a scratch file at tasks/rfc-decisions.md for reference during implementation.

4. Plan the Implementation

Before writing code, produce a concise implementation plan covering:

• New types/interfaces to add
• New functions/hooks to implement and their file locations
• Existing APIs to deprecate (mark with @deprecated JSDoc + console warning in dev)
• Whether a future flag is needed (see §5 below)
• Test files to create or extend (unit and/or integration)
• Changeset bump level (minor for new features, major for breaking changes behind a future flag that is now defaulted on)

Present the plan to me and wait for approval before implementing.

5. Future Flags for Breaking Changes

If the RFC changes or removes existing public API behavior, it must ship behind a future flag which will start with an unstable_ prefix.

Future flag pattern:

1. Add the flag to FutureConfig in packages/react-router/lib/router/utils.ts:

   export interface FutureConfig {
     // existing flags...
     unstable_myNewBehavior: boolean;
   }

2. Gate the new behavior on the flag:

   if (router.future.unstable_myNewBehavior) {
     // new behavior
   } else {
     // legacy behavior
   }

3. Document the flag in docs/upgrading/future-flags.md if it exists.

New additive APIs (no behavior change to existing code) do not need a future flag.