Jira Task Formatter

Convert a messy Jira task description into a clean, standard template. Works with any Jira project — the team prefix is read from the issue key, not hardcoded. The template below is a sensible default; a team can override section names, language, or the API block (see Configuration).

##Trigger

User invokes /jira-task-formatter, or asks to format / «оформить» a task and gives one or several issue keys (<PROJECT>-<NUMBER>, e.g. PROJ-123, ABC-42). Without a key — ask which task. Multiple keys → process one by one.

##Configuration

Defaults work out of the box; override per request if the user states otherwise.

##Workflow

###1. Fetch the task

All Jira access goes through the jira-cli skill (invoke it via the Skill tool, then use the jira command). For each key, get the raw issue:

Pull from the output: summary, description, issue type, components, labels, linked issues (blocks / is blocked by / relates), parent / epic, existing acceptance criteria, attachment URLs (Figma/ADR/specs).

If a field is missing from --plain, fetch raw JSON:

###1b. Pull missing data from the epic / siblings

A task usually belongs to an epic (parent/epic field). The epic and its sibling tasks are the best source for gaps the task itself does not state — spec / ADR / Figma links, related schemas, field names, scope boundaries, dependencies.

jira epic list <EPIC-KEY> --plain --columns key,type,summary,status --no-headers
jira issue view <SIBLING-KEY> --plain     # sibling tasks that look relevant

Use this to fill {TODO} gaps with real data instead of placeholders: a spec link found in a sibling task, a DB column introduced by another task, an explicit out-of-scope boundary ("done in <OTHER-KEY>"). State which sibling task each borrowed fact came from. Never invent — only reuse what a real task states.

###2. Classify the task

• handler task — adds/changes an HTTP endpoint. Signal: description mentions a route, METHOD /api/..., request/response payloads, or the component is an API service. → include the *+API+* block.
• non-handler task — everything else (logic, infra, migration, refactor). → omit the *+API+* block.

State the classification to the user before formatting.

###3. Map source content into the template

Reuse text already in the task. Do not invent business logic, API contracts, or acceptance criteria — those come from the source or stay as placeholders.

Rules:

• Do not put the task title / summary into the description — the description starts directly with the first section header.
• Extract spec / ADR / Figma URLs from description text and attachments.
• Rephrase the step list into numbered concrete steps.
• For handler tasks, lift the endpoint, request, response and error table from the source. Keep error codes and JSON exact — never edit quoted payloads.
• Acceptance criteria & DoD → bullet lists with the (x) icon prefix.
• "Как тестировать" → a sequence written for a Junior Manual QA.

###4. Fill the two extra sections

• Out of scope / Риски — what is explicitly NOT done in this task, plus open questions and risks. Derive from the source if stated; otherwise placeholder.
• Нефункциональные требования — logging/metrics, access rights / authorization, backward compatibility, env/config, feature flags. Fill what the source states; placeholder the rest.

###5. Mark gaps

Any field with no source data → write {TODO: <что нужно>} inline. After the formatted output, print a "⚠ Пробелы" list of every {TODO} so the user sees what to fill. Never fabricate values to hide a gap.

###6. Ask before writing to Jira

Show the formatted description, then ask the user (per task):

Обновить описание <KEY> в Jira этим текстом? (да / нет)

• да → write via the jira-cli skill, in the body markup the instance expects (see Markup).
  1. Write the formatted body to a temp file (on Windows: avoid stdin).
  2. Run jira issue edit <KEY> --no-input -b "$(cat <tempfile>)" via the Bash tool (feed < /dev/null to stop jira-cli hanging on a prompt).
  3. Verify — re-fetch jira issue view <KEY> --raw and confirm the description actually changed. jira-cli sometimes prints "✓ Issue updated" while the content stays stale; if so, retry the edit.
  4. Delete the temp file.
• нет → leave the task untouched; output stays for manual paste.

Never write to Jira without an explicit yes. Default answer is no.

##Markup: wiki vs Markdown

Jira renders the description differently depending on the deployment — get this right or the body shows raw syntax:

• Jira Server / Data Center → wiki markup (the template below). jira-cli sends -b as plain text without conversion, so the body must already be wiki markup.
• Jira Cloud → ADF; jira-cli accepts a markdown-ish body and converts it. Use Markdown headers/lists instead of wiki markup.

If the deployment is unknown, ask the user, or infer from the instance URL (*.atlassian.net = Cloud). When in doubt, default to wiki markup and verify the rendered result on the first write.

##Output template (wiki markup, default)

The description body below is Jira wiki markup. No task title. Section headers are bold + underlined: *+текст+*.

*+Бизнес цель+*

{Зачем это нужно бизнесу. 2-4 предложения.}

*+Техническое описание+*

*Спецификация:* [{Название}|{URL}]
*ADR:* [{Название}|{URL}]       (если есть)
*Figma:* [{Название}|{URL}]     (если есть)

# {Конкретный шаг}
# {Следующий шаг}
# {И так далее}

*+API+*  (ТОЛЬКО для handler-задач)

# *Endpoint:* {{ {METHOD} {BASE_URL}/api/v1/{prefix}/{action} }}

*Request:*   (если есть body)
{code:json}
{json}
{code}

*Response {CODE}:*
{code:json}
{json}
{code}

*Ошибки:*
||Код||Условие||Response||
|400|...|{{ {...} }}|

*+Out of scope / Риски+*

* Не входит в задачу: {что явно НЕ делаем}
* Риски / открытые вопросы: {...}

*+Нефункциональные требования+*

* Логирование / метрики: {...}
* Права доступа / авторизация: {...}
* Обратная совместимость: {...}
* Env / конфигурация / feature flags: {...}

*+Критерии приёмки+*

* (x) {Критерий 1}
* (x) {Критерий 2}

*+DoD+*

* (x) Код прошёл code review
* (x) {Критерий 2}

*+Как тестировать+*

# {Шаг для Junior Manual QA}
# {Следующий шаг}

##Rules

• Caveman-mode does NOT apply to the generated task description — write it in normal, full prose (Russian by default).
• For Jira Server/DC the body is wiki markup, never Markdown. Quick map: headers *+текст+*; bold *текст*; underline +текст+; numbered list # ; bullets * ; inline code/monospace {{текст}}; link [текст|url]; code block {code:json}…{code}; table ||заголовок|| / |ячейка|; checkbox-like prefix (x). For Jira Cloud use Markdown instead.
• {...} is a macro in wiki markup — curly braces in placeholders (e.g. {division_id}) break rendering. Rewrite as <division_id>.
• No task title in the description — start at the first section header.
• Quoted JSON, error codes, URLs from the source stay byte-exact.
• Omit the *+API+* block entirely for non-handler tasks (no empty block).
• Drop optional ADR/Figma lines if the source has no such link.
• Process multiple keys one by one; ask the write-back question separately for each.