playbooks

home / skills / basedhardware / omi / debug-mode

debug-mode skill

/.cursor/skills/debug-mode

This skill helps you debug tricky bugs by guiding hypothesis generation, instrumentation, reproduction, analysis, and targeted fixes.

npx playbooks add skill basedhardware/omi --skill debug-mode

Review the files below or copy the command above to add this skill to your agents.

Files (3)
SKILL.md
1.8 KB
---
name: debug-mode
description: "Debug mode workflows and best practices for troubleshooting bugs, regressions, and performance issues. Use when debugging tricky issues that standard agent interactions struggle with."
---

# Debug Mode Skill

Specialized workflows for Debug Mode: hypothesis generation, log instrumentation, runtime analysis, and targeted fixes.

## When to Use

Use this skill when:
- Debugging tricky bugs that are hard to reproduce
- Investigating regressions
- Analyzing performance issues
- Troubleshooting race conditions
- Standard agent interactions aren't working

## Debug Mode Workflow

### 1. Exploration and Hypothesis

**Agent will:**
- Explore relevant code paths
- Generate hypotheses about root causes
- Identify potential failure points
- Plan instrumentation strategy

### 2. Instrumentation

**Agent adds:**
- Log statements at key points
- State tracking (variables, buffers, connections)
- Timing information
- Error condition checks

### 3. Reproduction

**You provide:**
- Detailed reproduction steps
- Expected vs actual behavior
- Error messages and stack traces
- Context about when bug occurs

### 4. Analysis

**Agent analyzes:**
- Collected logs
- State transitions
- Timing patterns
- Error conditions

### 5. Fix

**Agent makes:**
- Targeted fix based on evidence
- Minimal changes to address root cause
- Verification of fix
- Cleanup of instrumentation

## Best Practices

1. **Provide detailed context**: More information = better hypotheses
2. **Reproduce consistently**: Follow steps exactly
3. **Multiple reproductions**: For intermittent bugs
4. **Review fixes**: Ensure root cause addressed
5. **Clean up**: Remove instrumentation after fix

## Related Resources

- Rule: `.cursor/rules/agent-modes.mdc`
- Command: `/debug`
- Agent: `.cursor/skills/debug-mode/agents/debug-specialist.md`

Overview

This skill provides a practical Debug Mode workflow for troubleshooting tricky bugs, regressions, and performance problems in AI wearable apps. It focuses on structured hypothesis generation, targeted instrumentation, reproducible reproduction steps, and evidence-driven fixes. The goal is to produce minimal, verifiable changes that address root causes while preserving system stability.

How this skill works

The skill inspects code paths and runtime behavior, proposes hypotheses for failure modes, and recommends where to add logging, state snapshots, and timing metrics. It guides you through reproducing issues, collects and analyzes logs and state transitions, and suggests targeted code changes and verification steps. After a verified fix, it helps you remove temporary instrumentation to keep the codebase clean.

When to use it

  • Diagnosing hard-to-reproduce bugs or intermittent failures
  • Investigating regressions after updates to app, model, or runtime
  • Analyzing persistent performance bottlenecks or timing issues
  • Troubleshooting race conditions, deadlocks, or resource leaks
  • When standard agent interactions fail to surface root causes

Best practices

  • Provide complete context: reproduction steps, environment, and recent changes
  • Instrument minimally and strategically: key variables, boundaries, and timings
  • Reproduce issues repeatedly to collect reliable evidence
  • Make small, reversible fixes and verify against collected logs
  • Remove or gate instrumentation after validation to avoid noise

Example use cases

  • A wearable audio transcription stops mid-session under high load—use instrumentation to capture buffer state and timing
  • Intermittent connection drops between mobile app and BCI hardware—add state tracking and error checks to isolate the failure window
  • A regression after a Flutter upgrade causes UI freezes—trace event timing and main-thread blocking
  • Performance degradation after model update—measure end-to-end latency and per-stage timings to locate the bottleneck
  • Race condition during device pairing—log sequence of events and verify ordering to craft a targeted fix

FAQ

How much instrumentation should I add?

Start with focused logs around suspected failure points: inputs, state transitions, and timing boundaries. Expand only if evidence is insufficient.

What if the bug is intermittent and hard to reproduce?

Automate reproduction runs, collect extensive contextual logs, and add probabilistic sampling for low-overhead tracing to capture rare events.