Guides / Building software with AI agents

QnA MD use cases: six ways to use a question file

Agent questions to an owner, approval chains and quorum decisions, an idea-to-brief interview, a skill brief, a team sign-off, and answering with no signal.

Product help

By Steven Michael Barber · Published October 19, 2026 · Updated November 3, 2026 · 6 min read

QnA MD keeps questions and decisions inside a Markdown file, as hidden tags that the QnA MD editor turns into answer cards. The idea is simple, and it fits more situations than the one we built it for. This guide walks through six that we use or have tested, with what each needs from the format. The tag details are in the file format guide.

An agent's open questions to the person in charge

This is the original case. An agent working in a repository reaches a choice it should not make alone, writes a tag into the relevant plan file addressed with to: to the person who decides, and carries on with other work. The person opens the file on their phone, and the Review tab shows only the items waiting on their handle, each under the paragraph it concerns. They answer, save, and put the file back in the repository or a shared folder. The next time the agent reads the file, the answer is there.

Two things make this work well. The agent offers listed options with one marked as its recommendation, so most answers are a single tap. And the agent treats only resolved items as instructions, leaving deferred ones alone and treating a vetoed one as a topic to drop.

Approval chains and quorum decisions

Some things need several people to agree rather than one person to choose. A decision tag states what is proposed in its D: line and lists the approvers. Written as @legal > @lead, the chain is ordered: the editor offers the Approve button to legal first and to the lead only after legal has approved. Written as a comma list with quorum:, any that many approvers will do. Without a quorum, everyone listed must approve.

An approver can Reject, with a reason: in an ordered chain only the person whose turn it is, in a quorum decision any listed approver who has not yet approved. A rejection sets the decision back to open, and only approvals given after it count, so a changed proposal cannot slip through on earlier sign-offs.

Worked example: two of three leads approve an email

An agent has rewritten a password-reset email and needs two of three support leads to sign off:

<!-- oq:decision #sup-07
by: @agent 2026-10-15T16:00Z
status: open
D: Send the new password-reset email from Monday.
approve: @dana, @lee, @sam
quorum: 2
why: Two of the three support leads sign off customer-facing email.
ref: emails/password-reset.md
log:
- [ ] @dana
- [ ] @lee
- [ ] @sam
-->

All three see the decision as waiting on them. Lee approves on Thursday. The status stays open, and the decision now waits only on Dana and Sam. On Friday Dana approves and adds a comment. That makes two of three, and the writer sets the status to resolved:

<!-- oq:decision #sup-07
by: @agent 2026-10-15T16:00Z
status: resolved
D: Send the new password-reset email from Monday.
approve: @dana, @lee, @sam
quorum: 2
why: Two of the three support leads sign off customer-facing email.
ref: emails/password-reset.md
log:
- [x] @dana 2026-10-16T06:55Z approve
- [x] @lee 2026-10-15T18:20Z approve
- [ ] @sam
- @dana 2026-10-16T06:55Z note: Checked the link on a phone.
-->

Each approval filled in that person's placeholder ballot instead of adding a new line, and Dana's comment became a note, which does not change the status. Sam's empty ballot stays as a record that his approval was not needed. The reference parser reports no warnings at any step.

An idea interview: from an idea to a brief

A file of questions does not need an agent behind it. In an unreleased template called aIdea, we tested 31 questions that walk a person from an app idea to a brief they can hand to their own AI tool or to a developer. It has no recommendations, because it has no opinion on the person's idea, and no to: lines, so every question waits on whoever opens it. The template is not available for download; the pattern is one you can use in your own files.

The first ten questions, under the first three headings, are marked "Quick" in their why: line and make a short idea brief on their own; the rest build toward a fuller plan. Most are free text, with choices, checklists, two yes or no questions and one ranking where the answers can be listed. A person answers what they know and taps Defer on the rest, which moves those questions to the end of the queue and records the deferral in the file. aIdea itself calls no AI model, and its template carries the CC0 public-domain dedication. The same shape works for an intake form, an onboarding checklist or a post-incident review.

A brief for an AI skill

We also tested a draft 15-question template for describing a repeatable task to an AI assistant, often called a skill: what it is for, what goes in and comes out, phrases that should trigger it, a test case and safety limits. The test asked whether each question fits a tag type and can be answered on a phone without follow-up. All fifteen passed once four questions moved to narrower types, such as the safety question becoming a confirm, and several gained a sentence saying how to lay out the answer, such as starting a two-part answer with "I give:" and "I get back:".

The test also showed the limits. QnA MD has no branching, so the file order has to carry the depth, and it does not check answers against rules such as a length limit or a naming pattern. Those checks belong to whatever reads the file next.

A team sign-off

A release checklist, a policy change or a launch plan can carry its questions for several people. Each tag's to: line names who it waits on, so each person's Review tab shows only their own items, while "All open" shows everything still outstanding. The Log view lists every decision and copies them as a Markdown table for a status report.

Because the file is the only shared state, a team needs one agreed home for it, usually a git repository or a shared folder. Two people answering in separate copies at the same time produce two versions that have to be merged; since each answer changes only its own tag, the merge is usually simple.

Answering on a phone with no signal

Once loaded, QnA MD works with no network at all. A person can open a file at the gate, answer it on the plane and save it after landing. The file and the answers stay on the phone until saved, and the editor shows "Unsaved changes" under the file name until they are. The one exception is dictation: some phones send speech to an online service for transcription, so typing is the offline option.

Where it fits less well: anything that needs live discussion, verified signatures or access control. The handle on each answer is a name the person types, not a proof of identity. Why we accepted that is covered in why we built QnA MD, and running whole rounds of questions this way is the subject of batch processing with QnA MD.