Ticket templates

A ticket template holds the rules your team has for new issues: which sections the description must have, which field values are preset, and what the AI should do when it writes the issue. The same template applies whether you create the issue in the dialog or the AI creates it from the chat.

Required fields are a different thing. They are enforced by Jira, and Tracemoor reads them from the Jira project. A template covers what Jira does not know, for example that every bug description has a section "Steps to reproduce".

Create a template

Choose File › Ticket Templates….
Tracemoor creates the folder .codeexplorer/ticket_templates/ in the exploration, adds a commented example.md if the folder is empty, and opens the folder in the file manager.
Copy example.md, rename it and edit it in any editor.

Every .md file in the folder is a template. The file name without .md is the template's name. The folder is part of the exploration and is shared with the team through Git.

Format

A template is Markdown with YAML frontmatter. The part below the frontmatter is the body skeleton that gets filled in.

---
provider: jira
project: PROJ
issue_type_id: "10200"
fields:
  components: [Backend]
  customfield_10011: "Team A"
required_sections:
  - Steps to reproduce
  - Expected behaviour
instructions: |
  Write headings and body in English.
  If a spec matches this bug, put its path under "Related spec".
---
## Steps to reproduce

1.

## Expected behaviour

## Related spec

Key	Effect
`provider`	Restricts the template to `jira` or `github_issues`. Leave it out for all providers.
`project`	Default project.
`issue_type_id`	Default Jira issue type, as ID, not name.
`fields`	Field defaults. They prefill the form and can be changed. A scalar is written without brackets, a multi-select as a list.
`required_sections`	Headings the description must contain. Enforced, see below.
`instructions`	Instructions for the AI. Not enforced, see below.

Required sections

If a template lists required_sections, the description must contain each of them as a Markdown heading. Otherwise the issue is not created:

In the Create Issue from Entry dialog, Create Issue shows the message "Template "name" requires these sections: …" and creates nothing.
In the preview of an AI write, Approve stays disabled while a heading is missing. Before the issue is sent, the check runs again, so deleting a section in the preview does not get past it.

The heading level does not matter (## or ####), and case and surrounding spaces are ignored. The text must be a heading. A mention in a paragraph does not count.

Field defaults and instructions

fields and instructions are not enforced:

fields prefill the form. The person or the AI can change every value.
instructions are passed to the AI when it uses the template, for example "write in English" or "find the matching spec". Both dialogs show them, so you can see what the template asks of the AI. Whether the AI followed them cannot be checked automatically.

Write instructions as a block scalar (| or >-). Prose contains colons and quotes sooner or later, and in a plain YAML scalar : starts a mapping. The template then fails to parse and is listed as broken.

Use a template

In the dialog: choose it under Template. It sets project, issue type, field defaults and, if the description is still empty, the body skeleton. The required sections are listed below.
From the chat: the AI lists the templates with tickets_templates, picks a matching one, fills in the skeleton and follows the instructions. The result goes through the same preview and the same check of required sections.