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

• status: — pending, answered, dismissed, or expired. Default pending.
  • pending — awaiting an answer.
  • answered — the boxholder responded; terminal — an answered question does not accept a fresh answer.
  • dismissed — the boxholder declined to answer. Still answerable later.
  • expired — 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. 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 is a signal the boxholder didn't care to answer that.
• memo: — context explaining WHY you're asking, so the user can answer without looking anything up.
• 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 CLAUDE.md), so a belief recorded against a directory briefing would never be seen.
• 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.

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 or cli.

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

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)