Lobster Debugging

A systematic 4-phase debugging framework to find root causes, eliminate flaky tests, and prevent regressions.

Install
cmdop skills install agensi-lobster-debugging

Lobster Debugging is a skill that enforces a four-phase debugging protocol on an AI agent, replacing ad-hoc guess-and-check repairs with a systematic, forensic approach to software defects.

Phase 1 (Investigation) directs the agent to perform a binary search of the codebase and add diagnostic instrumentation before any fix is attempted. Phase 2 (Synchronization) targets flaky timing problems by replacing arbitrary sleep timers with event-based waiting conditions. Phase 3 (Defense-in-Depth) moves beyond the single defect to introduce guards that prevent entire classes of similar vulnerabilities. Phase 4 (Verification) requires the agent to prove the fix handles edge cases and passes regression tests before the work is considered complete.

The skill enforces what its documentation calls the ‘Iron Law’: no code change is permitted until a root cause has been proven. This prevents common anti-patterns such as symptom-only patches and magic timeout values that leave technical debt behind.

This is a skill (not an MCP server), so it has no callable tools of its own; it operates as a behavioral framework that shapes how an AI agent reasons through a debugging task. It is most useful when an agent is being applied to complex, recurring, or timing-sensitive bugs where shallow fixes have already failed.

Use cases

  • Debugging intermittent race conditions or timing-sensitive test failures
  • Eliminating flaky tests by replacing sleep-based waits with event-based synchronization
  • Investigating a recurring bug that previous shallow fixes have not resolved
  • Adding defensive guards to prevent a whole class of similar defects after one is found
  • Conducting structured regression verification after a fix is applied
  • Guiding an AI coding agent through a root-cause investigation rather than a quick patch

When to use it

  • A bug keeps returning after multiple fix attempts
  • Tests are flaky due to timing or concurrency issues
  • Codebase has accumulated technical debt from symptom-only patches
  • An AI agent is being used for complex debugging and needs structured guidance
  • Root cause is unknown and systematic investigation is required

When not to use it

  • The task requires immediate, shallow hotfixes where investigation time is not available
  • The defect is trivial and its root cause is already fully understood
  • No AI agent is involved — this is a skill that shapes agent behavior, not a standalone tool
  • The project has no test suite, making Phase 4 verification impractical