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