| name | bug-triage |
| description | Use this skill when triaging, investigating, or fixing a reported bug. Covers reproduction, root cause analysis, fix implementation, and regression testing. Use when assigned a bug report or when investigating unexpected behavior. Don't use for new features (use backend-feature or frontend-feature) or reviews (use code-review).
|
Bug Triage
Investigate and fix bugs in AirwayLab following the triage protocol.
Triage Steps
1. Reproduce
- Understand the reported behavior vs expected behavior
- Identify which component/module is affected
- Check if it's a known issue (search existing issues/comments)
2. Root Cause Analysis
- Read the relevant code before proposing changes
- Check if the bug is in a protected module (lib/analyzers/, lib/parsers/, workers/)
- If yes: document the bug and escalate to CTO/board. Do NOT fix.
- Trace the data flow to find where behavior diverges
- Check for common gotchas:
- Float32Array serialisation issues
- Null oximetry data not handled
- Hardcoded sampling rates
- EDF date parsing (2-digit years)
- Duration-weighted averaging edge cases
- localStorage 4MB cap exceeded
3. Write a Test First
- Write a test that catches the bug before fixing it
- Test goes in
__tests__/<module-name>.test.ts
- The test should fail before the fix and pass after
4. Fix
- Minimal change. Fix the bug, don't refactor surrounding code.
- One concern per PR, max 400 lines
- Follow all coding conventions (TypeScript strict, Tailwind, etc.)
5. Verify
npx tsc --noEmit && npm run lint && npm test && npm run build
6. Report
Comment on the issue with:
- Root cause (one sentence)
- Fix description (what changed and why)
- Test added (name and what it covers)
- Regression risk (low/medium/high with reasoning)
Severity Classification
| Severity | Definition | Action |
|---|
| Critical | Core analysis produces incorrect results | Escalate immediately. Revert if merged. |
| High | Feature broken, no workaround | Fix in current heartbeat |
| Medium | Feature degraded, workaround exists | Schedule for next heartbeat |
| Low | Cosmetic, minor UX issue | Create task, prioritize normally |
Fix-on-Fix Rule
If a fix introduces a new bug, STOP. This is a red flag. Escalate to CTO. Do not stack fixes.
