question Card

Question Cards

A question card asks the user something and routes the answer back for processing. An answer has two products, and both are worth capturing when they apply: the immediate effect (directive: — what to do with this one answer) and durable knowledge (learning: — the belief the answer confirms or denies, going forward). Today's placement is the small part; the rule the boxholder just taught you is usually the valuable part.

Frontmatter

• A question's state is read from which lifecycle timestamp it carries:
  • pending — none of answered-at, dismissed-at, expired-at: awaiting an answer.
  • answered — has answered-at (and answer); terminal — an answered question does not accept a fresh answer.
  • dismissed — has dismissed-at: put away for now (Later), by the person or by Decide for me. Still answerable later.
  • expired — has expired-at: aged out of the active view by the aging sweep, without an answer. Still answerable later — expiry demotes visibility, it does not close the question. A card carries at most one of the three timestamps; answering a dismissed or expired question removes its timestamp. Before asking something new, check _bookkeeping/questions/ including answered/dismissed/expired cards: an existing answer is a user-stated fact, and a dismissal or expiry means the question was put off, not answered.
• memo: — context explaining WHY you're asking, so the user can answer without looking anything up.
• title: — a short name for the question, a few words ("Folder for the hardware receipt"): its tab and the chat beside it show this. Without one, the prompt's first sentence stands in.
• prompt: — the actual question.
• input: — {type: select|text|confirm, options?: [{id, label}]}. select requires at least two options. confirm and text must NOT carry options.
• learning: — optional. Set it when the answer is also evidence for a durable belief, not just a one-shot decision: {sink: guide|briefing|personality, ref?: <card path>, proposal: <the belief being tested, quotable>}. State what you are trying to learn and where it should be recorded — when the destination is known, declaring it here is cheap and turns recording the answer into a mechanical follow-up step. For sink briefing, ref MUST be the ROOT briefing card: directory briefings are not compiled into any agent's context (only the root briefing becomes the box's AGENTS.md), so a belief recorded against a directory briefing would never be seen. When the boxholder answers, the follow-up job records the confirmed (or denied) belief in that sink as a basis: user-stated fact — the strongest evidence tier, since the boxholder said it directly.
• directive: — what to do with the answer. The system creates a follow-up job using this text as instructions. Be specific. Without a directive, the answer's immediate effect goes nowhere (the follow-up job still records learning: if you set it).
• context: — array of {ref, text?} linking to related cards.
• asked-at: — ISO 8601 timestamp, set automatically by the template that creates the card. The aging sweep computes a question's age from this field, never from notification/latch state.
• expires-after: — optional ISO-8601 duration (e.g. P30D, PT12H) overriding the default expiry window for this question. Use it for a time-sensitive ask that should expire sooner, or an evergreen one that should last longer.
• urgency: — optional; the one value is time-bound. Set it when the question blocks something with a date (a form due Friday, a booking that closes). A new question badges the phone; a time-bound one also sends a notification.

After the user answers, the system fills in:

• answer: — {text, selected?} where selected is the option id for select questions.
• answered-at: — ISO 8601 timestamp.
• answered-via: — web, cli, or chat. A chat answer (bbx answer <path> --via chat "<their words>") is one you record from a conversation in which the person answered a pending card; it writes no follow-up job, because you do the directive yourself, in that conversation, before you answer the card. Answering is the last step: while the work is not done the card stays pending, and the pending card is the work item. For a select question pass the option's label; for a confirm question pass yes or no. If the briefing already holds the answer, answer the card from it without asking again. In a shared chat the message's user attribute names who answered; put it in the answer text ("Juni: mostly lending").

Dismissing sets dismissed-at:; the aging sweep expiring a question sets expired-at:.

provisional: — {decision, reasoning, undo, decided-at}: what the box decided in place of an answer. It is not the person's answer, and only bbx question decide writes it. A later answer keeps it as history; before recording that answer (any --via), reverse what the box did where the answer differs, as far as undo and git allow, and say what you reversed.

For select questions, make options mutually exclusive. For confirm questions, make the prompt unambiguous about what "yes" means.

The contains: field

Give this card a one-sentence contains: — the prime retrieval field for bbx search and listings. How to write a good one (carry the information when it's concise, never a list of parts, under 200 characters) is in the agent guide's ABOUT_CARDS section.

Templates

question

A multiple-choice question card

bbx create <path>.question.card -t question

Template: question Description: A multiple-choice question card Card types: question

Arguments: memo: Context/background for the question prompt: The question to ask options (array — repeat key or use JSON: key='["a","b"]'): Answer options (at least 2) directive (optional): What to do with the answer — creates a follow-up job using this text as instructions learning (optional): Durable belief the answer teaches: {sink: guide|briefing|personality, ref?, proposal} expires-after (optional): ISO-8601 duration overriding the default expiry window (e.g. P30D, PT12H)

question-text

A free-text question card

bbx create <path>.question.card -t question-text

Template: question-text Description: A free-text question card Card types: question

Arguments: memo: Context/background for the question prompt: The question to ask directive (optional): What to do with the answer — creates a follow-up job using this text as instructions learning (optional): Durable belief the answer teaches: {sink: guide|briefing|personality, ref?, proposal} expires-after (optional): ISO-8601 duration overriding the default expiry window (e.g. P30D, PT12H)

question-confirm

A yes/no confirmation question card

bbx create <path>.question.card -t question-confirm

Template: question-confirm Description: A yes/no confirmation question card Card types: question

Arguments: memo: Context/background for the question prompt: The question to ask directive (optional): What to do with the answer — creates a follow-up job using this text as instructions learning (optional): Durable belief the answer teaches: {sink: guide|briefing|personality, ref?, proposal} expires-after (optional): ISO-8601 duration overriding the default expiry window (e.g. P30D, PT12H)