Spec To Tickets

Spec to tickets

Write the text of a ticket from one section of a specification. A separate tool sends that text to the tracker (Jira Cloud REST v2, or the tracker the project uses). You never call the tracker API from this skill.

What the sync tool does, and what you do

The sync tool plans and applies. It writes a plan file — docs/delivery/tickets.plan.json — from the costing sheets and the assignment document, a human approves the operations, and the tool sends them. Read the plan file to see the exact summary and description that go out.

You write the words: the summary, the short why, and the acceptance criteria. Nothing else in this skill asks you to touch the network.

When the project has no sync tool, the same rules apply and a human copies the text into the tracker. Do not create tickets over an API on your own initiative.

Read before you write

1. The specification section, under specs/. Read the whole section.
2. The costing task and the assignment item that reference it, so the ticket matches the work that was estimated.
3. docs/delivery/tickets.config.json, for the project and the field names.
4. docs/delivery/tickets.json, the registry, to see if a ticket exists.

If the specification section is unclear, ask. Do not fill a gap with a guess.

The summary

One line, in the vocabulary of the team. Keep it below 255 characters, because Jira refuses a longer summary.

Examples. Good: Import a supplier price list from a CSV file. Bad: CSV importer (backend).

The description

Four blocks, in this order. Keep each block short.

1. Why — one or two sentences. The value, not the method.
2. Acceptance criteria — a checklist, each line testable.
3. Steps — the first steps from the assignment item, if there are any.
4. Spec — the link back.

The description is not a copy of the specification. Two copies of one requirement always diverge. Write the criteria and link to the source.

Acceptance criteria come from the words of the spec

Take each criterion from a sentence that is already in the specification. Keep the nouns and the verbs of that sentence. Change the grammar only.

Specification: The system rejects a price list whose currency column is empty. Criterion: A price list with an empty currency column is rejected.

Rules:

1. One criterion for each requirement or scenario in the section.
2. No criterion without a sentence behind it in the specification.
3. No performance number, no volume, and no deadline that the spec does not give.
4. If a criterion needs a value the spec does not state, write the criterion and mark the missing value [NEEDS CLARIFICATION].

Invent no scope. An error case, a migration, a permission rule, or a screen that the specification does not name belongs in a question, not in a ticket. Use harvest-questions for those.

Always link back

Every ticket carries a specRef: the repository path of the specification section, such as specs/billing/spec.md. The sync tool turns that path into a URL with the base in tickets.config.json.

The link is never pinned to a commit. A pinned link changes on every commit and re-fingerprints every ticket.

A ticket with no specRef is refused. That guard belongs in the sync tool, not in this skill.

What never goes in a ticket

Rates, day counts per profile, and internal disagreements stay in the repository. A tracker project usually has a wider audience than the repository.

Do not do these

• Do not create a second ticket for a key the registry already holds.
• Do not propose a status transition. The sync tool never writes one.
• Do not propose a deletion. There is no delete call, by design.
• Do not edit tickets.json by hand. The sync tool owns the registry.