Creating GitHub issues and Jira tickets

This documentation was generated with the assistance of AI. Please report any inaccuracies.

Filing a ticket before work begins introduces iru-create-github-issue and iru-create-jira-ticket as the two entry points that turn a rough idea into a tracked, actionable ticket. This page goes one level deeper: exactly what information each one asks for, how the drafted ticket is structured, and which skills actually run behind the scenes to produce it.

Both skills exist so a ticket is immediately actionable by the typical development cycle once filed — grounded in the real codebase rather than a guess, and carrying the same structured information every time regardless of who’s filing it or how much detail they thought to include.

What you provide

Neither skill asks everything up front in one long form — each question is asked only when the previous answer still leaves something unresolved, and every question beyond the task’s purpose is optional.

Information Required Tracker Notes

Purpose (what problem this solves, or what capability it adds)

Yes

Both

Free text. Can be given upfront as a short description argument (/iru-create-github-issue <short description> / /iru-create-jira-ticket <short description>) — the skill then asks only for whatever that description leaves unclear, instead of re-asking from scratch.

Acceptance criteria

No

Both

Folded into the purpose answer if the user already has any in mind; never invented if they don’t.

Linked URL(s)

No

Both

Design docs, discussions, prior art. Each is fetched (WebFetch) and its key points are folded into the draft rather than linked blind.

Attached file(s)/document(s)

No

Both

Local paths — screenshots, logs, specs, mockups. Read directly (including images and PDFs) and summarized.

Related ticket(s)/issue(s)

No

Both

Confirmed against the real tracker (gh issue view / Jira MCP tools) before being referenced, rather than trusted on the user’s word alone.

Epic

No

Jira only

Confirmed by key, then explored the same way iru-explore explores an epic — its description and, where listable, its child tickets — since an epic often carries a shared goal or constraint no single ticket repeats. Assigned to the new ticket as its parent/epic link on creation.

Organization-specific context

No

Jira only

Gathered by delegating to iru-jira-custom-context — an explicit extension point (see Customizing Jira ticket creation) that, out of the box, asks one generic optional question and is meant to be extended per organization with whatever a given Jira workflow actually needs (a required custom field, team ownership, a customer/account, an environment, a compliance classification).

Due date

No

Both

Free text, normalized to an absolute date (e.g. "next Friday" → the actual date).

Importance

A level is always recorded

Both

One of trivial, minor, important, blocking, asked as a fixed choice. Defaults to minor for an ordinary task, or blocking when the purpose reads as a bug or incident actively affecting production — either way, the user confirms or overrides rather than it being assigned silently.

Label (GitHub) / Project + issue type (Jira)

Resolved automatically

Both

Classified from the stated purpose (bug vs. feature/enhancement signal words) and matched against this repository’s real label set, or this Jira instance’s real project/issue-type configuration — never an invented label or issue type. The user is only asked to pick when the match is genuinely ambiguous or can’t be listed.

How the ticket is structured

Whatever was gathered above is drafted into a consistent shape before anything is filed — shown to the user in full for confirmation, never filed silently:

Section Content

Title / Summary

A concise, imperative one-liner (e.g. "Add retry support to the HTTP client").

Summary

The purpose and motivation, in the user’s own terms.

Context

