Open Orchestrator

Appearance

This workflow shows how to use Open Orchestrator to investigate bugs efficiently, especially when the root cause is unclear.

The Scenario ​

You have a bug report: "Users report intermittent login failures"

The cause is unknown, so you need to investigate multiple potential causes in parallel.

Step 1: Create Investigation Worktrees ​

Create separate worktrees for different investigation angles:

bash
# Main investigation
owt new "Investigate login failures" -t bugfix

# Check authentication code
owt new "Check login auth code for race conditions" -t bugfix

# Check database queries
owt new "Check login database queries" -t bugfix

# Check session handling
owt new "Check login session handling" -t bugfix

Step 2: Delegate Investigation Tasks ​

Send targeted investigation tasks:

bash
# General investigation
owt send fix/investigate-login-failures "Investigate intermittent login failures:
1. Review recent changes to login flow
2. Check error logs for patterns
3. Identify common factors in failed logins"

# Auth-specific investigation
owt send fix/check-login-auth-code "Review authentication code:
1. Check password verification logic
2. Review token generation
3. Look for race conditions
4. Check for timing issues"

# Database investigation
owt send fix/check-login-database-queries "Check database-related issues:
1. Review user lookup queries
2. Check for connection pooling issues
3. Look for transaction timeouts
4. Analyze query performance"

# Session investigation
owt send fix/check-login-session-handling "Review session handling:
1. Check session creation logic
2. Review session storage
3. Look for concurrent session issues
4. Check session expiration handling"

Step 3: Monitor Progress ​

Open the Control Plane to watch investigations progress:

bash
owt
open-orchestrator · 4 rows · 14:32:08

NEEDS YOU
  fix/check-login-session    claude   Found issue

IN FLIGHT
  fix/investigate-login      claude   Reviewing logs
  fix/check-login-auth       claude   Analyzing auth
  fix/check-login-database   claude   Checking pool

Step 4: Review Findings ​

When a row surfaces in the NEEDS YOU section, it may have found something. Attach from the Control Plane:

  1. Navigate to the row with up/down (or j/k)
  2. Press a to attach
  3. Review the AI's findings
  4. Press Alt+s to return to the Control Plane

Step 5: Coordinate Findings ​

Once you have leads, coordinate:

bash
# Send findings to main investigation
owt send fix/investigate-login-failures "Session investigation found:
[paste findings]
Cross-reference with your findings"

# Focus remaining investigations
owt send fix/check-login-auth-code "Focus on session token validation -
potential race condition identified"

Step 6: Implement Fix ​

Once the cause is identified, create a fix:

bash
# Create fix worktree
owt new "Fix login race condition" -t hotfix

# Send fix instructions
owt send fix/login-race-condition "Implement fix for login race condition:
- Add mutex around session creation
- Implement retry logic for failed token validation
- Add logging for debugging"

Step 7: Test the Fix ​

Test in a separate worktree:

bash
# Create test worktree
owt new "Test login race condition fix"

# Send test instructions
owt send feat/test-login-race-condition "Create tests for login race condition fix:
- Test concurrent login attempts
- Test session creation under load
- Test token validation timing"

Step 8: Merge and Clean Up ​

After fix is verified:

bash
# Merge the fix
owt merge fix/login-race-condition

# Delete investigation worktrees
owt cleanup --days 0

Alternative: Single Worktree Investigation ​

For simpler bugs, use one worktree with the bugfix template:

bash
# Create with bugfix template
owt new "Fix broken login page" -t bugfix

# Send investigation task
owt send fix/broken-login-page "Investigate and fix: [bug description]"

When to Use Parallel Investigation ​

Use parallel investigation when:

  • Root cause is unclear
  • Multiple systems could be involved
  • Bug is critical and needs fast resolution
  • You have time to monitor multiple sessions

Use single worktree when:

  • Bug is localized
  • Cause is likely known
  • Simple fix expected
  • Limited monitoring capacity

Tips for Bug Investigation ​

  1. Start broad -- Cover multiple potential causes
  2. Monitor actively -- Watch the Control Plane for early breakthroughs
  3. Share findings -- Coordinate between investigations
  4. Focus quickly -- Once cause is found, converge
  5. Document -- Keep clear task descriptions for reference

See Also ​