thoughtbox:debug

Thoughtbox Debug

Guided debugging workflow built on the Ulysses surprise-gated protocol. Prevents reactive debugging spirals by forcing structured hypotheses after repeated surprises.

Core Mechanic: The S-Register

The S-register (surprise counter) is the discipline mechanism. Each unexpected outcome increments S. At S=2, stop and form a falsifiable hypothesis before continuing. This breaks the "try something, doesn't work, try something else" spiral.

Phase 1: Initialize

Start a debugging session. Define the problem and any constraints.

async () => {
  return await tb.ulysses({
    operation: "init",
    problem: "$ARGUMENTS",
    constraints: [
      // Hard limits on what you can change
    ]
  });
}

This starts a session with S=0. State the problem precisely — vague problems produce vague debugging.

Phase 2: Plan-Act-Assess Loop

Repeat this cycle for each investigation step.

2a. Plan with a pre-committed recovery action

Before investigating, declare what you will do AND what you will do if it fails. The recovery action prevents post-hoc rationalization.

async () => {
  return await tb.ulysses({
    operation: "plan",
    primary: "Check CI environment variables vs local .env",
    recovery: "If env vars match, check node version differences"
  });
}

2b. Execute

Run the primary action using whatever tools are needed (Read, Grep, Bash, etc.). Gather evidence. Do not interpret yet.

2c. Assess the outcome

Report whether the result matched your expectation.

async () => {
  return await tb.ulysses({
    operation: "outcome",
    assessment: "unexpected",  // or "expected"
    severity: "minor",         // or "major"
    details: "Env vars are identical — rules out config differences"
  });
}

• "unexpected" increments S. "expected" leaves S unchanged.
• Be honest. Calling a surprise "expected" defeats the protocol.

Phase 3: Forced Reflection (S=2)

When S hits 2, the protocol blocks further plan operations until you reflect. This is the mechanism that prevents spiraling.