Question format v2

Stable URL: https://gitoodo.com/spec/questions/v2/

Gitoodo question format (version 2)

This document is the single source of truth for the format that agents use to ask a human a question in a forge issue or comment, and for the answer comment that Gitoodo posts back. The parsers (src/question/ and crates/core/src/question.rs), the agent skill (skill/gitoodo-questions/SKILL.md) and the tests follow it. The examples below are extracted and parsed by a test, so they cannot drift from the parsers. Both question parsers read the examples directly from this document and compare their complete results against tests/question-examples.expected.json. When changing the format, update the examples and their shared expected results together; do not copy example inputs into another fixture.

Version 2 replaces version 1; v1 blocks and answers are no longer read. The machine-read parts are fixed and English (markers, kind, Deadline:, Recommendation:, (yes/no), (multiple), (text), the answer tokens yes, no, explain). The human-read parts (the header line, context, questions, option labels, consequences, reasons) follow the app language of the asked human (en, de, es, ar, hi, zh-Hans). Answers are understood in every supported language (yes, ja, sí, نعم, हाँ, 是, …; see "Answer comment").

The format is an open standard: any agent, tool or forge integration may write and read it without Gitoodo. Its public, versioned home is https://gitoodo.com/spec/questions/v2/, generated from this document when the site is built. Section anchors are the GitHub-style slugs of the headings (#answer-comment, #tolerant-reading, #plain-answers), so links into this document work the same in the repository and on the site.

Compatibility promise #

Version 2 is stable. Within version 2 these never break:

What may change within version 2:

Anything that would break a valid version 2 block or answer gets a new version with its own marker (v3) and its own URL (/spec/questions/v3/). The version 2 page stays published with its rules unchanged.

Design goals #

Question block #

A block is delimited by two HTML comments. HTML comments are invisible in the rendered Markdown of all four forges, and the text between them renders as normal Markdown (a numbered list with the options as lines below each item).

<!-- gitoodo:questions v2 id="<id>" kind="<kind>" -->
@<login> **<Name>** (<hint how to answer, e.g. `1b` or `2 yes`>)
<up to 3 context lines>
Deadline: <YYYY-MM-DD>
1. <Question>?
   a) <Option> – <consequence>
   b) <Option> – <consequence>
   Recommendation: a
2. <Question>? (yes/no)
   Recommendation: yes
<!-- /gitoodo:questions -->

Delimiters #

Block kinds #

The kind tells the orchestrator (and the app) why the question is asked. It never changes how the block is parsed or answered; the parsed block carries it as kind next to id.

KindAsked byMeaning
workeran agent working on the issueThe worker is blocked on a human decision and continues after it.
approvalthe classifierA yes/no gate, e.g. for an issue or PR of an untrusted author.
clarificationthe classifierThe issue is contradictory or unclear (needs-clarification).

Unmarked questions (found in running text) have the kind worker.

Content #

All lines are optional, except at least one question.

PartSyntaxNotes
Header@<login> **<Name>** (…)First line. Addresses the human; text after the bold part is free.
Contextup to 3 plain lines between header and first questionMore than 3 makes the block invalid.
DeadlineDeadline: YYYY-MM-DDAmong the context lines; does not count as one. At most once.
Question<n>. <text> with n = 1, 2, 3, 4 in order1 to 4 questions per block.
Optiona) <label> or a) <label> – <consequence>Keys a to d in order. The dash is an en dash or -.
RecommendationRecommendation: <value> below the questionAt most once. Agents should always give one (see the skill).

Question kinds #

The kind is given by an optional suffix at the end of the question line.

KindSuffixOptionsRecommendation: valueAnswer token
single choicenone2 to 4 (a to d)one key, e.g. a1b or 1bc
multiple choice(multiple)2 to 4 (a to d)keys separated by commas: a, c1ac
yes/no(yes/no)noneyes or no2 yes
free text(text)nonenot allowed3 "any text"

A recommendation may be followed by – <reason>; the reason is ignored.

