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.