Issue types — picking the right one¶
The workflow never hardcodes the list of issue types. At runtime it queries the resolved Jira project and shows what is actually available. This file is guidance on which type to pick, plus a snapshot of the per-project landscape so the heuristic suggestion is informed.
The four canonical types¶
These exist in every Securitize Jira project consulted (verified 2026-04-30, except AO where the current user lacks create permissions).
Bug¶
Something is broken or behaves incorrectly. Use when the trigger is a defect: a stacktrace, "it doesn't work", "wrong result", a regression. Bugs typically have a clear "expected vs actual" pair.
Smell that it's a Bug: the user describes a current behavior that is wrong, rather than a missing capability.
Task¶
A small, distinct piece of work. Use as the default when nothing else fits clearly. Configuration changes, refactors, small operational work, internal adjustments, doc updates — all live here.
Smell that it's a Task: "we need to do X" without "as a user I want…" framing and without it being broken.
Story¶
A user-goal-shaped piece of functionality. Use for new features framed from the user's perspective. The classic shape is "as a {role}, I want {capability} so that {benefit}".
Smell that it's a Story: the change adds capability that an end user (investor, issuer, transfer agent, internal operator) will perceive.
Epic¶
A larger initiative that contains multiple Stories / Tasks / Bugs. Use when the work spans sprints or teams, or when it needs its own roadmap.
Smell that it's an Epic: you find yourself wanting to break it into multiple tickets before you even start writing it.
Special handling for Acceptance Criteria. Epics describe the goal of a feature; the testable behavior lives in the child Stories/Tasks. The workflow makes Acceptance Criteria optional on Epics and, when included, renders it as a free-form bulleted list of goals/outcomes — not BDD scenarios. Forcing Given/When/Then on the Epic itself produces low-signal AC that duplicates what will be written better in the children.
Heuristic for the default suggestion¶
The workflow picks a default from the user's prompt:
| Cue in the prompt | Suggested default |
|---|---|
| Stacktrace, "broken", "no funciona", "doesn't work", "regression" | Bug |
| "as a user I want", "new feature", "add support for" | Story |
| "initiative", "this will need multiple tickets", crosses teams | Epic |
| Anything else | Task |
The user can always pick something different from the actual project list.
Subtasks — out of scope for v1¶
Subtasks require a parent ticket and have a different creation flow. The wizard filters them out of the available list. If the user explicitly wants a subtask, suggest creating the top-level ticket first and adding subtasks via the Jira UI.
Note: in the OPS project the type is named Sub-task (with hyphen); in the others it is Subtask. The workflow never relies on the name — it uses the subtask: true flag from the API response.
Per-project custom types (snapshot, 2026-04-30)¶
Each project has additional custom types beyond the four canonical ones. Listed here for context; the workflow discovers them at runtime.
ON — Onboarding¶
Beyond Bug/Task/Story/Epic: Design Task, Automation Task.
ISR2 — Issuer Experience¶
Beyond the canonical four: Spike (timeboxed investigation), Deployment Issue, Design task, Automation Task, Dependency (for tracking dependencies on other teams).
TA — Transfer Agent¶
Beyond the canonical four: Stretch Story (work outside the committed scope but ready if capacity allows), Dependency, Deployment Issue, Design Task, Automation Task.
BC — Blockchain¶
Beyond the canonical four: Smart Contract (BC-specific work on the on-chain side), Test Task, Spike, Deployment Issue, Design Task, Automation Task.
OPS — DevOps¶
Beyond the canonical four: Improvement (incremental enhancement), Release (track a specific release), Deployment, Automation Task.
CTD — Cross Tech Debt (not team-owned)¶
Only the canonical types: Story, Task, Bug, Epic, Subtask. Use this project for cross-team initiatives, architecture work, and tech debt that doesn't belong to a single team.
AO — BlackOps¶
Snapshot incomplete: at the time of capture the API rejected the call with "You cannot create issues in this project". If the user lands here, surface the error verbatim and suggest contacting the BlackOps team or picking another board.
When the suggested default doesn't exist in the project¶
If the heuristic suggests a type that the project does not have (e.g. the user said "as a user I want…" but the project doesn't expose Story), fall back to Task and tell the user. Do not silently pick something else.
Choosing between Story and Task — quick rule¶
If you can complete the sentence "as a {role}, I want {capability} so that {benefit}" naturally, it's a Story. If the work is mainly internal (a refactor, a config change, ops work), it's a Task — even if a user benefits indirectly.