jira · diff
git:20260519.ea65ce0 to git:20260613.740355d
1 added, 1 removed. Audit A to A.
---
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](review.md) |
+ | `review <JIRA_ID>` | **review** | Full qualification review of any Jira ticket — delegates to [references/review.md](references/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:
```markdown
## 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
```bash
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
```yaml
---
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
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
```bash
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:**
```markdown
## 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:
| 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`:
```markdown
## 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:
```markdown
## 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`):
```markdown
**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](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.