Skip to content

Create Jira Ticket

TL;DR — Routes the ticket to the correct team/project (using the wiki SSOT), picks an issue type from the project's real list (never hardcoded), structures Acceptance Criteria in BDD, supports three states for optional sections (fill / TBD placeholder / skip), forces a preview with an adjustment loop, and only then creates the issue. Mandatory Atlassian MCP precheck at Step 1; lazy required-fields handling at the end.

Overview

This workflow turns a natural-language request like "create a ticket for X" into a Securitize-conformant Jira issue. It is conversational by design — the procedure is a wizard with deliberate confirmation points, not a single batch submission. Use it from any context (a repo, a doc folder, a fresh shell) — there is no requirement to be inside a Securitize repository.

Audience is intentionally broad: product, QA, engineering, operations, support, project management. The wizard does not assume technical knowledge in the user; non-technical callers describe behavior in plain language and the workflow structures Acceptance Criteria in BDD on their behalf (assisted mode is the default).

The Atlassian MCP cannot upload files — there is no addAttachment tool exposed by the current Atlassian MCP. Whenever the user wants screenshots, the workflow renders the Screenshots section as a TBD placeholder and tells the user to attach manually in Jira after creation. Do not promise to upload files (see Step 7).

Inputs

  • none required at start — the workflow elicits everything it needs through the wizard. The user typically gives an initial sentence describing the work; everything else is gathered turn by turn.
  • target Jira project (resolved in Step 2) — derived from explicit mention, best-effort repo inference, or a direct question.
  • issue type (resolved in Step 3) — picked from the project's live list returned by getJiraProjectIssueTypesMetadata.

Language — chat vs. ticket body

The two are different and must not be conflated.

  • Conversational replies (questions, confirmations, summaries shown to the user) match the user's language. If the user types in Spanish, reply in Spanish.
  • Ticket body (Title, General description, Acceptance Criteria, How to test, Technical notes) is always written in English. This is the Securitize convention regardless of chat language. If the user describes the work in Spanish, draft the ticket content in English and show it for confirmation — do not transcribe verbatim.

If the user explicitly asks for a Spanish ticket body, push back briefly and confirm before proceeding.

Steps

1. Verify the Atlassian MCP is available (precheck)

Before any user-facing question or inference, confirm the Atlassian MCP is available. If missing, halt with an actionable message — do not advance.

Verify the Atlassian MCP server is reachable in the session and run a semantic health-check by calling getAccessibleAtlassianResources to resolve the cloudId for securitize.atlassian.net. If auth or connectivity fails, surface the error verbatim and stop — do not retry.

  • Halt message: "This workflow requires the Atlassian MCP. It is not loaded in this session. Configure it (see wiki/ai-tooling/mcp-and-ai-tooling.md → Atlassian — atlassian-mcp) and try again."

Robustness note: the workflow couples to capabilities, not to literal tool names. If a tool name changes upstream and a runtime call fails with "tool not found" or a signature mismatch, surface the failure to the user (snapshot outdated) — do not retry blindly.

2. Resolve team and Jira project

The wizard never asks for content before knowing where the ticket goes. Use this cascade — the inference is a hint, not truth:

a. Explicit mention. If the user named a team, a Jira project key (ON, ISR2, TA, BC, AO, OPS, CTD), or said something like "for the Onboarding board", use it directly.

b. Best-effort repo inference (optional, may fail silently). Try git remote -v from $PWD. If git is not installed, the cwd is not a repo, or the remote does not match a known Bitbucket project, skip this step silently — do not propose a wrong default and do not mention the failed attempt to the user. If a match is found:

  • Load get_wiki_file(path="references/teams.md") to get the SSOT mapping Bitbucket project → team → Jira project.
  • Propose and wait for confirmation ("Looks like this is the CA repo → ON team. Is this ticket for ON?"). Never assume the match silently — the user might be standing in a repo that is not the one for this ticket (a notes repo, a sandbox, another project).

c. Direct question. If (a) did not apply and (b) was not confirmed, load teams.md if not yet loaded and show the team list with each team's responsibility as a hint, plus the special CTD option for cross-team initiatives / tech debt. Wait for the user's pick.

See wiki/organization/teams.md for the canonical mapping; wiki/organization/jira-boards.md holds the board URLs (loaded later in Step 10).

3. Resolve issue type

