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:
- A block or answer comment that follows the exact grammar of this document stays valid and keeps its meaning: the
markers,
v2, theidandkindattributes, the header, context,Deadline:, question, option andRecommendation:lines, the kind suffixes and the answer tokens (1b,2 yes,3 "text",explain). - The machine-read parts stay English and keep their spelling; the block kinds
worker,approvalandclarificationkeep their meaning. - A reader never demands more than this document demands today, so a writer that follows it is understood by every version 2 reader.
- The rule for detecting an answered question stays the same, and the forge remains the only source of truth. The one clarification (#764): a comment carrying a Gitoodo machine marker is never the human's reply, even under the human's login (see "Gitoodo comments").
- The URL above and its section anchors stay valid for as long as version 2 exists.
What may change within version 2:
- Tolerant reading may accept more slips, words and languages. It never changes how an exact block is read.
- Explanations, examples and the wording of this document may be clarified without changing a rule.
- How an app presents a card (layout, hints, controls) is not part of the format.
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 #
- Works on Forgejo, Gitea, GitHub and GitLab without any server-side support.
- Reads well as plain Markdown when the app is not used (a human can answer with a normal comment).
- Machine-readable: the app renders an answer card, the agent parses the answer.
- Agents write the exact format below; the app reads leniently (see "Tolerant reading") so that slips, hand-written questions and plain human answers still work. Anything that is not clearly a question stays plain text. Nothing ever crashes or half-renders.
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 #
- Opening:
<!-- gitoodo:questions v2 id="<id>" kind="<kind>" -->.v2is the format version;<id>matches[A-Za-z0-9._-]{1,64}and identifies the block inside its issue. The answer repeats it.<kind>isworker,approvalorclarification(see "Block kinds"); both attributes are required, in this order. - Closing:
<!-- /gitoodo:questions -->. - A body may contain several blocks. Ids must be unique per issue; for a repeated id the first block wins.
- Blocks inside fenced code blocks (``` or ~~~) are ignored, so documentation can quote the format.
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.
| Kind | Asked by | Meaning |
|---|---|---|
worker | an agent working on the issue | The worker is blocked on a human decision and continues after it. |
approval | the classifier | A yes/no gate, e.g. for an issue or PR of an untrusted author. |
clarification | the classifier | The 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.
| Part | Syntax | Notes |
|---|---|---|
| Header | @<login> **<Name>** (…) | First line. Addresses the human; text after the bold part is free. |
| Context | up to 3 plain lines between header and first question | More than 3 makes the block invalid. |
| Deadline | Deadline: YYYY-MM-DD | Among the context lines; does not count as one. At most once. |
| Question | <n>. <text> with n = 1, 2, 3, 4 in order | 1 to 4 questions per block. |
| Option | a) <label> or a) <label> – <consequence> | Keys a to d in order. The dash is an en dash or -. |
| Recommendation | Recommendation: <value> below the question | At 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.
| Kind | Suffix | Options | Recommendation: value | Answer token |
|---|---|---|---|---|
| single choice | none | 2 to 4 (a to d) | one key, e.g. a | 1b or 1bc |
| multiple choice | (multiple) | 2 to 4 (a to d) | keys separated by commas: a, c | 1ac |
| yes/no | (yes/no) | none | yes or no | 2 yes |
| free text | (text) | none | not allowed | 3 "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>
- Line 1 is the marker with the same
idas the block. - Line 2 is the answer line: space-separated tokens, one per answered question, in question order:
- single or multiple choice: number plus the chosen keys in alphabetical order, no separator:
1b,3ac; - yes/no: number, a space,
yesorno:2 yes; - free text: number, a space, then the text as a double-quoted JSON string (
\"and\nescapes):4 "Berlin"; - "please explain better", for every kind: number, a space,
explain, optionally a space and a note what is unclear as a double-quoted JSON string:2 explainor2 explain "What does staging mean here?"(see "Explanation requests").
- single or multiple choice: number plus the chosen keys in alphabetical order, no separator:
- Questions can be left out (partial answers are valid). Each number occurs at most once.
- After one blank line follows optional free text. It is plain Markdown and not interpreted.
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:
| Meaning | Words |
|---|---|
| yes | yes, ja, sí, si, نعم, हाँ, हां, 是, 好 |
| no | no, nein, لا, नहीं, नही, 否, 不 |
| explain | explain, 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 question block (
<!-- gitoodo:questions v2 … -->), a lease (<!-- gitoodo:lease v1) or an intake marker (<!-- gitoodo:intake-rejected -->,<!-- gitoodo:intake-milestone-created -->), or else - the automation marker as the last line:
<!-- gitoodo:auto -->.
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:
- a forward marker on its own line, outside code fences, naming the old block:
<!-- gitoodo:forwarded v2 id="<old id>" --> - 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.
- Question lines:
1.,1),**1.**,### 1.(one to six#) orFrage 1:(alsoFrage 1.,**Frage 1:**; the colon only afterFrage), one to three digits, numbered 1, 2, 3, … in order; up to 5 questions. A line with another number is an ordinary line of the question above it. The list starts at the first line numbered 1. The text after the number must not be empty; the prefix is not part of the question text. - Before the list: an optional first line
@<login> …(the addressee is the text afterFrage an, else a leading bold name, else the login),Deadline:orFrist:lines (any case, bulleted or bold; the first valid date counts) and context lines (the first 3 are kept, further ones are dropped). - Kind hints at the end of the question text, in any case:
(yes/no),(ja/nein),(sí/no),(j/n)for yes/no,(multiple),(mehrfach),(Mehrfachauswahl)for multiple choice,(text),(Freitext)for free text. Without a hint the kind follows from the content: two or more options give a single choice (multiple choice if the recommendation names several keys), a lone yes/no recommendation a yes/no question, no options and no recommendation a free-text question. - Options:
a),a.,(a),A),A.or**a)**, optionally after a list bullet (-,*,+) and indented or not; keys in order froma; 2 to 4 options, else the block is not read. An indented line right after an option continues that option (joined with a space); a blank line, an option or a recommendation line ends it. - Option separator between label and consequence: an en dash, an em dash or a hyphen with whitespace on both sides, or a colon followed by whitespace; the first one counts.
- Recommendation keywords in any case, colon optional, optionally bulleted or bold:
Recommendation,Recommended,Empfehlung,Empfohlen,Vorschlag. The value is read up to the first separator (so a reason may follow,Empfehlung: c – because …). Values: keys (b,ab,a, b), keys with a number (1c,1b); the number must be that of the question) or in parentheses (c)), and any yes/no word of the table above orj/nfor yes/no (stored asyes/no). The first usable one counts. A recommendation that names a key without an option, repeats a key, or is given to a text question or a question with options but a yes/no or text hint, makes the block unreadable, as do a single option and an option out of order. - Any other line inside a question is ignored.
Unmarked questions #
Outside markers a numbered list is read as a card when all of these hold:
- it starts at a question line numbered 1 (any form above) and continues over question lines, options, recommendation lines, blank lines and indented lines wrapping an option; the first other line ends it; numbering must run 1, 2, 3, … and have at most 5 questions;
- every question text ends with
?after the kind hint and theFrage n:prefix are removed; - at least one question is clearly a question: it has a kind suffix, two or more options, or a yes/no
recommendation. A list of bare
1. …?lines is not a card.
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":
- The comment must not contain an answer marker. The first line that is not blank and not quoted (
>), after removing fenced code, is the answer line; the rest is free text. - The line consists only of entries separated by whitespace,
,or;. An entry is a number (one to three digits), optionally followed by:and/or whitespace, and then keys (c,ac), a yes/no word in any supported language (any case), a quoted JSON string, or an explain word with an optional quoted note after whitespace. It ends at whitespace,,,;,.or the end of the line. - Each number occurs once, and every entry must fit its question in the block: the question exists, the kind matches, the keys exist and are unique (a single choice may name several), a text is not empty.
- Anything else is an ordinary comment and does not answer.
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 version is not
2(this includes everyv1block), theidor thekindis missing or malformed, or the closing marker is missing; - there is no question, or more than 5 (more than 4 in the exact grammar), or no
1.question to start the list; - a choice question has fewer than 2 or more than 4 options, or the keys are not
a,b, … in order; - a
yes/noortextquestion has options, or atextquestion has a recommendation; - a recommendation names an unknown option or repeats a key.
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.