Ask a person, and keep the answer
Use this when you need a person to answer something before the work can go on: a choice only they can make, an approval, a fact only they know. A question asked only in a conversation is gone when the session ends, and an answer given there gets asked for again next month. Keep each question that matters beyond the conversation, and its answer, where the next agent will look.
The rule
A question for a person that matters beyond the conversation is written down in the organization, and its answer is written next to it, with who answered and when. Where it goes depends on how the organization is set up:
The organization keeps a type for decisions or questions. Each question is one record of that type, and the answer goes into the same record. A project page, a tracker or a board that mentions the question links to the record instead of holding the question itself.
The organization keeps no such type. The question goes into the document it is about, or into the work item it concerns, and the answer goes there too.
Under either setup, a question about what one block of a document says, such as whether a number is right or whether a sentence should stay, is a comment on that block. The answer is a change to that block, or a note that it stays as it is, and the thread is resolved once that is done. Comments explains how threads work. If answering it takes a ruling that reaches beyond the block, write the question down as above, link it from the thread, and resolve the thread once the answer is kept.
Questions that need no record
A question the person answers in the same conversation, about the task in front of you, needs no record: which file they meant, whether to go on, the opening questions of Set up an organization. Write the answer where the work lands.
Write the question down when any of these is true:
The answer cannot come in this conversation.
Work waits for it beyond this session.
Someone other than the person you work for has to answer.
Other people or agents will need to find the choice later. Then write it down with the answer already in it.
A yes that must come in the conversation
Some steps wait for the person's own yes in the conversation, for example making an organization public, inviting someone or deleting something, and anything else the organization's AGENTS.md reserves that way (What this flow never does). A document can hold such a question and, later, its answer. But everyone in an organization can edit its documents, so a yes written into a document is not that yes. Ask for it in the conversation before you act.
Before you ask
Is it the person's to decide? If the organization keeps a page that says what the person decides and what agents do alone, read it first. A sign-off page describes one. If you are allowed to settle the question yourself, do not ask it: do the work, and say so in one line if the page asks for that.
Was it already asked or answered? Where the organization keeps a type for decisions, search its records, open and answered, with
documents.search({ organizationId, query, typeIds }). Otherwise search the organization for the question's words and read the document or work item it concerns. Then read the resolved threads of the document the question is about by passingincludeResolvedCommentstodocuments.getDocument. Do not ask a question that was already answered. Follow the answer that exists, or ask about what has changed since. If an open question already asks the same thing, add what you know to it and link it from your work. Do not ask it a second time.
Where the question goes
Write the question in the organization where the person who answers can read it, usually the one that owns the work. When you work for a client in their organization, or in a room you share with them, it goes there and not into your own internal organization (Where each result goes).
In a public organization, anyone can read every document, though not its comments (What public means). Keep questions for a person in a private organization they can read. Write only what the answer changes into the public page.
Find out how the organization keeps decisions
Read the organization's AGENTS.md first: it may say where questions and decisions go. Then look for a type the way Record what you decide not to do now does: call documents.searchTypes({ organizationId, query: "decision" }), then try the organization's own words for it, such as question or approval, and read the descriptions of the top rows. The platform has no type for questions, so any such type is the organization's own.
Whether to keep one is part of how an organization sets itself up, and it is not required. An organization that makes many calls, such as a software studio whose agents ask for a ruling every day, may choose a type for decisions, so one listing shows everything waiting and everything decided. Many organizations do well without one. Do not create or propose a type only to ask one question. When a kind gets its own type says when a kind earns a type, for questions as for anything else.
What to write down
A question that waits for someone carries these parts. In a record of a type they are its fields; in a document or a work item they are a few lines under the question, Status first.
| Part | What goes in it |
|---|---|
| Question | One question, with the words that answer it: "yes or no", "A or B". |
| Asked of | The person who answers it. |
| Pick | Your own recommendation, and one sentence on why only this person can decide. |
| What each answer does | What yes does and what no does, a sentence or two each. |
| Sources | Links to the exact paragraphs, ones the person who answers can open, never copies of them. |
| Needed by | The date the answer is needed, when work waits on it. |
| Status | Open, answered or withdrawn. |
| Answer | The person's words as given, who gave them and when. |
| Carried into | The document, or the block inside it, that the answer changed, when that is not where the question sits. |
An organization that keeps a type for decisions makes Status, Asked of and Needed by filterable fields and stores Needed by as a date, the way Set up an organization describes, so a listing or a filter finds what is waiting.
Tell the person who answers
Writing a question down does not tell anyone. If the person who answers is in your conversation, tell them there that the question is waiting, and give them its address: the url returned when you read the record or the document that holds it.
If someone else has to answer, tell the person you work for who it is. Then open a comment on the question with createComment, pass that member's user id in mentionUserIds (organizations.listMembers lists the ids), and write their first name as @Name in the body. Oddlynew emails them a link to the thread. The comment only points to the question. The answer still goes where the question is kept.
When the person answers
Wherever the answer arrives (in the conversation, in a comment, in an email), write it next to the question word for word, with who gave it and the date, and set its status to answered. If it came as a reply on a comment, resolve that thread with a note. Carry the answer into the work it changes the same day, and link the changed block from the question. If the answer changes nothing lasting, say so in one line.
If a question turns out not to be needed, set it to withdrawn and give the reason in one line. Do not leave it open.
Several questions at once
Group the open questions so one sentence can answer many of them ("yes to 1 to 5"), and mark as urgent only what blocks work now. Each question still keeps its own place, and each gets its own answer written in.
Where a question shows up
A project page, a tracker or a board that gathers what waits for the person links each question where it is kept. On a Lens, the record or the document that holds the question goes on as a card with the state needs-you, not as a drawn note that repeats the question. A list that gathers questions from many places is never a question's only home. The person answers in one place, and every list that shows the question then shows the answer too.
Example
An agent preparing a pricing page finds that two plans would be simpler than three. The organization's sign-off page says prices belong to the owner. The agent searches the organization for earlier answers about plans and finds none. The organization keeps no type for decisions, so the agent writes the question into the document that plans the pricing page: "Two plans or three? Answer: two or three." It is asked of the owner. The agent's pick is two, because nobody chose the middle plan in the last quarter. It says what each answer changes, links the paragraph of the pricing research it relied on, and sets Needed by to Friday, because the page goes live on Monday. In the conversation it says one question is waiting and gives the address of that block.
The owner answers in chat: "two, and keep the annual discount." The agent writes those words, the owner's name and the date under the question, sets it to answered, edits the pricing page, and links the changed block from the question.
In an organization that keeps a type for decisions, the agent would write the same question as one record of that type, write the answer into the record, and link the record from the plan.
If prices had belonged to a colleague who is not in that conversation, the agent would have told its own person and mentioned the colleague in a comment on the question. The answer would still go where the question is kept.
The same day, the owner leaves a comment on one sentence of the pricing page, asking whether "per seat" is still right. That is a question about one block, so it stays a comment. The agent fixes the sentence and resolves the thread with a note saying what changed.
Make it local
Name in the organization's AGENTS.md, in one line, where a question for a person and its answer go, for example "Every question for a person is one record of our Decision type, and the answer is written into it" or "A question for a person goes into the work item it concerns, with the answer, who gave it and the date". Write a useful AGENTS.md explains where that line goes.
Check that it works
Ask the organization "what is waiting for me, and what did I already decide?" The answer should come from the organization's documents: from listing that one type where the organization keeps one, otherwise from the documents and work items the questions concern. It should never need old conversations.