Skip to content

Latest commit

 

History

History
207 lines (143 loc) · 5.16 KB

ISSUE_TRIAGE_GUIDE.MD

File metadata and controls

207 lines (143 loc) · 5.16 KB

Omi Issue Triage Guide

This document explains how issues are evaluated and prioritized in the Omi repository.

Omi is a memory-first product. The highest priority is protecting the core memory loop:

Capture -> Understand -> Remember -> Retrieve -> Act

Issues are not prioritized by popularity or reactions. They are prioritized by how much they impact this loop.

1. Core Principle

If Omi fails to capture or preserve memory, nothing else matters.

All triage decisions flow from this principle.

2. Omi Core Layers

Every issue must be mapped to one primary layer.

  • Capture: Audio recording, device pairing, permissions, battery stability, offline capture
  • Understand: Speech-to-text, language detection, diarization, transcription accuracy
  • Memory: Memory creation, syncing, storage, metadata, privacy boundaries
  • Intelligence: Summaries, insights, action items, reasoning across memories
  • Retrieval / Action: Search, asking Omi questions, tasks, exports, integrations
  • UX / Polish: UI layout, animations, wording
  • Docs / Tooling: Documentation, examples, developer tooling

These layers are not equal. Lower layers support everything above them.

3. Core Layer Weight

  • Capture: 5
  • Understand: 4
  • Memory: 4
  • Intelligence: 3
  • Retrieval / Action: 3
  • UX / Polish: 1
  • Docs / Tooling: 1

Issues affecting deeper layers are inherently higher priority.

4. Scoring Factors

4.1 Failure Severity (1-5)

How broken is the behavior?

  • 5: Completely broken
  • 4: Frequently fails
  • 3: Partially degraded
  • 2: Minor annoyance
  • 1: Cosmetic

4.2 Trust Impact (1-5)

Omi is a memory product, so trust is critical.

  • 5: Data loss or missing memories
  • 4: Incorrect or corrupted memories
  • 3: Inconsistent behavior
  • 2: Confusing but recoverable
  • 1: No trust impact

4.3 Frequency (1-5)

How often does this occur?

  • 5: Happens daily
  • 4: Weekly
  • 3: Regular but situational
  • 2: Rare
  • 1: Edge case

4.4 Maintenance Leverage (1-5)

Will fixing this reduce future issues?

  • 5: Eliminates a class of bugs
  • 4: Improves observability or stability
  • 3: Neutral
  • 2: Adds complexity
  • 1: Increases long-term maintenance burden

4.5 Cost & Risk (1-5) (subtracted)

Engineering complexity and rollout risk.

  • 5: Cross-device + backend + firmware
  • 4: Core pipeline change
  • 3: Moderate
  • 2: Small
  • 1: Trivial

5. Priority Score Formula

Priority Score = (Core Layer Weight * Failure Severity)

  • Trust Impact
  • Frequency
  • Maintenance Leverage
  • Cost & Risk

6. Priority Levels

  • = 30: P0 - Existential / must fix immediately

  • 22-29: P1 - Critical
  • 14-21: P2 - Important
  • < 14: P3 - Backlog

7. Lane Assignment (Routing)

After scoring, issues are assigned a lane.

  • Maintainer Now: High-risk, cross-system, or architectural changes
  • Community Ready: Clear scope, safe changes, suitable for contributors
  • Needs Info: Missing repro steps, logs, versions, or clarity
  • Park: Out of scope or low leverage

8. GitHub Labels

Issues are labeled with exactly one label from each category.

Layer Labels (cool blues)

Label Color Description
capture #0ea5e9 Audio recording, device pairing, BLE
understand #38bdf8 Speech-to-text, language detection
memory #06b6d4 Memory creation, syncing, storage
intelligence #2563eb Summaries, insights, action items
retrieval-action #1d4ed8 Search, questions, tasks, exports
ux-polish #60a5fa UI layout, animations, wording
docs-tooling #93c5fd Documentation, examples, dev tools

Priority Labels (warm reds/oranges)

Label Color Score Range
p0 #7f1d1d ≥30 (Existential)
p1 #dc2626 22-29 (Critical)
p2 #f97316 14-21 (Important)
p3 #f59e0b <14 (Backlog)

Lane Labels (greens/neutral)

Label Color Description
maintainer #14532d High-risk, cross-system changes
help-wanted #22c55e Open to contributors
needs-info #64748b Missing repro, logs, versions
parked #9ca3af Out of scope, low leverage

9. Triage Rules

  • Issues are signals, not commands. Community input is invaluable, but maintainers decide priority.
  • Popularity does not determine urgency. Reactions and comments do not outweigh core system health.
  • Data loss outranks feature requests. Any issue involving missing or corrupted memories is always high priority.
  • Capture failures outrank intelligence improvements. Omi must record before it can reason.

10. Examples

Example: Recording stops unexpectedly

  • Layer: capture (weight 5)
  • Severity: 5
  • Trust Impact: 5
  • Frequency: 4
  • Leverage: 4
  • Cost: 3
  • Score: 35 → p0 + maintainer

Example: Improve summary phrasing

  • Layer: intelligence (weight 3)
  • Severity: 2
  • Trust Impact: 1
  • Frequency: 3
  • Leverage: 2
  • Cost: 2
  • Score: 10 → p3 + help-wanted

11. Final Principle

Omi exists to remember life. Anything that threatens memory reliability takes precedence over everything else.

This guide exists to keep Omi reliable, trustworthy, and sustainable as it grows.