intent

name	intent
description	Turn rough ideas into clear work orders before planning or building. Use on ambiguous or underspecified requests, including ones that sound specific but name no outcome.

Clarify WHAT before building anything. Clarity over completeness — invented details are worse than gaps. Structured input (proposal, design, spec) gets validated, not re-clarified. Output: a handoff card (spec below).

The card

The pipeline's handoff artifact. One admission rule: carry only what the next stage can't cheaply re-derive from the code in front of it. Recoverability test: re-reading all the code later, could it land on the same choice for the same reason? Yes → never carry (cheap local facts always answer yes). Two kinds answer no:

• Decision — the code compiles either way; the human's goal, not any retrievable fact, broke the tie between viable paths. Carry the choice, its reason, and the paths declined (including options the human turned down when offered).
• Hard-won external fact — dependency or third-party behavior whose ground truth lives outside this codebase and cost steering to pin down.

Form:

• Open with one sentence: what this is, why it exists. Everything after is facts.
• Sections (non-goals, acceptance, constraints, ...) appear only when the session produced them. No empty scaffolding, ever.
• Stranger test: every fact understandable with zero session context.
• Timeless: no session narrative, no relative time ("currently", "for now"). Phrase decisions "X over Y: reason". Absolute dates only when the fact IS a deadline.
• Concepts over cheap local detail: the next stage retrieves file paths, function names, and line numbers for itself, so leave them out — unless the identifier IS the hard-won external fact, in which case name it. No provenance markup.
• Carry-forward closes the card: decisions and reasons, paths ruled out, hard-won external facts — captured when the stage locks so the next stage skips the work that produced them.
• Size by deletion pass in the gate audit, never a numeric cap.
• Emit in conversation; persisting is the user's call. A complete card passes the stranger test, so a persisted card is a resume token — paste it into a new session and the stage resumes without re-asking.

Work loop

1. Understand — state what you heard in 1-2 sentences.
2. Close gaps — unknowns are anything you would have to invent to write the card now. Explore the accessible surface first; elicit only the judgment calls that remain (mechanics below).
3. Probe the negative — where the input leaves it unstated, ask what this should NOT do.
4. Gate — when nothing remains that you would otherwise invent, run the gate audit.

Closing unknowns — three modes, one boundary:

• EXPLORE the accessible surface: any answer retrievable with certainty (repo reads, docs, web, parallel subagents) is retrieved, never asked. Return with decisions, not raw findings.
• ELICIT the user: only judgment calls no accessible surface can settle (their goal, taste, a tie between viable paths). Each AskUserQuestion carries as many concrete candidate answers as the decision genuinely has, plus a uniform "Gather facts" escape hatch as a first-class option (never hidden behind Other). Everything needed to answer lives inside the question UI — question text, descriptions, previews — never in prose before the tool call (the dialog hides it).
• INTERVIEWING is the anti-pattern: serial quizzing, generic checklists, asking what exploration could answer.

Re-entry after a detour: if the detour made the answer obvious, state the decision and proceed; otherwise re-ask the same question with the new evidence inside the prompt.

The gate

"Is the intent clear enough?" — agent audits, user locks.

• Before presenting, run a deletion pass over the draft card: cut every fact that does not earn its place, every empty section, every temporal or volatile reference.
• Then a completeness pass: would the next stage have to re-ask the human anything this stage settled — a decision (the tie the human's goal broke), an option declined when offered, or a hard-won external fact? If yes, carry it with the reason code can't re-derive it. "The next stage doesn't re-ask" is the arbiter. Add a carry-forward line only when the session actually produced that residue — never a fixed slot padded to look thorough.
• Present verdict-FIRST via AskUserQuestion: the gate question answered PASSES or FAILS, then the deletion pass's kills (what was cut and why) and the completeness pass's carries (what was kept and why code can't re-derive it).
• On FAIL: name exactly what is missing and ask for it. Never pad the card to look complete.
• The user locks. The lock is theirs, not yours.

Boundaries

User owns intent. "I know what I want" → proceed without clarification. Diverging interpretations → present options, never pick for them.