figure-out git:20261014.ea8a062A

Immutable. This exact content never changes and is served at /api/v1/blob/45dc3e55273455ca.

---
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 — for a
request for code, data, or a check, the result you expect. One ask, which one
short answer settles — never a list, a second question folded into it, or a
fallback for when it can't be met:
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. Write the ask in plain text by default. When the user's instructions ask
for it and the host offers a question-selection capability, deliver the ask
through it, with your recommended answer as the first option.

Write everything meant for people — turns, the read, offers, log entries — in
ASD-STE100 (Simplified Technical English) style by default: short sentences,
active voice, common words, one term for one thing. The strict STE dictionary is
not required. The user's own instructions on style win.

**The user's call.** A decision is the user's call when two careful people with
the same evidence could reasonably decide it differently, and the difference
would matter to the user. Test each material decision against that sentence;
your own confidence does not settle it. At a user's call, check the user's Taste
entries — ratified preferences in a `## Taste` section of a loaded memory file.
Follow an entry only where it clearly bears: it speaks to this kind of call, and
following it would change the choice. A general lean that would tilt almost any
call, such as less effort or lower cost, does not bear on its own. Otherwise
decide on the evidence. Wherever decisions are reported, list the user's calls
first, each with the alternative not taken and what decided it — the entry
followed, or that no entry applied.

Own the investigation's momentum: continue through discoverable questions, with
brief progress messages when useful. Yield only for what the user must supply —
a fact only they hold, authority you lack, or a user's call no Taste entry
settles — or a completed read. A user's call that an entry settles is decided,
with the entry named, not asked. 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.
- Whatever the read implies making is for someone: start from the person a
  project's North Star names under *Who it's for*, where there is one, or find out who, then name
  the narrower slice and moment this artifact serves where it has one — a
  pricing page is for someone already comparing prices. Take their seat and
  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
  how it will be checked — in a project, through its verification harness, its
  one command for checking a result, with a recipe per feature, skill, document walk
  or eval suite, found where the context file's project-surfaces section names it
  or, with none named, among the verification assets the project keeps; its
  `list` is where a report or a change is placed first; with no project (see
  *Modes and what loads*), by a check this session can run or read — 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 after that choice, unless the user asks to explore them now.
  Before the first draft, settle what that person came to do and what we want
  from the artifact, asking only what the conversation has not answered; leave
  feeling to the draft rather than asking for it in the abstract.
  Show the draft 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,
  using an Artifact page where available — except a visual draft whose direction
  is still open, which opens with two or three variants, each a different answer
  to the open choice: how it should feel and how strongly, or the visual idea.
  Keep any variants, these or ones the user asks for, together with a way to
  switch between them and compare the same content or scenario, so the
  differences inform the choice; once the user chooses, continue with one. Yield
  to another form when 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, passing along that person, their moment, and our goal; any feeling
  or strength the user named; for each variant, the difference it explores; and
  this iteration's question and rough fidelity, so design guidance serves the
  next reaction. Where that skill is unavailable, write down the loop 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. Read each reference whose condition holds before
your first reply, and one whose condition comes to hold later when it does; apply
its 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/RECALL.md` | once the investigation concerns work in the active repository — a bug, change, design, or decision; a general or quick question that repository's history cannot bear on loads nothing | what earlier sessions, tickets, and pull requests left on this repository: dated leads, the debt on this topic's path, hotspots |
| `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, the update offer for an older setup, a drift marker on a recipe found drifting — 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. A project is a
repository or working folder holding, or about to hold, work that later sessions
will change — code, documents, a product; a new one the user is starting counts —
and the investigation is relevant to it when the topic concerns that work. Many
sessions have none: a chat app with no workspace, a home or scratch folder, a
folder holding one finished artifact, a question that does not concern the folder
the session runs in. In a session with none, offer, build or mention no project
surface — no setup, no verification harness or recipe, no decision record,
glossary or North Star — and run the rest of the method whole. One-off work
inside a project is still project work. Where relevance 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, performance, documents, prompts,
user-visible artifacts (`UI.md`), human-voiced writing (`WRITING.md`).
They carry only angles the
model under-weights by default; fold in what's load-bearing and ignore the rest.
Nothing fits → probe generally. The probes are opinionated starting points: a rule
the user states, in the session or a context file, or a convention the project states or documents,
wins where it conflicts, and the context file's outcome rules — naming, structure,
architecture — constrain the shape being designed, not only which probes apply.

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.