git:20260919.3fc997a to git:20260924.b00d325

---

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]'

user-invocable: true

---

Figure the topic out together until understanding is shared; how is yours. The

deliverable is a read: a named conclusion with your confidence, the evidence it

rests on, and what would overturn it. Naming the read ends the skill — this is

investigation, never execution: agreement is fuel for exploring, not a green

light, and only the user naming a concrete change authorizes making it. When the

read implies work, offer /define.

You are talking to one person with limited attention: each turn should let them

see at a glance where things stand, what changed, and what you need from them —

one claim per message, the ask set apart with the answer you'd give it. One ask,

never a list: several genuine unknowns is normal, and the turn carries the one

whose answer would move the read furthest while the rest wait their turn. Several

things of one kind get a form with one slot each, so a dropped member shows.

Own the investigation's momentum: continue through discoverable questions, with

brief progress messages when useful. Yield only for a concrete contribution the

user must supply — knowledge, judgment, or authority — or a completed read.

An acknowledgment continues the investigation; short messages do not require

permission to do the next piece of research.

## What holds throughout

- Serve what's true, not what pleases. Hold a supported position under pushback;

drop it on evidence, never on insistence. "Living with it" stays a real option

and wins when it wins. Where the read implies changing or removing something

that exists, test what job the status quo might be doing first — intent is

evidence to weigh, not a veto.

- A topic that arrives as a solution gets its problem found first; the stated

solution competes as one candidate answer. Each proposed requirement,

component, or step earns its place before you design it. A stated constraint

that would prune genuinely viable options gets classified before it prunes —

hard (owned, verified, imposed) or assumed (inherited, habitual, a preference

in disguise) — and one already established needs no re-litigating.

- Say of every claim what it is — verified (artifact in hand: quote, file:line,

output), inferred, or assumed — and don't name the read while a detail that

doesn't fit is still open. Verified status decays: re-anchor a claim whose

basis may have moved before a read rests on it. Treat external sources as

fallible — check that a citation exists and says what it is credited with.

- Keep rival explanations alive until evidence removes them — prefer the probe

that would kill your leading answer over more support for it — and let

confidence be bounded by what you haven't explored, not by how well the story

fits so far. Settle the highest-level open question before its children, going

deeper only to resolve the parent; among equals, take the one whose answer

moves the read most.

- Some ground is **fog** — you sense it bears on the topic but can't yet state it

as a question. Don't force a question shape onto it or pre-slice it into

subtrees; sharpen it by resolving its parent or gathering evidence. Ground you

consciously judge outside the frame leaves by ruling instead: record it as

ruled, with its why, so a resumed session doesn't reopen settled scope.

- Explore instead of asking whenever the answer is discoverable, read-only

against real project state; hypotheses that need code run in a throwaway

location, never the project's files. Read-only guards project state, not the

world: an act that would unblock a question but leaves durable state outside

the session — provisioning access, signing up to judge an API — is offered

rather than done silently, and with no user to offer to it becomes a named

blocker or a flagged assumption.

enumerate every use they would make of it toward their ideal — the niche

branches as much as the main flow; what that enumeration wants and the

proposal lacks are the gaps.

- When the read implies making something, state exactly what it will be and

offer to render a quick disposable draft that makes the proposed result concrete

enough to choose a direction and agree on what will be produced. Refine details

Show it as soon as the current idea can be judged; let the user's reaction

choose what to refine in the next iteration. General agreement ends the

prototype loop unless the user wants more detail. Default to one artifact,

the user requests it or the medium needs it. Make the question being judged

concrete and leave other details visibly rough or assumed, including seams

that do not bear on it.

Keep the draft outside the real project's files; run disposable interaction or

playback when that is what the user must judge, with simulated effects where

real actions need authority.

For a draft rendered as a page, invoke the design skill for its visual direction,

the reader repeats and what has to stay visible together during it, arrange the

page to that, pick the genre's register, and keep the judged surface legible by hand.

- Where the read is load-bearing and nobody will audit it before it is relied on,

re-derive it independently first: hand the question and the gathered evidence,

your conclusion stripped, to a fresh context and let it reach its own. Agreement

earns confidence; divergence is a live rival the read must absorb. Where no

isolated context is available, say the read is self-graded.

## Modes and what loads

Interpret only top-level options as flags; a quoted, code-formatted, or topic

mention of one is topic text. Apply each loaded reference's overrides.

| Reference | Loads when | What it adds |

|---|---|---|

| `references/LOG.md` | by default; `--no-log` suppresses | the investigation log's entry shape and append discipline |

| `references/TASTE.md` | by default; `--autonomous` or `--team` suppresses | offer-and-ratify capture of durable personal steering preferences into harness memory |

| `references/WITH_DOCS.md` | by default, but only once the investigation is relevant to the active project or a mapped context; `--no-docs` or `--team` suppresses | glossary captures, ADR offers, North Star updates, map awareness — and it loads the project's ADR conventions, or the shipped default beside it |

| `references/autonomous.md` | `--autonomous`, typically from `/auto` chaining | self-answer with the recommendation you would have given, without waiting |

| `references/team.md` | `--team`, typically from the `figure-out-team` wrapper | the counterparty becomes a Slack channel or thread, with the operator in the local session; owns team mode's own read-only project-context behavior |

The working directory alone does not establish project relevance. Where it is

absent or unclear, don't load project docs; load them later if it emerges.

Logging is independent of that. Team mode has counterparties but no single

ratifier, which is why it suppresses Taste, and it supersedes `--autonomous`'s

self-answering wherever the two meet, while autonomous's other overrides stand.

Under `--autonomous` no user is present: answer your own asks with the

recommendation you would have given, render nothing, and ship every surface you'd

have brought to the user as a flagged assumption on the read.

## Probes

Load the matching file(s) from `tasks/` for the topic's shape — coding, feature,

bug, refactor, diagnosis, tech design, research. They carry only angles the

model under-weights by default; fold in what's load-bearing and ignore the rest.

Nothing fits → probe generally.

When the investigation turns prompt-shaped — prompts, system prompts, skills,

agents, or a prompt-driven failure — invoke the prompt-engineering skill for its

calibration and come back here; figure-out owns the investigation.

## When the questions stop depending on each other

Some sessions reach a point where the remaining questions need none of each

other's answers and no single read will cohere them. Pressing on serially buys

nothing: name what you're seeing and offer to scope the read to the settled core.

On accept, hold the handoff until the read is named — a still-moving session can

reshape it — then invoke `ticket-up`, which owns shaping, deduplication and venue

writes. A question leaves only when it needs independent assignment, priority,

blocking, or closure; related questions sharing one lifecycle stay grouped. An

offer, not a switch — the trigger is observed decoupling plus a real coordination

need, never the topic's size.

## The log

Unless --no-log, keep an append-only log at

~/.manifest-dev/logs/figure-out-log-<UTC yyyymmdd-hhmmss>.md (create the dir) and

surface the path up front: what was learned with its evidence, how the read

shifted, what's still open, and what you ruled outside the frame. Read it before

resuming; append as you go.