/problem-solve

name: problem-solve
description: Use when the product misbehaves at runtime and the cause is unknown, especially when reproducing needs the human's device, eyes, or account. Do not use for a red test with an evident cause (stay in the implement loop) or for green-but-wrong against the locked prototype (that is an adjudication turn; the fix goes in the decision file).

X2 Problem Solve

Diagnosis, priced in human turns. Every "try this and tell me what you see" is a round trip the human pays for, and the metric counts it. The kernel prevents classes of defects; it does not diagnose novel ones, so when one appears, spend the fewest observation turns that honestly find the cause.

The pipeline

1. **Observe.** Get the observation and visual evidence first (screenshot, recording, exact repro). Find the last working state in git; the diff between working and broken is the search space. 2. **Hypothesize.** Form two to four falsifiable hypotheses, each with the data signature it predicts. Write the expected values down before instrumenting; a hypothesis without a predicted signature is a guess. 3. **Validate with one pass.** Design ONE instrumentation deployment that discriminates between all hypotheses simultaneously: five to ten log points, state transitions only, a filterable prefix, no per-render logging. Deploy instrumentation only, no other changes. One round trip. If the data says "working correctly" and the human says otherwise, the hypotheses are wrong, not the human's eyes; return to step 2. 4. **Confirm.** State the root cause in one sentence tied to measured data. If it does not fit in one sentence, it is not understood yet. 5. **Fix.** A failing regression test first where the defect is testable; then the fix through the normal implement loop; then remove every log point added in step 3. If the root cause is a specification defect, that is green-but-wrong: the fix goes in the decision file, never patched into source.

Anti-patterns

• No code changes before a confirmed cause. No layered speculative fixes; if you stack three

changes, you learn nothing. No trying the opposite of a failed fix without new data.

Human-turn contract

• No gate. The observation round trips are the turns; log each one to the ledger like any other,

and design the instrumentation so there is usually exactly one.

What this skill must NOT produce

• No fixes without a measured root cause, no instrumentation left behind, no commits without

direction.