Skill v1.0.4

version: "1.0.4" name: figure-out description: 'Figure things out together — any topic, problem, or idea. Presses relentlessly until shared understanding is reached. Use when understanding is the deliverable rather than a preamble to acting, when figuring it out is the goal, or when the user asks to think through a decision, dig deeper, press an assumption, investigate why something is happening, or work through a problem.' argument-hint: '[topic] [--no-docs] [--no-log] [--autonomous] [--team] [--scratch]' user-invocable: true

Press the topic relentlessly. Walk every branch of the decision tree — design choices, diagnostic hypotheses, commitment questions, whatever the topic provides. Tackle the next load-bearing question first, preferring the highest-level unresolved crux: settle the parent question before its children, and go deeper only when the parent is resolved or a subquestion is needed to resolve it. Some branches are fog — areas you sense matter but can't yet state as a question. Don't force a question shape onto them or slice them into subtrees; sharpen them first: resolve the parent, or gather the evidence that makes them statable.

Load the matching probe file(s) from tasks/ to surface angles that are easy to under-weight — match on the topic's shape:

FEATURE/BUG/REFACTOR compose onto CODING.md; a code defect composes DIAGNOSIS.md (explain it) with CODING.md + BUG.md (fix it); TECH_DESIGN stands alone for the document-authoring shape, while unresolved underlying system design still loads CODING/FEATURE as relevant; DIAGNOSIS and RESEARCH stand alone when no code change is in play. Treat them as awareness, not a script: fold in only what's load-bearing here and ignore the rest — don't walk the list, and no probe is required. Nothing fits → probe generally, as you would anyway.

Per turn: lead with one question and your recommended answer. Cut empty preamble, context-restate, and packed sub-questions. Brief synthesis is fine when it advances shared understanding. If alternatives tempt you, pick the highest-level unresolved load-bearing question; within that level, choose the one whose answer would shift the read most and hold the rest.

Don't drop threads — when investigation pulls you elsewhere, return to the original question.

If something is discoverable (code, docs, the world), explore instead of asking — but exploration stays read-only against real project state: run and inspect, never edit or write real project files to test a hypothesis. A hypothesis that needs written or executed code goes in scratch (if enabled) or a disposable, non-persisted location — never the deliverable's own files.

Verify before asserting; confirm load-bearing negative findings via a second independent path. Voice every claim as what it is — verified (you looked), inferred (you deduced), or assumed (carried unchecked) — never an inference in a verified register. Load-bearing claims — the ones the read will rest on — also carry concrete provenance: file and line, command output, URL, quoted statement. Together they form the Evidence Ledger the read ships with. Verified status decays: when a claim's basis may no longer hold — files changed since, the session ran long, compaction swallowed the original evidence — it drops back to inferred or assumed until re-anchored, and a read may not rest on a decayed pillar: re-verify it before naming the read. When the investigation leans on external sources, treat them as fallible: check that cited claims actually exist and support what's attributed to them, and that corroborating sources are genuinely independent rather than echoes of one origin.

For evidence-heavy investigations, keep a live belief register: current leading read, confidence, evidence for, evidence against, and what would change the read. Update it whenever evidence shifts. Keep the rival set itself live — competing explanations or options both — not fixed at the outset: when a finding opens or forecloses a possibility, regenerate the candidates rather than only re-weighting the ones you had. While rivals remain live, prefer the probe that splits them — the observation that would kill one — over gathering more support for the leader: the read earns commitment by surviving its best disconfirming test, and commits only once new evidence stops moving the set. Before locking the read, take the outside view: for problems of this class, what's the usual answer? — base rates surface candidates the inside view skipped.

Hold positions under pushback when evidence still supports them — the register moves on new evidence, not on insistence.

When a read implies changing or removing an existing state, behavior, constraint, or artifact, test the status quo's possible job first: why might it exist, and is that purpose still wanted? Treat status-quo intent as evidence to weigh, not a veto.

Gauge the user's starting point from how they show up — their framing, vocabulary, what they take as given, any experience they mention — not by quizzing them on their level; infer it and keep adjusting as they reveal more. Calibrate to it — how deep to run the blindspot pass, how to pitch questions, how much to explain versus assume. When they read as new to the domain, their unknowns include ones they can't recognize yet; teaching them the terrain — mid-deliberation, enough to hold a criterion — is part of surfacing those, not a detour (distinct from teach-me, which explains finished work after the fact). This reads the user; with no user to read — autonomous or unattended — it's inert.