Always query Jira for the project's real issue type list — never hardcode.

  1. Call getJiraProjectIssueTypesMetadata(cloudId, projectIdOrKey=<resolved project>). Filter out entries where subtask: true (subtasks require a parent and are out of scope for v1).
  2. Permissions edge case: the call may return an error like "You cannot create issues in this project" (verified for AO). Surface the error verbatim to the user, list alternatives — file via the team owner from teams.md, or use CTD — and let the user pick another board. Do not fail silently.
  3. Suggest a default from the user's prompt (heuristic):
  4. stacktrace / "broken" / "no funciona" → Bug
  5. new feature / "as a user I want…" → Story
  6. multi-sprint or cross-team scope → Epic
  7. otherwise → Task
  8. Verify the suggested default exists in the returned list (some projects use custom types — see references/issue-types.md for a snapshot per project).
  9. Present to the user: "Suggested type: . Available in this project: . Confirm or pick another." Wait for an answer.

See references/issue-types.md for guidance on picking Bug / Task / Story / Epic and dealing with project-specific custom types (e.g. Smart Contract in BC, Stretch Story in TA, Improvement / Release in OPS).

4. Collect General description

Ask: "Give me the summary: problem, motivation, scope." This is mandatory — if the user tries to skip, insist.

Draft the description in English (regardless of chat language — see Language section above). Keep it tight: 3–8 lines is typical. Show the draft and wait for confirmation or adjustment. The user can iterate in natural language; redraft and re-show until the user is satisfied.

See references/ticket-template.md for what each section should and should not contain.

5. Collect title tags and generate the title

