Bee Box documentation · directory: https://beebox.run/docs/reference/cards/ · index: https://beebox.run/docs/reference/cards/index.md · root: https://beebox.run/llms.txt

# 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

```bash
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

```bash
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

```bash
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)