Skip to content
Skills Library
Programming · Analysis

thoughtbox:debug

/thoughtbox:debug

Trigger when debugging something unexpected — a test failure, surprising behavior, production incident, or any situation where initial attempts aren't working. Prevents the common agent failure mode of trying random things when stuck. Use when "the first fix didn't work", "this is behaving unexpectedly", "I'm stuck", "why is this happening", or after 2+ failed attempts to fix something.

Repository
thoughtbox ↗
Licence
MIT
Last repository change
10.07.2026

Assessment and security

90/ 100Class: good
Format15 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 10.07.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What it does and when to use it

Trigger when debugging something unexpected — a test failure, surprising behavior, production incident, or any situation where initial attempts aren't working. Prevents the common agent failure mode of trying random things when stuck. Use when "the first fix didn't work", "this is behaving unexpectedly", "I'm stuck", "why is this happening", or after 2+ failed attempts to fix something.

Triggers from the description

the first fix didnthis is behaving unexpectedlym stuckwhy is this happening

Arguments

/thoughtbox:debug [problem description]
Original author description

Trigger when debugging something unexpected — a test failure, surprising behavior, production incident, or any situation where initial attempts aren't working. Prevents the common agent failure mode of trying random things when stuck. Use when "the first fix didn't work", "this is behaving unexpectedly", "I'm stuck", "why is this happening", or after 2+ failed attempts to fix something.

How it works

  1. Core Mechanic: The S-Register
  2. Phase 1: Initialize
  3. Phase 2: Plan-Act-Assess Loop
  4. Phase 3: Forced Reflection (S=2)
  5. Phase 4: Resolution
  6. Phase 5: Check Status
  7. When to Use This
  8. Key Principle
Original SKILL.md headings · 143 lines, 597 words
SKILL.md preview
---
name: thoughtbox:debug
description: Trigger when debugging something unexpected — a test failure, surprising behavior, production incident, or any situation where initial attempts aren't working. Prevents the common agent failure mode of trying random things when stuck. Use when "the first fix didn't work", "this is behaving unexpectedly", "I'm stuck", "why is this happening", or after 2+ failed attempts to fix something.
argument-hint: "[problem description]"
user-invocable: true
allowed-tools: Read, Glob, Grep, Bash, Edit, Write, mcp__thoughtbox-cloud-run__thoughtbox_execute, mcp__thoughtbox-cloud-run__thoughtbox_search
---

# 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.

```javascript
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.

```javascript
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.

```javascript
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.

```javascript
async () => {
  return await tb.ulysses({
    operation: "reflect",
    hypothesis: "The CI failure is caused by a timing race — the database isn't ready when tests start",
    falsification: "If adding a 5-second delay before test execution doesn't fix it, this hypothesis is false"
  });
}
```

Requirements for reflect:
- `hypothesis`: a specific, testable explanation (not "something is wrong with X")
- `falsification`: explicit criteria that would prove the hypothesis wrong

Reflection resets S to 0. Continue the Plan-Act-Assess loop with a focused hypothesis to test.

## Phase 4: Resolution

When the bug is found and fixed:

```javascript
async () => {
  return await tb.ulysses({
    operation: "complete",
    terminalState: "resolved",
    summary: "Root cause: async database seeding wasn't awaited in test setup. Fix: added await to beforeAll hook."
  });
}
```

Terminal states:
- `"resolved"` — root cause found and fixed
- `"abandoned"` — not worth further investigation
- `"deferred"` — understood but fix postponed (file an issue)

## Phase 5: Check Status

Query the current protocol state at any point.

```javascript
async () => {
  return await tb.ulysses({ operation: "status" });
}
// Returns: S value, consecutive surprises, hypothesis count, history
```

## When to Use This

**Use Ulysses when:**
- Your first attempt did not work
- The behavior is genuinely surprising
- You have been going in circles
- The problem involves multiple interacting systems
- You catch yourself thinking "let me just try one more thing"

**Skip for:**
- Simple typos or obvious errors
- Well-understood failure modes
- Quick fixes that work on first try

## Key Principle

When debugging feels frustrating — when you want to "just try this one more thing" —
that is exactly when S=2 reflection would help most.
The protocol forces you to stop guessing and start hypothesizing.

Versions

The database has no other skills named thoughtbox:debug.

Identical content appears in 1 other GitHub folders. We show one copy with the highest score.

Database snapshot: 13.11.2026 · package version 1d36250ddc79 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100systematic-debugging
    Four-phase debugging framework for any technical issue. Use when encountering bugs, errors, or unexpected behavior. Prevents random fix attempts.
  • 100systematic-debugging
    Use when debugging a failing test, build error, or runtime issue that isn't immediately obvious. Guides a 4-phase root cause analysis instead of random fix attempts.
  • 100debug
    Systematic debugging methodology for build failures, test failures, unexpected agent behavior, and drift-related errors. Use when a build fails, tests fail unexpectedly, an agent produces wrong output repeatedly, or sync drift is detected. Triggers on: "debug", "fix build",…
  • 100ask-codex
    Consult OpenAI Codex for investigation, debugging, or code review. Use when user explicitly asks to "ask codex", "check with codex", "codex review", or as a last resort when stuck after 4+ failed attempts at debugging, investigation, or bug fix and completely out of ideas. Codex…
  • 100debug
    Finds and proves the root cause of a failure before any fix is attempted, and escalates to the architect agent after two failed fixes. Use when a test, a verify step, a land or a running feature fails and the cause is not already proven, when a fix did not work, when a failure…
  • 100debugging-protocol
    Systematic 4-phase debugging: (1) understand the failure by reading the complete error and reproducing it, (2) find working examples to compare against, (3) test one hypothesis at a time with a single change, (4) fix the root cause and verify with tests. Includes the Three…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.