A single choice asks for one option, but the human may combine several: a click in the app picks one option, and an option can be added on purpose (the card's "choose several" control or a Cmd/Ctrl-click). The answer then carries every chosen key like a multiple choice (1bc). Agents read such an answer as "all of these options" (see the skill). The question block itself is unchanged: a single choice still has at most one recommended key.

Answer comment #

The app posts one comment per answered block:

<!-- gitoodo:answer v2 id="<id>" -->
<answer line>

<optional free text, Markdown>

An answer line that does not match this grammar makes the whole comment "not an answer" (it stays an ordinary comment). The tokens are case-insensitive when parsed; the app always writes the lowercase English tokens.

Every supported language is understood when reading, in the answer comment and in plain answers:

MeaningWords
yesyes, ja, sí, si, نعم, हाँ, हां, 是, 好
nono, nein, لا, नहीं, नही, 否, 不
explainexplain, erklären, explicar, اشرح, समझाएं, 解释

A word ends at whitespace, ,, ;, . or a quote; digits and keys (1ac) stay as described above.

Explanation requests #

Instead of choosing, the human can send a single question back with <n> explain when the question, the options or the decision criteria are not understood. It is allowed for every question kind and can be combined with answers to the other questions of the same block (1b 2 explain "What does b cost?" 3 yes). The optional note is a JSON string like a free-text answer; an empty note is written as no note.

The agent re-asks exactly the questions marked explain in a new block (new id) with a fuller explanation of the question, the options and the decision criteria, and keeps the other questions as answered. For the app the block counts as answered like after any other partial answer, so the question is no longer open until the new block arrives, which then shows up as a new question.

Gitoodo comments #

The orchestrator may write with the user's own account (no separate worker account), so the login alone cannot tell a worker's question or a status note from the human's reply. Every comment that Gitoodo, its dispatcher, its classifier or a worker posts therefore carries a machine marker on a line of its own:

A comment with any of these markers is written by Gitoodo, whatever account posted it. The answer marker (<!-- gitoodo:answer v2 …) and the forward marker (<!-- gitoodo:forwarded v2 …) belong to a human acting through the app; a comment with either of them is the human's, even when it also carries a question block (a forward). A comment without any marker is written by a person.

For comments written before the automation marker existed, readers also treat these unmarked status notes as Gitoodo's: a comment that starts with gitoodo: , one that starts with Gitoodo could not bring this branch up to date with, and Milestone <name> is closed; removed from it (backlog).

Writers other than Gitoodo (an agent asking through gitoodo ask or the skill) post question blocks, which are marked already; they add <!-- gitoodo:auto --> to any other comment they post in the issue on Gitoodo's behalf.

Detecting an answered question #

Only blocks and answers posted by trusted people count (the bot, the repo's human, trusted authors, people with write access or organisation membership; docs/security.md). A block or answer marker in a comment of anyone else is ignored and never shown to a worker as a question or answer.

A block is answered when the last comment after the question was written by the asked human, the login in the header (@<login>), and is not a Gitoodo comment (see "Gitoodo comments"). The content of that comment does not matter otherwise; an answer comment of the app, a plain answer or a free remark all close the question, a status note of Gitoodo posted under the same login does not. A block without a header login is answered by a comment that contains an answer marker with the block's id and a valid answer line, or by a plain human reply (see "Plain answers") that fits the block. Only comments after the question count; the app and agents compare by position in the issue (body first, then the comments in order). A plain reply answers the latest card that was asked before it, never an older one. A block whose id appears in a later forward marker (see "Forwarding") is answered for good. Without any of these the question is open.

Forwarding #

The asked human can hand a question on to another trusted person. From the asked human's account, the app posts one comment that holds, per forwarded block:

  1. a forward marker on its own line, outside code fences, naming the old block: <!-- gitoodo:forwarded v2 id="<old id>" -->
  2. a new block of the same kind with a new id (the old one plus -f1, -f2, … until it is unused in the issue, at most 64 characters), the header @<new login>, and the same context, deadline, questions, options and recommendations.

The comment starts with one visible line that names the forwarding person, for example Forwarded by @alice. Markup in that line is removed, so it can never open or close a block.

Forwarded by @alice
<!-- gitoodo:forwarded v2 id="db-choice" -->
<!-- gitoodo:questions v2 db-choice-f1 worker -->
@bob **Bob**

### 1. Which database?
...
<!-- /gitoodo:questions -->

The old block is answered by the forward itself: the comment is by the asked human, and the marker keeps it answered after the new person replies. The new block is open until @<new login> comments, like any other block. The app also assigns the issue to the new person and removes the forwarding person from the assignees.

Rules of the app (not of the format): only blocks of kind worker whose header names the forwarding person can be forwarded; the new person must be trusted (a configured login, write access to the repo, or membership in the owning organisation); nobody receives a forward while they hold 10 or more open blocks in that repo. In a public repository the forwarded question is as public as the original.

The forge is the only source of truth: there is no answered label and no state outside the issue.

Tolerant reading #

The exact format above is what agents write (the skill never changes). The app additionally reads what humans and less careful agents produce, in four tiers. Each block carries an origin: strict (exact block), tolerant (marked block with slips), unmarked (found in running text); the card shows a subtle hint for the last two. Everything else is plain text (tier four). Answers are always written in the strict form.

Fenced code (``` or ~~~) is never read, in any tier, and neither are quoted lines (starting with >).

Marked blocks with slips #

If the exact grammar fails, a block with a valid opening marker (v2, valid id, valid kind) and its closing marker is read again with these rules; the first block of an id wins in both tiers.

Unmarked questions #

Outside markers a numbered list is read as a card when all of these hold:

Unmarked cards have no addressee, context or deadline. Their id is derived from the content, so it stays the same on every poll: u- plus the 16 hex digits of the FNV-1a 64-bit hash (offset 0xcbf29ce484222325, prime 0x100000001b3) over the UTF-8 bytes of the question texts, each lowercased with whitespace collapsed to single spaces, joined by \n. The text of a broken or unsupported marked block is never read as an unmarked card.

Plain answers #

A human answers with an ordinary comment, e.g. 1c, 1 yes, 2 b, 1 ja or 3 "Berlin":

A comment in the exact answer format is read by the strict rules only.

Invalid and partial blocks #

A marked block is plain text, and shows no card, when neither the exact grammar nor the tolerant reading accepts it:

The exact grammar is stricter: it also rejects stray lines, a numbering gap, more than 4 questions, more than 3 context lines, a second Deadline: or Recommendation: line and several recommended keys for a single choice; such a block is read tolerantly instead if the rules above allow it.

There is no partial rendering: a block is either a valid card or plain text. In both cases the app also offers the free comment field. Other valid blocks in the same body are unaffected.

Examples #

Single choice with a deadline:

<!-- gitoodo:questions v2 id="db-choice" kind="worker" -->
@silvio **Silvio** (answer e.g. `1b` or `2 yes`)
The sync job needs a store for seen notification ids.
Deadline: 2026-11-20
1. Which store should hold the seen ids?
   a) SQLite – one more dependency, but queryable
   b) JSON file – simple, enough for a few thousand ids
   Recommendation: b
<!-- /gitoodo:questions -->

Yes/no and single choice together:

<!-- gitoodo:questions v2 id="release-1" kind="worker" -->
@silvio **Silvio** (answer e.g. `1b` or `2 yes`)
Release 0.2.0 is ready on dev.
1. Release now? (yes/no)
   Recommendation: yes
2. Which channel?
   a) Staging only – safe
   b) Staging and production – needs your approval
   c) Hold back
   Recommendation: a
<!-- /gitoodo:questions -->

Multiple choice and free text:

<!-- gitoodo:questions v2 id="platforms" kind="worker" -->
@maik **Maik**
1. Which platforms should the first beta support? (multiple)
   a) macOS
   b) Windows
   c) Linux – not planned
   Recommendation: a, b
2. What should the beta be called? (text)
<!-- /gitoodo:questions -->

A marked block with slips (tolerant): addressee without bold, 1) and A. with bullets, bold recommendation, upper-case kind suffix.

<!-- gitoodo:questions v2 id="naming" kind="worker" -->
@silvio Frage an Silvio
Which name do we ship?
Deadline: 2026-11-30
1) Name for the app?
   - A. Gitoodo – short
   - B. Git-to-do
   **Recommendation:** a
2. Ship it? (YES/NO)
<!-- /gitoodo:questions -->

Questions without markers in the form people actually write them (from an issue), with an option wrapped over two lines:

Offen ist nur Akzeptanzpunkt 3: Nachweis in der echten App.

1. Wie soll der Nachweis erbracht werden?
   a) Ich teste selbst in der echten App
   b) Ich lasse es per Skript pruefen
   c) Der Punkt wird gestrichen
   Recommendation: c – Code ist gegated und getestet.

Other forms of numbering, options and recommendations (unmarked): bold number, parenthesised options, Empfohlen with a question number.

**1.** Welche DB?
(a) SQLite
(b) JSON
**Empfohlen:** 1b)
Frage 1: Welche DB?
**a)** SQLite
**b)** JSON
Vorschlag: b)
### 1. Welche DB?
- a) SQLite
- b) JSON
Recommendation: b

Yes/no hints (j/n) and (yes/no):

1. Release jetzt? (j/n)
Recommendation: yes
1. Release now? (yes/no)
Recommended: yes

Multiple choice and free text hints:

1. Welche Plattformen? (Mehrfachauswahl)
a) Mac
b) Win
Empfehlung: ab
1. Name? (Freitext)

Mixed forms, bulleted upper-case options, em dash and colon separators, a wrapped option and a Frage n: question:

1) Wohin soll der Build gehen?
* A) Staging — nur intern
* B) Produktion: braucht
    deine Freigabe und ein
    Zeitfenster
* C) Nirgends
Empfehlung: 1c
Frage 2: Auch Windows bauen? (Ja/Nein)

Questions without markers, as a person or an agent without the skill would write them (unmarked):

Before I continue I need two decisions from you.

1. Which database should hold the cache?
   a) SQLite – queryable
   b) JSON file – simple
   Recommendation: b
2. Should the old endpoint stay? (yes/no)
   Recommendation: no

Thanks!

An unmarked free-text question with a kind suffix:

Quick check:
1) Wie soll das Release heißen? (text)

The matching answer comments:

<!-- gitoodo:answer v2 id="release-1" -->
1 yes 2a
<!-- gitoodo:answer v2 id="platforms" -->
1ab 2 "Gitoodo Beta"

Windows build only after the macOS one is stable.

An answer that sends question 2 back for a better explanation, with a note:

<!-- gitoodo:answer v2 id="release-1" -->
1 yes 2 explain "What is the difference between staging and production?"

Invalid blocks, which are rendered as plain text. Missing closing marker:

<!-- gitoodo:questions v2 id="broken-1" kind="worker" -->
@silvio **Silvio**
1. Is anything closing this block?
   a) No
   b) Yes

A single-choice question with one option and a recommendation for an unknown key:

<!-- gitoodo:questions v2 id="broken-2" kind="worker" -->
1. Only one option?
   a) Yes
   Recommendation: c
<!-- /gitoodo:questions -->

An unsupported version:

<!-- gitoodo:questions v3 id="future" kind="worker" -->
1. From the future? (yes/no)
<!-- /gitoodo:questions -->

A heading list is not a question list:

### 1. Setup
Install the package.
### 2. Usage
Run it.

Bare numbered questions without any option, hint or recommendation:

Open points:
1. Who owns the release?
2. When is the freeze?

Plain numbered list without questions:

Steps to reproduce:
1. Open the app
2. Click the tray icon
3. Nothing happens

Quoted question list (quotes are never read):

> 1. Which store?
>    a) SQLite
>    b) JSON file

Question list inside fenced code (here ~~~, so it can sit inside this fence):

The format looks like this:

~~~
1. Which store?
   a) SQLite
   b) JSON file
~~~

Prose that merely contains option letters:

Options a) keep it, b) drop it or c) wait - which one do you prefer?

Plain replies and what they mean for the block with the same id are listed in tests/question-replies.expected.json; both parsers are checked against it.