a. Tags (optional, free-form). Ask: "Any tags to prefix the title? Free-form, your team's convention (e.g. [BE], [FE], [bug], [infra]). Skip to omit." No canonical list — each team picks their own (some don't use any). Do not validate; render as-is in brackets at the start of the title.

b. Title (auto-generated, editable). Generate a concise title from the General description. Rules:

  • Max 60–70 characters total, including tags.
  • One line, no trailing period.
  • If the user types a manual title that exceeds the limit, reject it and ask to shorten.
  • Final format: [TAG1][TAG2] <title>.

Show the auto-generated title and wait for the user to confirm or rewrite.

6. Collect Acceptance Criteria

Behavior depends on the issue type resolved in Step 3.

For Epics — AC is OPTIONAL and NOT BDD.

Epics describe the goal of a feature that will be broken into Stories and Tasks. Each child ticket carries its own BDD AC. Forcing BDD on the Epic itself produces low-signal scenarios that duplicate what will be written better in the children.

Ask: "Want to add high-level goals or outcomes for this Epic? (Skip if not needed — the detailed BDD scenarios will live in the child Stories/Tasks.)" If the user provides content, render it as a free-form bulleted list of goals/outcomes — do not coerce into Given/When/Then. Three states apply just like other optional sections: fill / TBD placeholder / skip. If skipped, omit the Acceptance Criteria section from the Epic entirely (no empty header).

For all other types (Bug, Task, Story, and project-specific custom types like Spike, Smart Contract, Improvement, etc.) — AC is MANDATORY in BDD.

At least one scenario. Two modes:

  • Assisted (default). The user describes in natural language what should happen (one case, several, mixed). The workflow structures each scenario in Given / When / Then and shows the result. The user confirms or adjusts in natural language ("the second one is actually only when flag X is on"). This mode is critical for non-technical callers (product, QA, support) who may not be familiar with the BDD syntax.

  • Manual. The user opts to dictate step by step. Prompt each clause one by one: Given → When → Then → optional AND clauses → "another scenario?"

In both modes the user can add / remove / edit scenarios before closing the block. If a scenario has an unclear When or a missing Then, ask a clarifying question instead of guessing.

See references/bdd-acceptance-criteria.md for the full guide — clause definitions, good vs. bad examples, common pitfalls.

7. Collect optional sections

Four optional sections, each with three valid states — make all three explicit when asking:

  • Fill it now — user provides content; the section renders normally.
  • Leave as TBD placeholder — the section header is included in the ticket with a _TBD — to be added._ line, signaling that someone will complete it manually in Jira after creation. Useful for things that cannot be embedded in chat (Figma URLs not gathered yet, attachments, etc.).
  • Skip entirely — the section header is omitted from the ticket; no empty headers, no placeholder.

Go through them in order:

  1. How to test. "Want to add QA tips (test data per env — dev / rc / sandbox / prod —, specific accounts, feature flags, edge cases)? Fill it now, leave a TBD placeholder, or skip." See references/how-to-test-tips.md for what tends to be useful per environment.

  2. Figma URL. "Any Figma link? Paste URL, leave a TBD placeholder, or skip."

  3. Screenshots. "Want to attach screenshots? I can't upload them from here (the Atlassian MCP does not support attachments), but I'll leave a TBD placeholder so you can attach them in Jira after creation. Yes / skip." If yes, render _TBD — to be attached manually in Jira after the ticket is created._. Never promise to attach files. The "fill it now" state does not apply to Screenshots — there is no way to embed an image from chat.

  4. Technical notes. "Any implementation hints, libraries to touch, tradeoffs, related tickets? Fill it now, leave a TBD placeholder, or skip."

8. Collect Jira metadata (batched)

Ask all three together in one turn, with explicit defaults so the user can answer in one line. Do not split into three sequential prompts — that adds noise without value.

"Assignee (name / email or unassigned), labels (or none), priority (Highest / High / Medium / Low / Lowest, default Medium)?"

Skip items the user already mentioned earlier in the conversation. If the user gives a name or email for assignee, resolve to an accountId with lookupJiraAccountId before creation.

9. Required custom fields — handle lazily (do NOT pre-query)

The getJiraIssueTypeMetaWithFields capability returns large payloads (~90 KB for a Task in ON) that can exhaust token limits. In practice, most projects have only the canonical required fields (project, issuetype, summary), which are already covered by the wizard. Pre-querying is rarely useful and often expensive.

Recommended flow:

  • Do not call getJiraIssueTypeMetaWithFields up front. Skip this step entirely in the common case.
  • In Step 12, attempt createJiraIssue directly with the data collected so far.
  • Only if the create call fails with a missing-required-field error, parse the error, ask the user for those specific fields, and retry. The expensive call becomes an exception path, not the default path.

If you do need to introspect fields explicitly (e.g. the user asks "what custom fields can I set?"), the response is too large to read directly. Save it to a file and filter with jq:

jq '.[1].text | fromjson | [.fields[]? | select(.required==true) | {fieldId, name, schema: .schema.type, hasDefaultValue}]' <response.txt>

This returns only the required fields. Use select(.required==false) for optional ones.

10. Render the preview (mandatory)

Before any create call, load get_wiki_file(path="references/jira-boards.md") if not already cached in this session — it holds the board URL for the resolved project. Then render a single message containing:

  • Header line: Project · Type · Assignee · Labels · Priority · Board URL.
  • Title: the final [TAGS] <title> string from Step 5.
  • Body (markdown, all sections in order, omitting skipped optional sections and including TBD placeholders where chosen):
# General description
<content>

# Acceptance Criteria    (BDD for Bug/Task/Story/custom; free-form bullets for Epic; omitted entirely if skipped on Epic)
## Scenario 1: <short title>
- **Given** <context>
- **When** <action>
- **Then** <expected outcome>
- **And** <optional>
... (more scenarios as needed) ...

# How to test            (only if filled or placeholder)
...
# Figma url               (only if filled or placeholder)
...
# Screenshots             (only if placeholder — never filled)
...
# Technical notes         (only if filled or placeholder)
...

End with: "Confirm to create, or tell me what to change."

11. Adjustment loop

The user may request changes in natural language: "change AC #2", "drop the [BE] tag", "assignee is Juan", "add a scenario for the failure case". Apply the change and re-render the full preview. Never skip this step — even if the change feels small. Loop until the user gives an explicit confirmation ("create it", "sí, dale", "go").

12. Create the issue

Call createJiraIssue with:

  • cloudId — from Step 1.
  • projectKey — from Step 2.
  • issueTypeName — from Step 3 (use the exact name from the project's list, e.g. Task, Bug, Sub-task in OPS vs. Subtask elsewhere).
  • summary — the final title from Step 5.
  • description — the full markdown body from Step 10.
  • contentFormat — "markdown" (the MCP converts to ADF internally).
  • assignee_account_id — only if the user provided a non-unassigned value in Step 8.
  • additional_fields — only if non-default labels or priority were chosen in Step 8 (e.g. {"priority": {"name": "High"}, "labels": ["foo"]}).

Error handling:

  • If the call fails with a missing-required-field error, parse the error, ask the user for those specific values, and retry once (see Step 9). Do not loop blindly.
  • On success, return the ticket URL (https://securitize.atlassian.net/browse/<key>) and the issue key to the user. Remind them about any TBD placeholders they need to fill manually in Jira (typically Figma URL and Screenshots).

Verification

  • The ticket exists at https://securitize.atlassian.net/browse/<key> with the expected title, type, description, assignee, labels, and priority.
  • General description and Acceptance Criteria are present and non-empty.
  • Optional sections appear only in their chosen state — filled, TBD placeholder, or fully omitted (no empty headers).
  • The title fits within 60–70 characters and starts with the agreed tags (if any).
  • The board listed in the preview matches the one in wiki/organization/jira-boards.md for the resolved project.

Rollback

  • Before Step 12 (no issue created yet) — discard the wizard state; nothing was published.
  • After Step 12 (issue created) — the workflow cannot un-create an issue. Options:
  • Edit the issue in Jira (correct content) — use editJiraIssue if available, or the Jira UI.
  • Move the issue to a "Closed - Won't Do" or equivalent terminal state via transitionJiraIssue.
  • Delete via the Jira UI if the caller has delete permissions on the project (most do not).

See also

Tags

workflow #jira #ticket #atlassian #wizard