Bug Reporting Guide
Triage-ready reporting
Use this page when logging issues found during manual QA, regression testing, or release validation. Strong reports reduce back-and-forth and speed up debugging.
Good reports include
- exact reproduction details
- clear environment and network context
- evidence that preserves what the tester actually saw
What good bug reports include
This is the minimum context needed to make most bugs actionable.
- short title
- build version and build type
- device model and OS version for mobile issues
- platform: iOS, Android, Web, or local dev
- account email and role
- network state
- exact steps to reproduce
- expected and actual result
- frequency
- screenshot or recording if helpful
Queue and reconnect bugs usually need a little more context than ordinary UI bugs.
- pending count before and after the action
- whether manual sync was attempted
- whether the item existed after app relaunch
- whether the synced item appeared in the admin control plane
Hardware and permission bugs are hard to debug if the report does not describe the original device state.
- whether the permission had already been granted or denied
- whether it happened on simulator/emulator or physical device
- any relevant device capability context, such as biometrics enrollment
Suggested reporting flow
When possible, check whether the issue is repeatable before you leave the failing state behind.
Screenshots, recordings, timestamps, and exact entered values are easiest to preserve in the moment.
Use the shared bug report template so reports stay consistent across testers and environments.
Note whether the issue is new, intermittent, role-specific, or likely related to something already known.
Severity guide
| Severity | Definition | Examples |
|---|---|---|
| Blocker | Core use is stopped or data integrity is at risk | App will not launch, login impossible, offline capture lost |
| High | Major feature broken but app still usable in limited ways | Sync never clears, voice recording unusable, normal save flow broken |
| Medium | Important issue with workaround | Dashboard partly broken, event creation fails for some cases |
| Low | Minor issue or polish gap | Copy issue, spacing bug, small theming inconsistency |
Risk
Immediate escalation issues
- launch crash
- auth broken for valid users
- offline capture loss
- sync corruption or repeated duplicates
- app lock dead-end with no recovery
- wrong-user data exposure
Logs and evidence
These artifacts are usually enough to start good triage even without engineering tools.
- screenshot of the UI state
- screen recording of the repro path
- timestamp of when the issue occurred
- exact text entered, especially for capture and login flows
Use these when local builds or deeper debugging tools are available.
- Expo or Metro logs from local mobile runs
- iOS device logs from Xcode device console
- Android logs from
adb logcator Android Studio - browser console and network output for admin issues
- Vercel logs for backend or API failures when available
Before filing as new
Check whether the issue is already known or expected for the current build.
Do not hide repeats, but do note when a new test confirms an existing issue on a new build, device, or role.