By name: fix-perps-bug description: Debug and fix perps feature bugs maturity: stable
Fix Perps Bug
When To Use
- Bug report involving perps UI (positions, orders, trading, margins, TP/SL)
- Formatting/decimal display issues in perps screens
- Stream data not updating (prices, positions, orders)
- Order submission or validation failures
Workflow
Identify affected screen. Map the bug to a screen using the mobile-extension-map. Check if the screen exists on both repos or is missing on one.
Locate the code.
- Find the component/hook for that screen (see file paths in repo-specific section)
- Check if the bug involves a duplicated utility (see shared-package-analysis) -- if so, check both codebases
Check formatting. If the bug involves number display:
- Read formatting-rules knowledge
- Fix must follow the sig-dig rules, not hardcode decimals
Check stream hooks. If the bug involves stale/missing data:
- Verify the channel subscription is active and data transforms are correct
Fix the bug.
- Make the minimal change
- If fixing a duplicated utility, check the other repo's equivalent
- If the fix belongs in
@metamask/perps-controller, fix there (not in UI layer)
Write tests.
- Unit test the fix
- If formatting: test against the sig-dig table in formatting-rules
Validate.
- Run repo-specific validation (see below)
- Confirm the fix doesn't break the other repo's equivalent screen
Common Pitfalls
| Pitfall | Rule |
|---|---|
Adding .toFixed(2) on extension |
Use formatCurrencyWithMinThreshold as interim, target formatPerpsFiat behavior |
| Fixing a util that exists in both repos | Check the other repo's copy too |
| Ignoring missing screens on extension | Flag as known gap, don't create stub implementations |
| Hardcoding testIDs | Use the repo's convention (PascalCase selectors on mobile, kebab-case on extension) |