Grounded in iru-explore’s own codebase orientation — the relevant existing files/modules/classes and how they behave today, so whoever picks the ticket up (including a later `iru-explore/iru-plan run) starts oriented instead of cold.

Acceptance criteria

A short bulleted list, only if the user gave any or they can be reasonably inferred — omitted entirely rather than invented.

Task details

Due date (if given), importance, and an estimated difficulty — the skill’s own assessment of how hard the task is to implement, grounded in everything gathered: how much of the codebase it touches, whether it needs new abstractions or unfamiliar dependencies, and the scope described in the purpose/context. One of very easy, easy, medium, hard, very hard, extreme, or impossible, plus a one-line rationale (e.g. "medium — touches two existing classes with clear precedent elsewhere in the codebase, no new dependencies"). impossible is reserved for something that genuinely contradicts a hard technical constraint found during exploration, not just something difficult.

References

Summarized URLs/file contents, confirmed related-ticket links, and — for Jira — the epic (if any) and whatever iru-jira-custom-context returned.

Skills executed

flowchart TD A["/iru-create-github-issue\nor /iru-create-jira-ticket\n(optional short description)"] --> B["iru-explore\n(ground the draft in the codebase,\ngeneral orientation — no ticket yet)"] B --> C["Ask: purpose of the task"] C --> D["Ask: additional context\n(URLs, files, related tickets)"] D --> E{Jira ticket?} E -- yes --> F["Ask + explore: optional epic"] F --> G["iru-jira-custom-context\n(organization-specific context)"] E -- no --> H G --> H["Ask: due date (optional) +\nimportance (trivial/minor/\nimportant/blocking)"] H --> I{Jira ticket?} I -- yes --> J["Resolve Jira project + issue type\n(matched against real configuration)"] I -- no --> K["Classify bug vs. feature;\nmatch a real GitHub label"] J --> L K --> L["Draft title/summary + structured body\n(Summary, Context, Acceptance criteria,\nTask details incl. estimated difficulty,\nReferences)"] L --> M["Show full draft to user"] M --> N{User choice} N -- edit --> L N -- decline --> O["Stop: draft kept, nothing filed"] N -- confirm --> P["File: gh issue create\n(or GitHub MCP tools)\nor Jira MCP tools"] P --> Q(["/iru-issue &lt;id-or-key&gt;\nor /iru-plan &lt;id-or-key&gt;\n(separate, later invocation)"])
Diagram block Skill(s) What happens

iru-explore (ground the draft)

iru-explore

  • Run with no argument — there is no ticket yet, so this is a general codebase orientation rather than one scoped to a specific area

  • Detects the codebase’s language(s)/framework(s) so the drafted Context section can name real files/modules

  • Skipped if equivalent exploration already happened earlier in the same conversation

Ask purpose / additional context / due date / importance

iru-create-github-issue or iru-create-jira-ticket

  • Asks the purpose directly, in plain conversational text — not a fixed choice, since the answer is open-ended

  • Asks for optional context (URLs, files, related tickets, and — Jira only — an epic), fetching/reading/ confirming whatever is actually provided

  • Asks for due date (optional) and importance (fixed choice, with a purpose-aware recommended default)

iru-jira-custom-context (Jira only)

iru-jira-custom-context

  • Delegated to during additional-context gathering, passed the task’s stated purpose

  • Out of the box, asks one generic optional question; extended per organization to ask for whatever else that Jira workflow requires

  • A "nothing provided" response is never a blocker — the caller proceeds with just its own context in that case

Resolve project + issue type (Jira) / Classify + label (GitHub)

iru-create-github-issue or iru-create-jira-ticket

  • GitHub: classifies bug vs. feature/enhancement from the stated purpose’s signal words, then matches it against this repository’s actual gh label list — never inventing a label

  • Jira: resolves the target project (reusing one already established in the conversation, listing accessible ones, or asking) and the issue type (matched against this project’s real configured types)

  • Either way, the user is only asked to pick when the match is genuinely ambiguous or can’t be listed

Draft + confirm + file

iru-create-github-issue or iru-create-jira-ticket

  • Composes the structured title/summary and body described above and shows it in full

  • Waits for explicit confirmation — create now, edit the draft first, or don’t create it — before any visible action is taken

  • On confirmation, files via gh issue create (or GitHub MCP tools) for a GitHub issue, or the connected Jira MCP tool(s) for a Jira ticket, including the epic link/parent field if one was assigned

Detailed, spec-style issues

iru-create-github-issue is the quick path: a handful of questions, a short structured body, filed in a minute. When an issue needs to be written like a specification — every requirement testable, every acceptance criterion traceable, gaps found before the issue exists — use the detailed path, which is GitHub-only (there is no Jira counterpart) and made of three skills that also work on their own:

Skill What it does

iru-draft-github-issue

Interviews the user in small batches (after iru-explore), writes a complete draft to a local file, runs the review loop on it, offers a split when the issue is large, shows the final draft and creates the issue only after confirmation. Invoked as /iru-draft-github-issue [functional|documentation] [<short description>].

iru-review-github-issue

Reviews an existing issue (/iru-review-github-issue <issue-number>) or a draft file (/iru-review-github-issue draft:<path>) against a quality checklist and returns classified findings — gap, pending, inconsistency or doubt — each with the exact question to ask. Read-only: for an existing issue it only posts a comment or edits the body after explicit confirmation.

iru-split-github-issue

Assesses whether an issue is too large and, after the user confirms the proposal, splits it into sub-issues under a root issue, tracked by a milestone. Invoked as /iru-split-github-issue <issue-number> or /iru-split-github-issue draft:<path>.

The two shapes

Shape Sections

Functional

Context, functional requirements, acceptance criteria, optional technical details (classes and lines to change, for highly technical tasks), out of scope, dependencies, and task details.

Documentation

Audience and the page structure to follow. Technical docs cover architecture, data model, use cases, configuration properties, metrics and algorithms; non-technical docs are a learning guide with pages or sections per concept. Every documentation issue requires bibliography or official-documentation links (the review fetches them to confirm they resolve) and Mermaid or SVG diagrams where they aid understanding, plus acceptance criteria.

Missing, doubtful or inconsistent points are put to the user as questions, never silently guessed. The review first resolves what it can from the codebase and context, and only asks the user for the rest.

flowchart LR A["/iru-draft-github-issue\ninterview + draft file"] --> B["iru-review-github-issue\n(loop, max 5 rounds)"] B -- findings --> C["Resolve from codebase\nor ask the user"] C --> B B -- no gaps --> D{"Issue too large?"} D -- yes --> E["iru-split-github-issue\nroot + sub-issues + milestone"] D -- no --> F["Show draft, confirm"] F --> G["gh issue create"] E --> H(["Issues ready for\n/iru-issue or /iru-plan"]) G --> H

Splitting, milestones and dependencies

A split proposes the sub-issues first and creates nothing until the user confirms. Size is judged from concrete signals: more than about seven acceptance criteria or requirements, more than one independently deliverable capability, more than one module or area touched, or an estimate of hard or above. A split always creates a milestone tracking all the sub-issues. Dependencies are recorded in three redundant places:

  • GitHub sub-issues link each child to the root issue.

  • Each sub-issue body has a Blocked by: #N, #M line (or Blocked by: none) and a Parallel group: <n> line. The same group number means independent, so those issues can proceed in parallel.

  • The root issue carries an ordered table of groups (group, issues, parallelizable).

Sub-issues are created in dependency order so Blocked by can reference real issue numbers.

Quick path or detailed path?

Use iru-create-github-issue (or iru-create-jira-ticket) for a simple, well-understood task. Use iru-draft-github-issue when the issue is a feature or documentation effort that needs full requirements and acceptance criteria, or may be large enough to split. iru-review-github-issue can also be run on its own on an existing issue before picking it up with /iru-issue.

Where this fits

Filing a ticket this way is entirely optional — nothing in the typical development cycle requires going through either skill first. /iru-issue <ticket-id> and /iru-plan <ticket-id> work exactly the same way against a ticket filed by hand, or even against no ticket at all (a free-form description). What these two skills add is consistency: every draft is grounded in the real codebase and asks for the same structured information, rather than depending on whoever’s filing it to remember what a well-formed ticket needs.

See also