Collaboration checkpoint

Collaboration Checkpoint

When to use this skill

• The same error or test failure recurs after two or more fix attempts
• A change "should work" but does not, and the agent cannot explain why
• The user says "you're missing something", "that's not the problem", or repeats a hint
• The agent's confidence is low, or it is oscillating between competing hypotheses
• More than one debugging path has been abandoned without a definitive conclusion
• The diff is growing while the failure stays the same

If any of these are true, run this skill before writing another line of code.

Core principle

When the agent is looping, more code is the wrong move. The cheapest information available is the user's mental model of the system — and the agent rarely has it. A checkpoint replaces "try again" with "stop, summarize what is known, surface the gap, and ask." Humility is not a tone; it is an operation: state your model, state your confidence, and invite correction.

Procedure

This skill has two halves. Run both, in order.

Part A — Stagnation recognition

1. Stop editing code. No further fixes until the checkpoint completes. If a fix is half-applied, revert or stash it.
2. Write an Attempts Log (template below) listing every fix tried in this session for this issue.
3. From the log, extract three lists:
   • Solid evidence — facts proven by reproducible observation
   • Assumptions — beliefs not yet proven
   • Ruled out — hypotheses disproven, with the evidence that disproved them
4. Form at most three new hypotheses. Rank them by which one, if true, would best explain all the solid evidence — not by which one is easiest to test.

Part B — Humility trigger / rubber duck mode

5. State the agent's current model of the system in plain language. Two to four sentences. No jargon shortcuts.
6. State the agent's confidence as low, medium, or high, and identify where confidence is lowest.
7. Ask the user a direct question:

   "Here is my model of how this works. Which part of this does not match how the system actually behaves?" Wait for the answer. Do not propose fixes yet.

8. Compare the user's mental model to the agent's, line by line. List every divergence. Divergences are usually where the bug lives.
9. Only after the models are reconciled, propose the next experiment — not the next fix. An experiment produces evidence; a fix assumes the cause is already known.

Attempts Log template

| # | Hypothesis                          | Action taken              | Result          | What it ruled out                |
|---|-------------------------------------|---------------------------|-----------------|----------------------------------|
| 1 | Stale token in cache                | Cleared cache, re-ran     | Same 500 error  | Cache freshness as sole cause    |
| 2 | Missing await in handler            | Added await on refresh    | Same 500 error  | This handler as sole cause       |
| 3 | ...                                 | ...                       | ...             | ...                              |

Required output format

A single message containing, in order:

## Attempts Log
<table>

## Solid evidence
- ...

## Assumptions
- ...

## Ruled out
- ...

## My current model
<2–4 plain sentences>

## My confidence
<low | medium | high> — weakest at: <which part>

## Question for the user
<one direct question that targets the weakest part of the model>

The agent posts this and waits. No code edits until the user responds.

Stop conditions / escalation triggers

• Three fix cycles without progress — invoke this skill immediately, do not wait for a fourth
• The user repeats the same hint twice — the agent's model is wrong, not its code
• Hypotheses keep contradicting each other — the Solid evidence list is too short; gather evidence before guessing again
• The agent cannot state its model in plain language — it does not have a model yet; stop and read the relevant code
• After the user answers, the agent's instinct is to "just try it" — re-run Part B; the models are not yet reconciled

Short examples

Good model statement:

I believe the websocket reconnect handler is being registered twice because the React effect runs on every render. I am confident about the double registration. I am uncertain whether the second registration is the one that drops the auth header or whether both share the same header.

Bad model statement (rejected):

Something is wrong with the websocket.

The agent has no model and is guessing. Stop, read the code, and try again.

Good question for the user:

Do you expect the reconnect handler to share auth state with the original connection, or is it supposed to re-authenticate from scratch on each reconnect?

Bad question (rejected):

Any ideas?

This extracts no signal from the user's intuition. Ask about a specific divergence in the model.

Good next experiment (after reconciling models):

Add a log line at handler registration that prints the auth header reference identity. Run one reconnect cycle. If the two handlers print different identities, the second is being constructed without the latest auth context — and that explains the 401.

Bad next step (rejected):

Try removing the second registration and see if it works.

That is a fix, not an experiment. It produces no diagnostic information if it fails.