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:

• 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:

1. Prompt the user for it.
2. 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)"                                                # Project name
git branch --show-current                                        # Local branch
git rev-parse --abbrev-ref --symbolic-full-name @{upstream} 2>/dev/null || echo "none"
git rev-parse HEAD                                               # Full SHA
git rev-parse --short HEAD                                       # Short SHA
git log -1 --format="%ci"                                        # Commit date
git log -1 --format="%s"                                         # Commit subject
git status --porcelain | head -1                                 # Dirty check

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

Step 1: Load Context

1. Capture git context (commands above).
2. 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.
3. Read the track's plan.md for phases and tasks.
4. Read the track's metadata.json for title and type.
5. Read the track's spec.md for root-issue description.
6. 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
7. 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

1. Parse findings by severity (Critical, High, Medium, Low).
2. 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.
3. Group by severity for the export.

From review-report-latest.md

1. 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).
2. Extract for each finding: Severity (Critical ✗ / Warning ⚠), Category, Location, Issue, Risk/Impact, Fix.
3. 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

1. Capture git context (commands above).
2. Find the active track from draft/tracks.md. If a track ID is provided in $ARGUMENTS, use that.
3. 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:

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.