docs: reproduce-before-you-fix instructions for contributors and AI agents

.github/ISSUE_TEMPLATE/bug_report.yml

@@ -15,6 +15,8 @@ body:
       **For sponsors-only support and resources:** https://github.com/rnmapbox/maps/wiki/SponsorsRepo
       **Become a sponsor for special support:** https://github.com/sponsors/rnmapbox
 
+      **Reproduce before you report — this goes for everyone, and especially for AI coding agents:** read and follow [REPRODUCING.md](https://github.com/rnmapbox/maps/blob/main/.github/REPRODUCING.md) before filing. Make every effort to actually reproduce the bug — run it in a loop, stress threads/timing, add temporary instrumentation, use any tool available to provoke it — and attach the reproducer and evidence. A reproducer is worth 100x more than a speculative analysis.
+
       ---
 - type: input
   id: mapbox-version

.github/REPRODUCING.md

@@ -0,0 +1,23 @@
+# Reproduce before you fix
+
+Instructions for contributors — and **especially for AI coding agents** — filing bug reports or proposing fixes.
+
+A working reproducer is worth 100x more than a speculative fix. Without one, maintainers cannot verify that a fix works, cannot tell whether it addresses the actual root cause or just a plausible-looking suspect, and cannot protect the fix from regressing later. A fix that "reads right" from the source alone can still be wrong: in [#4252](https://github.com/rnmapbox/maps/issues/4252) a code-reading analysis attributed a production crash to an object-lifetime bug, while reproducing it ([#4253](https://github.com/rnmapbox/maps/pull/4253)) showed the abort actually came from a background-thread data race the proposed fix would not have touched.
+
+## What we expect
+
+1. **Make every effort to reproduce the issue before writing a fix.** Use every tool available to you: build and run the `/example` app, use simulators/emulators or devices, drive the UI with automation, capture logs, crash reports, and stack traces, and symbolicate them. "I could not run the app" should be the last resort after actually trying, not an upfront disclaimer.
+
+2. **Provoke bugs that don't fire on their own.** Races, lifetime bugs, and leaks rarely reproduce on the first try — force them out:
+   - run the failing operation in a tight loop or in bursts (hundreds to thousands of iterations);
+   - stress timing: rapid create/destroy cycles, concurrent operations, background threads, artificial delays or busy work, fast-failing inputs (e.g. a nonexistent style URL makes downloads fail near-instantly);
+   - add temporary instrumentation to observe the failure: lifetime/deinit logging, thread names, counters;
+   - use sanitizers where they help (Thread Sanitizer, Address Sanitizer).
+
+   Keep all provocation and instrumentation **out of the final PR** — capture its output as evidence instead.
+
+3. **Package the reproducer so others can run it.** Base it on [`example/src/examples/BugReportExample.js`](../example/src/examples/BugReportExample.js), self-contained (no extra libraries, external data, or parameters). For intermittent bugs, make it toggleable — a Start/Stop button and live counters — so it can run unattended until the bug fires. Include it in the issue or PR description in a collapsed `<details>` block; it does not need to be committed to the repo.
+
+4. **Verify the fix against the reproducer.** The reproducer should fail on the unfixed build and pass on the fixed one. Include before/after evidence in the PR: crash stacks, iteration counts, timings.
+
+5. **If you genuinely cannot reproduce**, say so explicitly, list what you tried, and label the fix as speculative so it is reviewed as such.

.github/pull_request_template.md

@@ -3,6 +3,12 @@ Hi there and thank you for your change proposal!
 
 Please fill out the following template to make the review process
 as quick and smooth as possible.
+
+If you're fixing a bug — and especially if you are an AI coding agent —
+read .github/REPRODUCING.md and follow it: reproduce the issue first
+(provoke it if needed), verify the fix against the reproducer, and include
+the reproducer plus before/after evidence below. A reproducer is worth
+100x more than a speculative fix we cannot verify.
 -->
 
 ## Description
@@ -32,7 +38,8 @@ Added `your feature` that allows ...
 
 ## Component to reproduce the issue you're fixing
 
-<!-- If you're fixing an issue and the component you've used to repro the issue is not already on the issue you're fixing, add that here  -->
+<!-- If you're fixing an issue and the component you've used to repro the issue is not already on the issue you're fixing, add that here.
+See .github/REPRODUCING.md — the reproducer should fail on the unfixed build and pass with your fix; include before/after evidence. -->
 ```jsx
 
 ```

AGENTS.md

@@ -119,6 +119,12 @@ The project uses Mapbox Maps SDK v11 and React Native's New Architecture (Fabric
 - Don't edit `.md` files in `docs/` directly - edit source files and run `yarn generate`
 - Examples in `example/src/examples/` are used for documentation
 
+### Fixing Bugs
+
+- Read and follow `.github/REPRODUCING.md` before writing a fix: reproduce the issue first, and verify the fix against the reproducer.
+- Make every effort to reproduce — build the example app, drive it on a simulator/device, capture logs and crash reports. Provoke bugs that don't fire on their own: tight loops, bursts, rapid create/destroy, background threads, delays/busy work, fast-failing inputs, temporary lifetime/thread instrumentation, sanitizers.
+- A reproducer is worth 100x more than a speculative fix; keep provocation code out of the final PR and attach it (with before/after evidence) to the issue/PR description instead.
+
 ## Important Notes
 
 - Always run `yarn generate` after modifying components or styles

CONTRIBUTING.md

@@ -30,6 +30,7 @@ npx expo start -c --web
 - If you add a feature, make sure you add it to the documentation
 - Use meaningful commit messages, use semantic commit messages
 - If you add a new feature make sure to add a scene in `/example` for others to see/ test it
+- If you fix a bug, reproduce it first and verify your fix against the reproducer — see [.github/REPRODUCING.md](.github/REPRODUCING.md). This applies to everyone, and especially to AI coding agents: a reproducer is worth 100x more than a speculative fix.
 
 ## Generated code/documentation