| name | jira |
| description | Unified Jira entry point. Routes to preview (default), create, or review subcommands. |
Jira
Single entry point for all Jira workflows: preview Draft tracks as Jira issues, create them via MCP (default = 1 Story per track; --epic = 1 Epic + 1-3 Stories), and review any Jira ticket (epic, story, bug, sub-task) end-to-end.
Subcommand Routing
Parse $ARGUMENTS and dispatch:
| User Intent | Subcommand | Behavior |
|---|
(no args), preview, preview <track-id> | preview (default) | Generate jira-export-<timestamp>.md — one Story containing all phases/tasks |
preview --epic ... | preview --epic | Generate rich export: 1 Epic + 1–3 Stories (max) |
create, create <track-id> | create | Create 1 Story (default) via MCP |
review <JIRA_ID> | review | Full qualification review of any Jira ticket — delegates to review.md |
preview is the default when no subcommand is supplied.
review requires a Jira ID as the next argument. Validate format <PROJECT>-<NUMBER> (e.g., ENG-446236). If numeric-only, prompt for project prefix — do NOT assume.
Jira Configuration (Shared)
All subcommands read project-level Jira configuration from draft/workflow.md under a ## Jira section:
## Jira
Project Key: <KEY>
Integration: jira-mcp
Team: <team-name>
Component: <component-name>
Swimlane: <swimlane-name>
Assignee Display Name: <assignee-name>
- Project Key — required for
create. If missing, prompt and persist.
- Integration — informational; defaults to
jira-mcp if absent.
- Team / Component / Swimlane / Assignee Display Name — applied as defaults to every issue created by
create. Empty values are skipped (Jira ignores blank fields).
If a value is missing when needed:
- Prompt the user for it.
- Append to (or create) the
## Jira section in draft/workflow.md so subsequent runs reuse it.
Jira Content Hygiene (Mandatory)
When writing any text that will go into Jira (descriptions, summaries, bug details):
- Be minimal, concise, and precise.
- Do not dump full plans, long task lists, verbose context, or Draft-internal reasoning into Jira.
- Use short summaries + key outcomes only.
- Structured content (phases, tasks) may be included as compact markdown, but keep it brief.
- Never pollute Jira with excessive text.
This rule applies to both preview generation and create descriptions.
Subcommand: preview
Generate a timestamped jira-export-<timestamp>.md (with jira-export-latest.md symlink) from the active track's plan for review and editing before creating Jira issues.
Flag handling: Check $ARGUMENTS for --epic at the very start of this section. If present, set EPIC_MODE=true and remove the flag from the working arguments. This flag changes the entire output structure (see Step 2).
Red Flags — STOP if you're:
- Generating a preview without an approved plan.md
- Assigning story points inconsistent with task count
- Missing sub-tasks that exist in plan.md
- Not including quality findings when review/bughunt reports exist
- Overwriting a reviewed jira-export without warning the user
Plan first, then preview. Accuracy over speed.
Standard File Metadata
The generated jira-export-<timestamp>.md MUST include the standard YAML frontmatter for traceability and sync verification.
Gathering Git Information
basename "$(pwd)"
git branch --show-current
git rev-parse --abbrev-ref --symbolic-full-name @{upstream} 2>/dev/null || echo "none"
git rev-parse HEAD
git rev-parse --short HEAD
git log -1 --format="%ci"
git log -1 --format="%s"
git status --porcelain | head -1
Metadata Template
---
project: "{PROJECT_NAME}"
module: "root"
track_id: "{TRACK_ID}"
generated_by: "draft:jira:preview"
generated_at: "{ISO_TIMESTAMP}"
git:
branch: "{LOCAL_BRANCH}"
remote: "{REMOTE/BRANCH or 'none'}"
commit: "{FULL_SHA}"
commit_short: "{SHORT_SHA}"
commit_date: "{COMMIT_DATE}"
commit_message: "{FIRST_LINE_OF_COMMIT_MESSAGE}"
dirty: {true|false}
synced_to_commit: "{FULL_SHA}"
---
Mapping Structure
Default behavior (recommended)
- Every track becomes exactly 1 Story.
- All phases and their tasks are included inside the Story description (as markdown sections).
- No child Jira issues are created.
This keeps Jira clean and keeps the export focused on root issues by default.
Opt-in rich hierarchy (--epic)
Use /draft:jira preview --epic or /draft:jira create --epic when you want an Epic.
Splitting rule (simple):
- 5 or fewer phases → 1 Story under the Epic
- More than 5 phases → split across 2 or 3 Stories (maximum)
All detailed tasks remain inside the Story descriptions — we never create Jira Tasks or Sub-tasks.
Summary of mappings
| Flag | Root Issue | Child Issues | Where phases/tasks live |
|---|
| (default) | 1 Story | None | Inside the single Story description |
--epic | 1 Epic | 1–3 Stories (max) | Distributed across the Story descriptions |
Step 1: Load Context
- Capture git context (commands above).
- Find the active track from
draft/tracks.md (look for [~] In Progress or first [ ]). If a track ID is provided in $ARGUMENTS, use that instead.
- Read the track's
plan.md for phases and tasks.
- Read the track's
metadata.json for title and type.
- Read the track's
spec.md for root-issue description.
- Check for quality reports:
draft/tracks/<id>/review-report-latest.md — review findings (from /draft:review)
draft/tracks/<id>/bughunt-report-latest.md — defect findings
- Read
draft/workflow.md → ## Jira section for shared config (see Jira Configuration above).
If no track found: tell the user "No track found. Run /draft:new-track to create one, or specify track ID."
Step 2: Determine Export Mode, Count Phases, and Group Content
2.1 Detect Mode
- If
EPIC_MODE=true (from --epic flag), use Epic + Stories mode.
- Otherwise, use default single-Story mode.
2.2 Count Phases and Decide Story Count (Epic Mode Only)
Count the number of ## Phase sections in plan.md.
Splitting guideline (when using --epic):
- Phases ≤ 5 → 1 Story under the Epic
- Phases 6–12 → 2 Stories under the Epic
- Phases > 12 → 3 Stories under the Epic (hard cap)
Store the target number of stories: TARGET_STORIES.
2.3 Group Phases (for Epic Mode)
Divide the phases as evenly as possible across TARGET_STORIES.
Example grouping (store this in memory):
- Story 1 gets phases 1..K
- Story 2 gets phases K+1..M
- Story 3 gets remaining phases
In default mode, ignore grouping — everything goes under one Story.
2.4 Build Data Structures
For every phase:
- Capture Phase name, Goal, Verification
- Collect all its tasks (with status)
Calculate total story points using the existing simple table (1-2 tasks = 1pt, 3-4=2pt, 5-6=3pt, 7+=5pt). This total goes on the root issue (or split across stories in epic mode if desired — default is to put total on the first Story).
2.5 Root Issue Data
- Summary = Track title
- Description base = content from
spec.md (first 2-3 paragraphs) + later the full structured plan
- Issue Type = "Story" (default) or "Epic" (--epic)
Step 3: Extract Quality Findings (if reports exist)
If review-report-latest.md or bughunt-report-latest.md exists in the track directory:
From bughunt-report-latest.md
- Parse findings by severity (Critical, High, Medium, Low).
- Extract all sections for each bug: Location, Confidence, Code Evidence, Data Flow Trace, Issue, Impact, Verification Done, Why Not a False Positive, Fix, Regression Test.
- Group by severity for the export.
From review-report-latest.md
- Parse findings from review report stages — Stage 1: Automated Validation (Architecture Conformance, Dead Code, Dependency Cycles, Security Scan, Performance), Stage 2: Spec Compliance, Stage 3: Code Quality (Architecture, Error Handling, Testing, Maintainability).
- Extract for each finding: Severity (Critical ✗ / Warning ⚠), Category, Location, Issue, Risk/Impact, Fix.
- Group by severity for the export.
Critical/High findings should be highlighted — consider suggesting additional stories or tasks to address them before the track is complete.
Step 4: Generate the Export File
TIMESTAMP=$(date +%Y-%m-%dT%H%M)
EXPORT_FILE="draft/tracks/<track_id>/jira-export-${TIMESTAMP}.md"
SYMLINK="draft/tracks/<track_id>/jira-export-latest.md"
Create the file and the latest symlink.
4.1 Write Frontmatter + Header
Use the standard YAML frontmatter.
Add a mode: default or mode: epic field.
Write a clean summary table.
4.2 Write Root Issue Section
Jira Content Rule: Keep the description minimal and focused. Use short paragraphs. Do not dump full plans or verbose reasoning. Structured phases/tasks must be compact.
Always start with:
## Root Issue
**Summary:** [Track Title]
**Issue Type:** Story # or Epic when --epic
**Labels:** draft
**Description:**
{noformat}
[First 2-3 paragraphs from spec.md]
## Plan
Then render the plan content concisely:
- In default mode: Render all phases as
### Phase X: Name headings, with Goal, Verification, and a compact task checklist under each.
- In --epic mode: If this is the root Epic section, put a short overview only.
Include the Draft signature at the bottom of the description.
4.3 Write Story Sections (only in --epic mode)
Jira Content Rule: Keep every Story description short and scannable. Use compact headings and minimal text.
If mode: epic:
- Emit 1 to 3
## Story N: [Short Title] blocks (using the grouping decided in Step 2).
- Under each Story, put the phases assigned to it as
### Phase ... + compact task checklists.
- Each Story gets its share of the total story points (or put the total on the first one — simple is fine).
4.4 Write Bug Issues Section (always)
Use the existing high-quality bug export format from bughunt-report-latest.md.
These will become real Bug issues linked to the root (Epic or the main Story).
4.5 Final Notes in the Export
Add at the top:
Default = 1 Story. Use --epic for 1 Epic + 1-3 Stories.
Update the symlink.
Step 5: Report
Jira Preview Generated
Track: [track_id] - [title]
Mapping: [story-rooted | epic-rooted] (phases: N)
Export: draft/tracks/<id>/jira-export-<timestamp>.md
Symlink: draft/tracks/<id>/jira-export-latest.md
Summary:
- 1 root issue ({Story | Epic})
- N mid-level issues ({Tasks | Stories})
- M leaf issues (Sub-tasks)
- P total story points
- B bugs (from bughunt-report-latest.md)
Breakdown:
- Phase 1: [name] - X pts, Y tasks
- Phase 2: [name] - X pts, Y tasks
- ...
Bugs (if bughunt-report-latest.md exists):
- X critical bugs
- Y high bugs
- Z medium/low bugs
Next steps:
1. Review and edit the export via jira-export-latest.md (adjust points, descriptions, leaf issues, bug priorities)
2. Run `/draft:jira create` to create issues in Jira
Error Handling (preview)
plan.md has no phases:
- Tell user: "No phases found in plan.md. Run
/draft:new-track to generate a proper plan."
spec.md missing:
- Use
plan.md overview for root-issue description.
- Warn: "spec.md not found, using plan overview for root-issue description."
jira-export-latest.md already exists:
- Check if the target file has been manually modified (user-added content not matching generated patterns — edited descriptions, added rows, changed story points from generated values).
- If modifications detected, prompt: "Existing jira-export appears to have manual edits. Overwrite? [y/N]"
- If unmodified, proceed with regeneration (new timestamped file + updated symlink).
Phase has no tasks:
- Create mid-level issue with 1 story point.
- Add note: "No leaf issues defined for this phase."
Subcommand: create
Create Jira issues from jira-export-latest.md using MCP-Jira. If no export file exists, auto-generates one first by running the preview subcommand.
Red Flags — STOP if you're:
- Creating Jira issues without reviewing
jira-export-latest.md first (run /draft:jira preview)
- Proceeding when MCP-Jira is not configured
- Creating duplicate issues (check if jira-export-latest.md already has Jira keys)
- Not verifying the target Jira project before creation
- Skipping the export file update after issue creation
Preview before you create. Never create duplicates.
Default = 1 Story only. Use --epic when you want an Epic + 1–3 Stories. We never create Jira Tasks or Sub-tasks.
Step 1: Load Context
- Capture git context (commands above).
- Find the active track from
draft/tracks.md. If a track ID is provided in $ARGUMENTS, use that.
- Check for
draft/tracks/<track_id>/jira-export-latest.md.
If no track found: tell user "No track found. Run /draft:new-track to create one, or specify track ID."
Step 2: Ensure Export Exists
If jira-export-latest.md exists: read and parse it (follow the symlink to the timestamped file). Proceed to Step 3.
If missing: inform user "No jira-export-latest.md found. Generating preview first..." then execute the preview subcommand. Proceed to Step 3.
Step 3: Check MCP-Jira Availability
Detect MCP-Jira tools. Known tool name variants: mcp_jira_create_issue, jira_createIssue, create_jira_issue, jira-create-issue. Use whichever is available.
If unavailable:
MCP-Jira not configured.
To create issues:
1. Configure MCP-Jira server in your settings
2. Run `/draft:jira create` again
Or manually import from:
draft/tracks/<id>/jira-export-latest.md
Stop execution.
Step 4: Parse Export File (Export Format)
Read the mode field from frontmatter:
default → expect 1 root Story
epic → expect 1 Epic + 1–3 Stories
Root Issue(s)
- Parse the
## Root Issue (and any ## Story N: sections if mode=epic).
- For each Story section: Summary, Description (which now contains the phases and task checklists), story points if present.
Bug Issues
Parse the ## Bug Issues section completely (same as before). These are always created as separate Bug issues.
Important: There are no longer "Mid-Level" or "Leaf Issues" tables that become separate Jira Tasks/Sub-tasks. All work items live inside the Story description(s).
Step 4b: Resolve Jira Configuration
Read draft/workflow.md → ## Jira section. Required fields and behavior:
| Field | Required? | Behavior if missing |
|---|
| Project Key | Yes | Prompt user; append to ## Jira section |
| Integration | No | Defaults to jira-mcp |
| Team | No | Skip — not applied to issues |
| Component | No | Skip |
| Swimlane | No | Skip |
| Assignee Display Name | No | Skip |
When prompting for a missing field, append to draft/workflow.md:
## Jira
Project Key: <KEY>
Integration: jira-mcp
Team: <team-name>
Component: <component-name>
Swimlane: <swimlane-name>
Assignee Display Name: <assignee-name>
Validate Project Key
Before creating issues, attempt to fetch project metadata via MCP to verify the project key exists:
MCP call: get_project (or equivalent)
- project: [project key]
If invalid: "Jira project '[KEY]' not found. Verify the project key and try again." Stop execution.
Resolve Assignee
If Assignee Display Name is provided, resolve to an account ID via MCP user search (e.g., find_users(query=<display_name>)). Cache the resolved ID for the session. If resolution fails, warn and create issues unassigned rather than failing.
Step 5: Create Issues via MCP
Pin the symlink target: At the start of this step, resolve the symlink to its actual timestamped file path (e.g., via readlink -f jira-export-latest.md). Use the resolved path for all subsequent writes to prevent data loss if the symlink is updated mid-run.
Incremental persistence: After creating each issue, immediately update the corresponding entry in the export file with the Jira key. This ensures re-runs can skip already-created items even if the process fails mid-way.
Note: Some Jira configurations do not allow setting status during creation. If status setting fails, create in default status and log a warning.
Shared field defaults
Apply these to every create_issue call (omit any that resolved to empty in Step 4b):
- project: [Project Key]
- labels: ["draft"]
- component: [Component if set]
- assignee: [Resolved account ID if set]
- custom_field_swimlane: [Swimlane if set] # field ID is Jira-config specific
- custom_field_team: [Team if set] # field ID is Jira-config specific
Swimlane and Team are often custom fields. If your Jira project uses different field IDs, configure your MCP server's field mapping. Unknown fields will be rejected — log the rejection and continue without them.
5a. Create Root Issue(s)
- If mode = default: Create 1 Story.
- If mode = epic: Create 1 Epic, then create the 1–3 Stories (using the sections from the export file) and link them to the Epic.
For each Story/Epic:
Jira Content Rule (strict): The description sent to Jira must be concise. Use short summaries and compact structured sections only. Do not include long reasoning or exhaustive lists.
MCP call: create_issue
- issue_type: Story or Epic
- summary: ...
- description: [concise content — phases as compact sections, tasks as short checklists]
+ shared field defaults
Capture the keys.
5b. Create Bug Issues (from Bug Hunt Report)
For every bug parsed in Step 4, create a real Bug issue:
MCP call: create_issue
- issue_type: Bug
- summary: ...
- description: [full bughunt evidence]
- parent / epic_link: [link to the root Story or Epic]
- priority: [from severity]
+ shared field defaults
Detailed work lives inside the root issue description(s) by default. All detailed work lives inside the Story descriptions.
Step 6: Finalize Tracking
Export file has already been updated incrementally during Step 5. Now update plan.md with the Jira keys:
## Phase 1: Setup [PROJ-124]
...
- [x] **Task 1.1:** Extract logging utilities [PROJ-125]
- [x] **Task 1.2:** Extract security utilities [PROJ-126]
Set export file status to Created (via jira-export-latest.md):
**Status:** Created
**Root Key:** PROJ-123
Step 7: Report (new simplified format)
Jira Issues Created
Track: [track_id] - [title]
Project: [PROJ]
Mode: {default → 1 Story | --epic → 1 Epic + 1-3 Stories}
Created:
- {Story | Epic}: PROJ-123 - [Track title]
(All phases and tasks are inside the Story description)
Bugs (from Bug Hunt) — always created as separate issues:
- Bug: PROJ-131 - [Critical] Correctness: Off-by-one error in pagination (linked to PROJ-123)
- Bug: PROJ-132 - [High] ...
Total: 1 root issue + B bugs
Label: "draft" applied to all issues
Updated:
- plan.md (added root Jira key)
- jira-export-latest.md (marked as created)
Error Handling (create)
MCP call fails:
Failed to create [issue type]: [error message]
Partial creation:
- {Story | Epic}: PROJ-123 (created)
- Mid-level 1: PROJ-124 (created)
- Leaf 1.1: PROJ-125 (created)
- Leaf 1.2: FAILED - [error]
- Mid-level 2: (skipped)
Fix the issue and run `/draft:jira create` again.
Already-created issues will be detected by keys in jira-export-latest.md.
Export has existing keys: skip items that already have keys; only create items without keys. Report "Skipped Mid-level 1 (already exists: PROJ-124)". Still create leaves if mid-level exists but leaves don't have keys.
Project not configured: see Step 4b.
plan.md phases don't match export: warn "Export has N mid-level issues but plan has M phases. Proceeding with export structure." Create based on export.
Subcommand: review
See review.md for the full epic/story/bug/sub-task qualification pipeline. The router delegates to that file when the user invokes /draft:jira review <JIRA_ID>.
The review subcommand:
- Accepts any Jira issue ID (epic, story, bug, sub-task) and adapts its depth to the issue type.
- Runs a 7-phase pipeline: prerequisites → epic/story collection → document/test-plan synthesis → code change collection (Gerrit/GitHub/GitLab) → context synthesis → quality analysis (deep-review + bughunt + coverage) → test gap analysis → report.
- Produces
draft/jira-review/<JIRA_ID>/qualification-report.md and (if gaps exist) remediation-plan.md.
- Verdict: QUALIFIED / PARTIALLY QUALIFIED / NOT QUALIFIED.