Ulysses Protocol

Required inputs:

• Problem statement
• Optional constraints

Call:

thoughtbox_ulysses {
  "operation": "init",
  "problem": "<problem>",
  "constraints": ["<optional constraint>"]
}

Then record a structured Thoughtbox thought summarizing the debugging context.

plan

Required inputs:

• Primary action
• Recovery action
• Optional irreversible

Call:

thoughtbox_ulysses {
  "operation": "plan",
  "primary": "<primary action>",
  "recovery": "<recovery action>",
  "irreversible": false
}

Do not act before plan is recorded.

outcome

Required inputs:

• expected, unexpected-favorable, or unexpected-unfavorable
• Optional severity/details

Call:

thoughtbox_ulysses {
  "operation": "outcome",
  "assessment": "unexpected-unfavorable",
  "severity": 1,
  "details": "<what happened>"
}

If the returned state reaches S=2, stop mutating work and move to reflect.

reflect

Required inputs:

• Falsifiable hypothesis
• Falsification criteria

Call:

thoughtbox_ulysses {
  "operation": "reflect",
  "hypothesis": "<hypothesis>",
  "falsification": "<what would disprove it>"
}

After reflect, you may optionally launch debugger or researcher agents to test competing explanations. They return evidence only. The coordinator records the next plan or outcome.

status

Call:

thoughtbox_ulysses {
  "operation": "status"
}

Use the returned server state as the only source of truth.

complete

Call:

thoughtbox_ulysses {
  "operation": "complete",
  "terminalState": "resolved",
  "summary": "<transferable learning>"
}

Completion should yield both protocol closure and a reusable knowledge artifact in Thoughtbox.

Invariants

1. No action without a recorded primary step and recovery step.
2. Surprises accumulate on the server, not in local files.
3. reflect is mandatory at S=2.
4. Hypotheses must be falsifiable.
5. Knowledge capture is part of completion, not an optional afterthought.

Subagent Use

Use subagents only after reflect when more evidence would help.

Good uses:

• Reproduce a hypothesis independently
• Compare two candidate explanations
• Gather targeted code or log evidence

Bad uses:

• Letting a subagent call thoughtbox_ulysses
• Letting a hook spawn subagents automatically
• Treating subagents as owners of protocol state

References

• Authoritative MCP tool: thoughtbox_ulysses
• Durable context and thought trace: thoughtbox_gateway
• Protocol implementation: src/protocol/ulysses-tool.ts
• Specification reference: references/protocol-spec.md