DillieDocs
dillie.work

Writing tickets

How to create tickets with the CLI that someone without context can read and start working from. Whoever reads a ticket is you a few weeks later, a colleague who was not in the conversation, or an AI opening the project for the first time. Few tickets can be understood from the title alone; the body does that work.

Build the body

Three things are enough, and leaving any one out usually means someone has to ask.

  • Background — why this is needed. What symptom, request, or decision produced it.
  • Work — what changes. Named so a reader can navigate to it: files, screens, endpoints.
  • Acceptance — what has to be true for this to be done. Something a person can check.
## Background
Users keep reporting an empty list on the first screen after login. The data is
there; the view renders before the first request fills the cache.

## Work
- Distinguish the initial loading state from the empty state
- Split the empty-state copy into "Nothing yet" and "Loading"

## Acceptance
- Refreshing on a slow network does not show "Nothing yet" first
- A list that really is empty still shows "Nothing yet"

Do not write acceptance as “works correctly”. Whoever judges completion then has to invent the criteria, and they will not be the ones the author had in mind.

Filter out what does not belong

  • Conversation logs — keep “so we decided this”, drop the path there.
  • Undecided options — if a decision is needed, make that decision the work of the ticket.
  • Guessed causes — mixing what was checked with what was guessed leaves the reader to sort it out. If it is a guess, say so.

Write in Markdown

Write the body in Markdown, including tables, code blocks, and lists.

HTML and JSX tags are rejected (400). Tags inside code blocks and inline code are fine; outside them they count as tags. So notation such as Array<string> or <tenantId> is rejected in plain text too — wrap it in backticks or write it like {tenantId}.

Set the description key

The description is not an ordinary field; you put it in the _description key of values. It is a virtual key, so it does not appear in the describe fieldMap — choosing keys from the fieldMap alone leaves no place for the description.

dillie project tasks create ACME --data '{"values":{"title":"Title","_description":"## Background\n…"}}'

For a long body, pass the whole request body as a file.

dillie project tasks create ACME --data-file ./ticket.json

values accepts three kinds of keys — field ids from fieldMap.fields in describe, the aliases below, and _description. Any other key is rejected, and the message names the rejected keys.

dillie --agent describe ACME --fields fieldMap

There are commands that read and write only the description. Use them to change the description of an existing item. Give either --content or --content-file, not both.

dillie --agent project tasks get-description ACME ACME-123
dillie project tasks set-description ACME ACME-123 --content-file ./body.md

Use aliases for value keys

Keys in values are field ids from the fieldMap, but common ones can also be written by name: title, status, issueType, assignee, priority, dueDate. The server maps each to the field id with that role. There is less room for error than copying UUIDs.

  • Giving the same field both as an alias and as a field id is rejected (400). Give one.
  • If the list has no field with that role, or more than one, it is rejected. Use the field id then.
  • Put a user id in assignee, and "YYYY-MM-DD" or { "due": …, "start": … } in dueDate.

For fields with a fixed set of choices (status, issue type, priority), send the option id, not the label. A label is turned into an option id only when you give the key as an alias and the label matches exactly one option, including case. Look up option ids in the field’s options in the describe fieldMap.

For the issue type you can also pass a label with --issue-type. The CLI matches it case-insensitively and turns it into the option id; if the label matches several options, it errors instead of choosing. It works with create, update, and bulk-create.

dillie project tasks create ACME --issue-type Bug --data '{"values":{"title":"Empty list is indistinguishable from loading"}}'

Write the title

The title is the line that identifies the item in search results and lists.

  • Write what it does. “Empty list is indistinguishable from loading” rather than “Login bug”.
  • Say where the change is. Someone scanning search results should be able to pick it from the title.
  • In lists that have an issue type field, do not classify with a prefix. That field already carries the type.

Troubleshooting

A value key is rejected

The message names the rejected keys. You may have reused a field id from a previous session — call describe again and pick keys from fieldMap.fields. If you sent an alias together with its field id, drop one.

The description is rejected

The body has HTML or JSX tags, or angle-bracket notation, outside code. Wrap it in backticks or switch to Markdown syntax. How to read other rejections is in Working with the dillie CLI — Troubleshooting.