/question-card

The question card

A question card is for a question the user has to think about. "Yes" or a letter applies that option; other words that pick an outcome apply it; a question gets an assessment and the same card back. The examples below are invented and own nothing in this codebase: mirror the shape, not the content.

The card, in order

The header is `**Question N of M:**` alone on its line. M counts the cards known when the card renders; a later round that adds a card raises M on the cards that follow.

The next line is the question in one sentence, in inline code: it names the ways and ends in a question mark, nothing else. Facts go in Today, the stake goes in the close.

Then a `**Today.**` paragraph: what exists now, in what the user sees. Every sentence changes the pick or comes off. No file paths or line numbers, since the user never opens them. A claim you could not check says "unverified" in the same sentence as the claim.

Then the options in one plain three-backtick fence, lettered `a.` `b.` inline, and `c.` only when a third real outcome does something different; a question with more than three outcomes is split into cards. The proposed option is always `a.`, so "Yes" applies it, and its title is followed by `(proposed)`. Each option is written as what the user sees afterward, in as many short lines as that takes, and may end with one sentence on when it is the right pick. A way-out that is a real outcome stays, written as what happens; a pure escape goes, since the reply line already takes any words.

Then the close: `My pick is a. <what the user sees>.` then, on its own line, `**Question:** Go with a?` then, on its own line, `**Why:** <one sentence on why a fits this user's situation and the other ways do not, grounded in a fact from Today>`, with a blank line before each. With three options, the Why rules out both other ways, one clause each. "Yes" is a complete answer. The pick and the Why are each one line of explanation, never a transcript of reasoning.

Around the card

Before Question 1, one list headed `Settled without asking - say which to reopen` names every call made without a question, so the user sees every decision before the first one they are asked. Each item leads with the behavior in product words, then an indented line of code facts, the only place paths appear; every line the same shape. The list prints before the first card; when the flow asks no card, it prints where the first card would have rendered; when no call was made without asking, it is omitted. A later round that settles more calls prints only the new items, before its next card, under the same heading; an item already listed or already asked is never repeated. When the user names a settled item, it is asked on a card in the flow's normal order.

After each answer, one line reads the ruling back in product words and confirms the write: `Ruled (a): <behavior>. In the story.` after the edit has landed in the story file, or `Ruled (a): <behavior> - kept as planned.` when the answer changes nothing in the file. The read-back prints only after the write lands, and the next card renders only after that, so an answer survives a session that dies mid-flow.

A card closes only on the user's explicit answer: a letter, a yes, or words that pick an outcome. It is never withdrawn, never moved to the settled list, and never decided by the agent, because the user is the only one who can close it. A question from the user is answered in full and never with a question; the agent's job at that moment is to show the thing clearly, in plain words, and then put the same card back, with nothing between the answer and the card. When the user asks about a card, or says they do not follow it, the answer goes above the card and gives them a handle on it: a plain example from outside this codebase, or the strongest case for the other option, whichever shows what is at stake. It adds what the card left out. The same card comes back unchanged, word for word.

A card is redrawn only on a fact, the user's or the agent's own finding, and the redrawn card names that fact. A clarifying question is not a fact, and neither is confusion.

What makes the pick

The pick serves the intent already on the page: the story's Spark, or the user's research query when there is no story. It rests on something checked this session; an unchecked claim says "unverified" in the same sentence as the claim, in Today. It holds when challenged, and moves when someone points out a problem, the user or the agent itself; then the card names the fact that moved it.

Examples

<examples> <example> Settled without asking - say which to reopen

• Plan citations are scanned at story completion, not at each chunk.

`complete-story.sh` already walks every changed file once

• A hit names the file and line in the user's words, no path.

the scan's output line is reformatted, not the scan itself

**Question 1 of 4:**

`Fail the story on a plan-citation hit before it is marked complete, or withhold the commit after?`

**Today.** The story is marked complete first. Then the commit step runs, and if it backs out, the list of files it was about to commit is thrown away. The only thing that backs it out today is a file list from the wrong story, which is rare. A comment that cites the plan would not be rare.

a. Fail before complete (proposed)
   The scan runs before the story is marked complete. A hit looks
   like any other failed check: you see the line, the fix loop
   runs, completion runs again.

b. Withhold the commit after complete
   The story is marked complete, then the commit is withheld. You
   see "complete" on the story, nothing in git, the file list gone,
   and no line telling you what to do next.

My pick is a. A hit fails the story before it's marked complete, same as a failed test, and you fix it and finish.

**Question:** Go with a?

**Why:** A plan citation would not be rare the way a wrong-story file list is, so b w