Figure It Out

figure-it-out

This skill is the executable arm of ~/.claude/rules/figure-it-out.md — Directive 8 ("dispatch a team to investigate in parallel when stuck"). It does not replace the rule; it operationalizes it. The agents are a library, not a team that all fires at once: the front-end always runs, then 3-4 thinkers are selected for the problem type, then the empirical gate proves the fix.

Two locked principles govern the whole flow:

1. Empirical verification is the arbiter of correctness — never a judge's opinion. The Verifier's run is the verdict. Nothing is "solved" on belief.
2. Any agent can raise a CANDIDATE FLAG, but the flag fast-paths to the empirical gate — it does not exit the skill. A believed fix jumps to Builder→Verifier to be proven. Confirmed → commit. Refuted → Debugger analyzes the failure, the pipeline resumes.

When this fires (the trigger gate)

Fire ONLY if at least one holds:

• The same approach has failed twice (per loop-prevention.md).
• You are about to write terminal-skip language — "doesn't work," "isn't supported," "is gated," "needs a workaround," "is impossible" — especially if the user has counter-evidence (a video, a prior success, a doc).
• The problem is genuinely open-ended with no clear approach.

When this does NOT fire

• First failure — just try again.
• A problem you can solve in one or two more reads — just solve it.
• Clear check: if cause→effect is self-evident and you already know the fix (Cynefin Clear), apply it; do NOT dispatch. This skill is an escape hatch, never the default. Firing it on a trivial problem is strictly worse than solving it directly.

Control flow

The orchestrator is THIS session (the main thread). It selects agents, runs the Hamster pre-check, enforces the 3-4 simultaneous cap, handles Verifier delegation requests, and commits. Dispatch agents via the Agent tool (default substrate — see Substrate rubric).

TRIGGER GATE → fire only if stuck per above. CLEAR CHECK → if we know the fix, apply it, don't dispatch.

— Phase 0: front-end (ALWAYS, sequential; ANY step may raise a CANDIDATE FLAG → jump to S11) —
S1  Search-external → researcher: has someone ALREADY solved/documented this publicly? A found fix raises a candidate flag.
S2  Recall-internal → historian: have WE solved OR FAILED this before? Surface prior solutions AND dead-ends.
S3  Reframe        → reframer: is this the right problem, or a better adjacent one?
S4  Deconstruct    → constraint-questioner: decompose the ORIGINAL and the reframed problem; segment every premise; pass all versions down.
S5  Verify         → researcher: verify EVERY ledger row across all versions (real/false/stale/unverifiable).
S6  Rebuild        → first-principles: strip fallen premises, restate the MINIMAL TRUE PROBLEM. Dissolves it → candidate flag.

— Phase 1: targeted attack (only if no candidate yet) —
S7  Diagnose       → classify the rebuilt field T1-T6 + Cynefin gate (type + complexity + why).
S8  Select squad   → pick 3-4 thinkers from the library for the type; justify each. Hamster pre-check (read-only thinkers don't conflict).
S9  Think          → thinkers run (innovator / analogist / debugger as fit); each may raise a CANDIDATE FLAG.
S10 Stress-test    → skeptic attacks the leading candidate(s); advisory verdict. Survivors → the gate.

— Phase 2: the empirical gate (the fast-path target; the ONLY exit to "solved") —
S11 Build          → builder (CONDITIONAL — skip if the fix uses an existing thing): construct the candidate in _scratch/.
S12 Prove          → verifier: exercise the built-or-existing thing by any means; the observed result is the verdict.
                     • Verifier returns a DELEGATION REQUEST → you (orchestrator) dispatch the named helper, feed the result back.
                     • Verifier flags a real irreversible/outward action needed → surface its confirmation request to the user; wait.
                     • FAIL → debugger post-failure root-cause → loop back to S11 (rebuild) or S9 (rethink). CAP ≤3 build-fail loops.
S13 Make-actionable→ pragmatist: sequence the PROVEN fix to maximize Claude automation; minimize the user's manual steps.
S14 Decide         → commit (Chairman): the PROVEN fix + the single concrete next action + named blind spots.

The candidate-flag mechanism

Any agent may end its report with a CANDIDATE FLAG ("I believe this is the fix: …"). When one fires:

• Jump straight to S11 (Builder — skip if nothing to build) → S12 (Verifier proves it).
• Confirmed → S13 (Pragmatist) → S14 (commit). A fast but earned exit.
• Refuted → the Debugger does post-failure root-cause, and the pipeline resumes from where the flag was raised (not from the start). The false belief is caught here, never shipped.

This is how the skill gets speed AND certainty: the thinking short-circuits, but correctness is always settled by a run.

Problem taxonomy (S7 — diagnose the rebuilt field)

Pick ONE primary type (note a secondary if close). It routes the thinker subset; Builder/Verifier/Pragmatist are the Phase-2 back-end for every type. Cap 3-4 simultaneous; justify each pick.

Cynefin gate (a modifier, not a 7th type): Clear → apply the known fix, don't dispatch; Complicated → analyze, fewer/sequential; Complex → probe with safe-to-fail builds, never one big analysis; Chaotic → stabilize first.

Substrate rubric (how to dispatch)

Hard gate: VS Code panel without Agent-Teams env flags → subagents. Subagents-as-default is the safe failure mode.

Convergence rubric

The final commit is always you (the Chairman), committing to what the Verifier PROVED. Correctness is never settled by opinion. Cap debate/rework at ≤3 rounds (round 1 carries most value, round 3 is noise); after the cap, commit-with-residual.

Orchestrator responsibilities (don't skip these)

• Hamster pre-check before any parallel dispatch: enumerate each agent's file/scope set; the read-only thinkers don't conflict, but the Builder and Verifier (both write _scratch/) run sequentially, never in parallel.
• Each spawn brief is lean and self-contained: task / files / pattern / verify, plus the 4-field return contract (sources / findings+paths / snippet locations / confidence+gaps). The agents have no prior context.
• Treat every agent output as a CLAIM until the Verifier confirms it (trust boundary). Record external-source URL + date.
• Handle Verifier delegation requests: when the Verifier asks for a capability it lacks, dispatch the named helper yourself and feed the result back — an unhandled request is a dead end.
• Surface the Verifier's confirmation prompts for real irreversible/outward actions; wait for the user before letting it act.
• Honest-failure output (per exhaust-before-skipping.md): if unresolved after the ≤3-loop cap, return a SPECIFIC unknown-map — each rung tried + its concrete failure mode. Banned: bare "impossible / can't / gated," and "it depends."

Anti-patterns (do not do)

• Firing the skill on a first failure or a trivial problem (use the trigger gate + Clear check).
• Skipping Phase 0 — the front-end is where the buried assumption gets caught.
• Exempting any premise from questioning because it is "obvious."
• Dispatching the whole library at once — select 3-4 thinkers and justify each.
• Letting a candidate flag EXIT without the Verifier proving it.
• Settling correctness by opinion (Skeptic verdict, team confidence) instead of a Verifier run.
• Dumping manual steps on the user that Claude could automate (the Pragmatist prevents this).
• Returning "it depends" or a bare "impossible" instead of a committed answer or a specific unknown-map.