Add BUGBOT.md (#3173)

Author: buenaflor

.cursor/BUGBOT.md

@@ -0,0 +1,116 @@
+# PR Review Guidelines for Cursor Bot (Root)
+
+**Scope & intent**
+
+- High-level review guidance for the entire monorepo.
+- Optimize for **signal over noise**: only comment when there’s material correctness, security/privacy, performance, or API-quality impact.
+- If you find anything to flag, mention that you flagged this in the review because it was mentioned in this rules file.
+- Do not flag the issues below if they appear only in tests.
+
+**Reviewer style**
+
+- Be concise. Quote exact lines/spans and propose a minimal fix (tiny diff/code block).
+- If something is subjective, ask a brief question rather than asserting.
+- Prefer principles over nitpicks; avoid noisy style-only comments that don’t impact behavior.
+
+---
+
+## 0) Critical Issues to Flag
+
+> Use a clear prefix like **CRITICAL:** in the review comment title.
+
+### A. Security & Privacy
+
+- **Secrets / credentials exposure**: Keys, tokens, DSNs, endpoints, or auth data in code, logs, tests, configs, or example apps.
+- **PII handling**: New code that logs or sends user-identifiable data without clear intent and controls. These must be gated behind the `sendDefaultPii` flag.
+- **Unsafe logging**: Request/response bodies, full URLs with query secrets, file paths or device identifiers logged by default.
+- **File/attachments**: Large or sensitive payloads attached by default; lack of size limits or backoff.
+- **Debug code shipped**: Diagnostics, sampling overrides, verbose logging, or feature flags accidentally enabled in production defaults.
+
+### B. Public API & Stability
+
+- **Breaking changes**: Signature/behavior changes, renamed/removed symbols, altered nullability/defaults, or event/telemetry shape changes **without** deprecation/migration notes.
+- **Behavioral compatibility**: Silent changes to defaults, sampling, or feature toggles that affect existing apps.
+
+---
+
+## 1) General Software Quality
+
+**Clarity & simplicity**
+
+- Prefer straightforward control flow, early returns, and focused functions.
+- Descriptive names; avoid unnecessary abbreviations.
+- Keep public APIs minimal and intentional.
+
+**Correctness & safety**
+
+- Add/update tests with behavioral changes and bug fixes.
+- Handle error paths explicitly.
+- Avoid global mutable state; prefer immutability and clear ownership.
+
+**DRY & cohesion**
+
+- Remove duplication where it reduces complexity; avoid over-abstraction.
+- Keep modules cohesive; avoid reaching across layers for convenience.
+
+**Performance (pragmatic)**
+
+- Prefer linear-time approaches; avoid unnecessary allocations/copies.
+- Don’t micro-optimize prematurely—call out obvious hotspots or regressions.
+- Use streaming/iterables over building large intermediates when feasible.
+
+---
+
+## 2) Dart-Specific
+
+**Idioms & language features**
+
+- Avoid `!` (null assertion) on nullable targets; use guards or null-aware operators.
+- Follow Effective Dart style and documentation; document public symbols.
+- Consider modern Dart 3.x features (e.g., sealed classes) when they clarify the model.
+
+**Safety & async**
+
+- Avoid unawaited futures unless intentional and documented.
+- Cancel `StreamSubscription`s and dispose resources deterministically.
+
+**Concurrency & isolates**
+
+- For CPU-bound work with simple inputs/outputs, consider offloading to an **isolate**; avoid complex object graphs needing heavy serialization.
+
+**Tree-shakeability**
+
+- Avoid patterns that defeat tree shaking
+- Use const constructors/values where it makes sense to enable constant folding/canonicalization.
+- Instantiate optional features/integrations inside guarded branches (e.g., if (options.enableX) { ... }).
+- Prefer typed factories over dynamic/string lookups
+
+---
+
+## 3) SDK-Specific (high-level)
+
+**Tracing & spans**
+
+- Any span started must be **closed**.
+- For _automated_ instrumented spans, always set:
+    - `sentry.origin`
+    - `sentry.op` using a standard operation where applicable (see [Sentry’s list of standard ops](https://develop.sentry.dev/sdk/telemetry/traces/span-operations/)).
+
+**Structured logs**
+
+- For _automated_ instrumented structured logs, always set `sentry.origin`.
+
+**Initialization & error paths**
+
+- Wrap dangerous or failure-prone paths (especially during `Sentry`/`SentryFlutter` init) in `try/catch`, add actionable context, and ensure fallbacks keep the app usable.
+
+---
+
+## Quick reviewer checklist
+
+- [ ] **CRITICAL:** No secrets/PII/logging risks introduced; safe defaults preserved.
+- [ ] **CRITICAL:** Public API/telemetry stability maintained or properly deprecated with docs.
+- [ ] Spans started are always closed; automated spans/logs include `sentry.origin` (+ valid `sentry.op` for spans).
+- [ ] Dangerous init paths guarded; app remains usable on failure.
+- [ ] No `!` on nullable targets; async gaps guarded; resources disposed.
+- [ ] Tests/docs/CHANGELOG updated for behavior changes.