8.3 KiB

Raw Blame History

MotorSignal — GitHub Copilot Instructions

Project

MotorSignal is a Flutter motorcycle telemetry application.

Treat telemetry, ride recording, performance timing, persistence, synchronization, and safety-related presentation as production-sensitive systems.

Prefer small, evidence-based changes over broad refactors.

Source of Truth

The protected master branch is the authoritative production baseline.

Do not:

commit directly to master
force-push
bypass repository rules or required CI
rewrite published history
modify unrelated files
silently change database schemas
silently change telemetry semantics

All implementation work should use a short-lived branch and pull request.

Investigate Before Changing Code

Before proposing or implementing a change:

Locate the existing implementation.
Trace the relevant data flow.
Inspect existing tests.
Identify established invariants and compatibility requirements.
Determine the smallest safe change.

Do not assume a feature is missing merely because its implementation is not immediately obvious.

Prefer extending existing architecture over creating parallel implementations.

Preserve Known-Good Behavior

A fix for one subsystem must not silently alter unrelated behavior.

Pay particular attention to:

telemetry cadence
GNSS freshness
ride distance
top speed
performance timing
lean/bank calculations
G-force calculations
heading
ride persistence
cloud/offline synchronization
dashboard presentation
field logging

If behavior must intentionally change, make the change explicit and add or update tests.

Telemetry Architecture

MotorSignal has a single authoritative telemetry pipeline.

Important invariants:

GNSS input is approximately 10 Hz.
Authoritative telemetry output is 20 Hz / 50 ms.
Do not introduce a competing telemetry pipeline.
Do not create additional independent sensor-fusion paths.
Preserve raw telemetry evidence.
Derived facts must only be produced from evidence that satisfies their validity requirements.

Sensor or GNSS wrappers must not make old evidence appear new.

GNSS Freshness

GNSS freshness is a canonical MotorSignal invariant.

The current boundary is:

gpsAgeMs <= 4000

Therefore:

3999 ms = fresh
4000 ms = fresh
4001 ms = stale

Do not change this boundary without an explicit task requiring it.

Fresh GPS requires valid coordinates.

Coordinates must:

exist
be finite
be within valid latitude/longitude ranges

Repeated telemetry frames containing the same underlying GPS fix must not refresh the GNSS freshness watchdog.

Stale GPS Behavior

Never present stale GPS-derived information as current evidence.

Expected behavior includes:

stale speed presentation uses -- rather than a frozen speed or false 0
derived ride metrics reject stale GPS evidence where appropriate
performance timing must not launch from stale evidence
GPS loss during active performance timing must follow the established abort behavior
recovery from an outage must not create catch-up distance
heading falls back to the established compass path when GPS course evidence is stale, absent, or unsuitable
maps may retain last-known coordinates only when clearly presented as stale/last-known
stale GPS must not be presented as an active GPS fix

Preserve these semantics unless an explicit requirement changes them.

Performance Timing

Performance timing is evidence-sensitive.

Do not allow stale GPS speed to:

arm a timer
launch a timer
continue a timing run as though GPS were current

When a READY timer loses valid speed evidence, preserve the established disarm behavior.

Moving GPS recovery must not automatically launch a previously armed run.

Fresh stationary evidence is required to re-arm where required by the existing state machine.

Preserve normal fresh-evidence launch and interpolation behavior.

Ride Metrics

Derived ride statistics must remain truthful.

Review freshness and validity before modifying calculations involving:

distance
top speed
moving time
stopped time
acceleration
braking
performance runs
elevation
high-speed events
heading

Do not substitute missing/stale evidence with fabricated values merely to keep the UI populated.

Persistence

MotorSignal currently uses Drift schema version 7.

Do not:

increment the schema version
add a migration
modify persisted schema semantics
regenerate schema-related production behavior

unless the task explicitly requires a database change.

Any schema change requires deliberate migration planning and compatibility validation.

Cloud and Offline Sync

Do not change synchronization, authentication, ownership, or offline-queue behavior as a side effect of unrelated work.

Preserve existing:

local persistence
offline behavior
ownership rules
sync semantics
retry behavior

Changes to these systems require explicit scope and dedicated validation.

UI Truthfulness

Prefer unavailable or stale states over misleading values.

Examples:

-- is preferable to a fabricated numeric value.
LAST KNOWN LOCATION is preferable to presenting stale coordinates as live.
NO GPS / equivalent established state is preferable to falsely indicating a current fix.

UI changes must preserve the semantic distinction between:

current
stale
unavailable
unsupported
error

Testing

Every behavioral change should have focused regression coverage when practical.

For bug fixes:

reproduce or encode the failure
make the smallest correction
prove the corrected behavior
verify nearby compatibility behavior

Pay particular attention to boundary tests.

For GNSS freshness, preserve explicit coverage around:

3999 ms
4000 ms
4001 ms

Do not weaken or delete tests merely to make a change pass.

Validation

Before declaring implementation complete, run the relevant focused tests.

For substantial Flutter changes, also run:

flutter analyze

and the appropriate regression/full test suite when practical.

Check diff hygiene with:

git diff --check

Do not claim a test, analyzer, build, or CI result that was not actually executed.

If validation cannot be run, state that explicitly.

GitHub Pull Requests

Pull requests targeting master must satisfy repository rules.

Required CI currently includes:

Analyze, test and debug build
Firestore ownership rules
Website build and regression tests
Waze relay tests
Backend API tests

Do not attempt to work around a failing required check.

Investigate the failure and determine whether it is caused by the proposed change.

Code Review

When reviewing MotorSignal changes, prioritize:

correctness
telemetry truthfulness
regression risk
data integrity
persistence compatibility
synchronization compatibility
safety-related presentation
tests
maintainability
style

Identify concrete defects rather than speculative rewrites.

When reporting an issue, explain:

the affected file/code path
the triggering condition
the resulting incorrect behavior
why it matters
the smallest reasonable correction

Do not request broad refactors unless they are necessary to resolve a demonstrated problem.

Scope Discipline

Stay within the requested task.

Do not opportunistically:

upgrade dependencies
reformat unrelated files
rename unrelated APIs
reorganize directories
rewrite stable architecture
introduce new frameworks
change CI
change authentication
change database schemas

unless explicitly required.

If a separate problem is discovered, report it separately instead of silently expanding scope.

Security

Never commit:

API keys
tokens
passwords
signing credentials
private certificates
production secrets

Do not weaken authentication, authorization, ownership rules, TLS, or secret handling to make development easier.

Completion Standard

A MotorSignal task is not complete merely because the code compiles.

Completion should establish:

requested behavior implemented
known-good behavior preserved
relevant tests passing
analyzer/build validation appropriate to the change
clean diff
no unrelated modifications
PR created from a dedicated branch
required CI passing
review findings resolved

When evidence is incomplete, report the uncertainty rather than assuming success.

8.3 KiB Raw Blame History