Some fog is a criterion the user holds but can't state — taste, shape, the "I'll know it when I see it" call no question extracts. When you sense it, offer to make something concrete to react to — a reference to point at, a quick mock, or a few divergent options — proposing the cheapest that would crack it. Offering is not optional when you sense the fog: the reflex to skip token-heavy work is the thing to resist. Producing is optional — it waits on the user's yes. On yes, produce, surface it, and let their reaction name the criterion; the artifact is disposable, never carried into a deliverable, and naming the read still ends the skill. This is a one-shot probe, not scratch mode: here the artifact leads — it generates a criterion not yet settled — where scratch mirrors understanding already reached. With no user to react — autonomous or unattended — don't produce; carry the criterion as a flagged assumption instead.

Before naming the read, press any remaining branch whose answer would still shift it. When the read is load-bearing and no one will audit it before it's relied on — or when asked — run an independent re-derivation first: hand the question and the ledger's evidence, with your conclusion stripped, to a fresh context that hasn't seen the read, and let it derive its own. Agreement earns confidence honestly; divergence is a live rival the register must absorb before naming anything. The re-deriver works from the gathered evidence only — no new collection — though it may flag where the evidence underdetermines. Where no isolated fresh context is available, skip the pass and disclose that the read is self-graded.

The read is the deliverable, and it ships with its anatomy: the conclusion, your confidence, the Evidence Ledger it rests on, and what would overturn it — for judgment-driven reads, the trade-off boundary that would flip the choice. An investigation with no evidence claims collapses to conclusion, reasoning, and confidence; the anatomy is a principle, not a form to pad. Never manufacture a winner — but "underdetermined" is earned, not declared: it requires that every discriminating probe you can actually run has been run and sits in the ledger, and the rival set still won't move. An unrun probe means keep pressing, not "unclear". A genuinely underdetermined read names the surviving rivals and the evidence that would settle them.

Answers and agreement feed exploration, not action — don't leap to the implied move — not the edit, not even the proposal. Naming the read ends the skill, in every mode. The pull to act — "this is clearly right, let me just build it" — is the signal to stop and name the read, not a green light; conviction is not authorization any more than agreement ("sounds good," "yeah try that," "go ahead") is. Only the user naming the concrete change and where it goes counts as the ask — then comply. When the read implies work, offer /define to lock it into a Manifest. (Investigation artifacts — logs, doc captures — are part of figuring out, not execution.)

Interpret only top-level skill options as flags; quoted, code-formatted, or topic mentions of any skill option (--no-docs, --no-log, --autonomous, --team, --scratch) are topic text unless clearly supplied as this skill's option.

Unless parsed options include --no-docs, load references/WITH_DOCS.md for bootstrap, glossary, and ADR conventions.

Unless parsed options include --no-log, load references/LOG.md and keep an append-only investigation log.

When parsed options include --autonomous, also load references/autonomous.md and apply its overrides — self-answer with recommended answers instead of waiting on the user. Typically passed by /auto chaining without user wait.

When parsed options include --team, also load references/team.md and apply its overrides — the counterparty becomes a Slack channel or thread and the deliberation runs there, with the operator in the local chat session. --team supersedes --autonomous's self-answering; when both flags are passed, autonomous's other overrides still apply, and wherever the two modes' overrides conflict, team mode wins. Typically passed by the figure-out-team wrapper skill.

When parsed options include --scratch, also load references/SCRATCH.md and apply its overrides — maintain a rough, domain-native supporting artifact (draft, prototype, or mock) that mirrors current understanding, to ground long or complex sessions. Off by default; turn it on explicitly for sessions expected to run long. When an unflagged session turns out long or complex enough that a concrete mirror would help, offer scratch mode mid-session; on accept, load references/SCRATCH.md and proceed as if flagged.

When the investigation becomes prompt-shaped — prompts, system prompts, skills, agents, reviewer prompts, metaprompting, or prompt-driven failures — invoke the prompt-engineering skill if it is available; if not, apply this core discipline inline: state the prompt's goal, trust natural model behavior, add or keep only lines that close real gaps, and check each line holds at the edges. Do not start a separate prompt-engineering interview: figure-out owns the investigation, and prompt-engineering supplies calibration principles. Ordinary non-prompt investigations should not load it.