chore: add MotorSignal Copilot instructions
This commit is contained in:
root
parent
2a8c438f07
commit
1e19f739bc
|
|
@ -0,0 +1,372 @@
|
|||
# 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:
|
||||
|
||||
1. Locate the existing implementation.
|
||||
2. Trace the relevant data flow.
|
||||
3. Inspect existing tests.
|
||||
4. Identify established invariants and compatibility requirements.
|
||||
5. 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:
|
||||
|
||||
1. reproduce or encode the failure
|
||||
2. make the smallest correction
|
||||
3. prove the corrected behavior
|
||||
4. 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:
|
||||
|
||||
1. correctness
|
||||
2. telemetry truthfulness
|
||||
3. regression risk
|
||||
4. data integrity
|
||||
5. persistence compatibility
|
||||
6. synchronization compatibility
|
||||
7. safety-related presentation
|
||||
8. tests
|
||||
9. maintainability
|
||||
10. 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.
|
||||
Loading…
Reference in New Issue