jira-syntax

Original source / Raw SKILL.md

---
name: "jira-syntax"
description: "Jira wiki markup syntax validation, templates, and formatting guidance. Use when: (1) Writing Jira issue descriptions or comments, (2) Converting Markdown to Jira wiki markup, (3) Requesting bug report or feature request templates, (4) Validating Jira syntax before submission, (5) Keywords like 'jira format', 'wiki markup', 'jira syntax', 'format for jira', (6) Ensuring content uses h2./h3. headings instead of Markdown ##, (7) Checking code blocks use {code:lang} not triple backticks, (8) Any task involving Jira text formatting"
---

# Jira Syntax Validation Skill

Provides Jira wiki markup syntax validation, templates, and formatting guidance. For API operations, use the **jira-communication** skill.

## Quick Syntax Reference

| Jira Syntax | Purpose | NOT this (Markdown) |
|-------------|---------|---------------------|
| `h2. Title` | Heading | `## Title` |
| `*bold*` | Bold | `**bold**` |
| `_italic_` | Italic | `*italic*` |
| `{{code}}` | Inline code | `` `code` `` |
| `{code:java}...{code}` | Code block | ``` ```java ``` |
| `[text\|url]` | Link | `[text](url)` |
| `[PROJ-123]` | Issue link | - |
| `[~username]` | User mention | `@username` |
| `* item` | Bullet list | `- item` |
| `# item` | Numbered list | `1. item` |
| `\|\|Header\|\|` | Table header | `\|Header\|` |

See `references/jira-syntax-quick-reference.md` for complete syntax documentation.

## Available Templates

### Bug Report
**Path**: `templates/bug-report-template.md`

Sections: Environment, Steps to Reproduce, Expected/Actual Behavior, Error Messages, Technical Notes

### Feature Request
**Path**: `templates/feature-request-template.md`

Sections: Overview, User Stories, Acceptance Criteria, Technical Approach, Success Metrics

## Syntax Validation

Run before submitting to Jira:
```bash
scripts/validate-jira-syntax.sh path/to/content.txt
```

### Validation Checklist
- [ ] Headings: `h2. Title` (space after period)
- [ ] Bold: `*text*` (single asterisk)
- [ ] Code blocks: `{code:language}...{code}`
- [ ] Lists: `*` for bullets, `#` for numbers
- [ ] Links: `[label|url]` or `[PROJ-123]`
- [ ] Tables: `||Header||` and `|Cell|`
- [ ] Colors: `{color:red}text{color}`
- [ ] Panels: `{panel:title=X}...{panel}`

### Common Mistakes

| ❌ Wrong | ✅ Correct |
|---------|-----------|
| `## Heading` | `h2. Heading` |
| `**bold**` | `*bold*` |
| `` `code` `` | `{{code}}` |
| `[text](url)` | `[text\|url]` |
| `- bullet` | `* bullet` |
| `h2.Title` | `h2. Title` |

## Integration with jira-communication Skill

**Workflow:**
1. Get template from jira-syntax
2. Fill content using Jira wiki markup
3. Validate with `scripts/validate-jira-syntax.sh`
4. Submit via jira-communication scripts (e.g., `uv run scripts/workflow/jira-create.py`)

## References

- `references/jira-syntax-quick-reference.md` - Complete syntax documentation
- `templates/bug-report-template.md` - Bug report template
- `templates/feature-request-template.md` - Feature request template
- `scripts/validate-jira-syntax.sh` - Automated syntax checker
- [Official Jira Wiki Markup](https://jira.atlassian.com/secure/WikiRendererHelpAction.jspa?section=all)


---

## Referenced Files

> The following files are referenced in this skill and included for context.

### scripts/validate-jira-syntax.sh

```bash
#!/bin/bash

# Jira Wiki Markup Syntax Validator
# Checks text for common Jira syntax errors and suggests corrections

set -e

# Colors for output
RED='\033[0;31m'
YELLOW='\033[1;33m'
GREEN='\033[0;32m'
NC='\033[0m' # No Color

# Counters
ERRORS=0
WARNINGS=0

# Function to print error
error() {
    echo -e "${RED}❌ ERROR:${NC} $1"
    ((ERRORS++))
}

# Function to print warning
warning() {
    echo -e "${YELLOW}⚠️  WARNING:${NC} $1"
    ((WARNINGS++))
}

# Function to print success
success() {
    echo -e "${GREEN}✅ $1${NC}"
}

# Function to check file
validate_file() {
    local file="$1"
    echo ""
    echo "=========================================="
    echo "Validating: $file"
    echo "=========================================="

    if [ ! -f "$file" ]; then
        error "File not found: $file"
        return
    fi

    local content=$(cat "$file")
    local line_num=0

    # Check for Markdown-style headings (## instead of h2.)
    if echo "$content" | grep -qE "^##+ "; then
        error "Found Markdown-style headings (##). Use Jira format: h2. Heading"
        echo "   Lines with issue:"
        echo "$content" | grep -nE "^##+ " | head -5
    fi

    # Check for Markdown-style bold (**text** instead of *text*)
    if echo "$content" | grep -qE "\*\*[^*]+\*\*"; then
        warning "Found Markdown-style bold (**text**). Use Jira format: *text*"
        echo "   Examples found:"
        echo "$content" | grep -oE "\*\*[^*]+\*\*" | head -3
    fi

    # Check for Markdown-style italic (_text_ is ok, but *text* for bold might be confused)
    if echo "$content" | grep -qE "\*[^*]+\*\*[^*]+\*"; then
        warning "Found potential Markdown-style italic mixed with bold"
    fi

    # Check for Markdown-style code blocks (``` instead of {code})
    if echo "$content" | grep -qE "^\`\`\`"; then
        error "Found Markdown code blocks (\`\`\`). Use Jira format: {code:language}"
        echo "   Lines with issue:"
        echo "$content" | grep -nE "^\`\`\`" | head -5
    fi

    # Check for Markdown-style inline code (` instead of {{)
    if echo "$content" | grep -qE "\`[^\`]+\`" && ! echo "$content" | grep -qE "{{[^}]+}}"; then
        warning "Found Markdown inline code (\`code\`). Consider Jira format: {{code}}"
    fi

    # Check for Markdown-style links ([text](url) instead of [text|url])
    if echo "$content" | grep -qE "\[([^\]]+)\]\(([^)]+)\)"; then
        error "Found Markdown-style links ([text](url)). Use Jira format: [text|url]"
        echo "   Examples found:"
        echo "$content" | grep -oE "\[([^\]]+)\]\(([^)]+)\)" | head -3
    fi

    # Check for headings without space after period (h2.Title instead of h2. Title)
    if echo "$content" | grep -qE "^h[1-6]\.[^ ]"; then
        error "Found headings without space after period. Use: h2. Title (not h2.Title)"
        echo "   Lines with issue:"
        echo "$content" | grep -nE "^h[1-6]\.[^ ]" | head -5
    fi

    # Check for code blocks without language specification
    if echo "$content" | grep -qE "{code}[^{]"; then
        warning "Found {code} blocks without language. Consider: {code:java} for syntax highlighting"
    fi

    # Check for tables with incorrect header syntax (|Header| instead of ||Header||)
    if echo "$content" | grep -qE "^\|[^|]+\|$" && ! echo "$content" | grep -qE "^\|\|"; then
        warning "Potential table header without double pipes. Headers should use: ||Header||"
    fi

    # Check for unclosed {code} blocks
    local code_open=$(echo "$content" | grep -c "{code")
    local code_close=$(echo "$content" | grep -c "{/code}")
    if [ "$code_open" -ne "$code_close" ]; then
        error "Mismatched {code} tags: $code_open opening, $code_close closing"
    fi

    # Check for unclosed {panel} blocks
    local panel_open=$(echo "$content" | grep -c "{panel")
    local panel_close=$(echo "$content" | grep -c "{/panel}")
    if [ "$panel_open" -ne "$panel_close" ]; then
        error "Mismatched {panel} tags: $panel_open opening, $panel_close closing"
    fi

    # Check for unclosed {color} blocks
    local color_count=$(echo "$content" | grep -o "{color" | wc -l)
    if [ $((color_count % 2)) -ne 0 ]; then
        warning "Potential unclosed {color} tag (odd number of occurrences)"
    fi

    # Check for Markdown-style lists (- item instead of * item)
    if echo "$content" | grep -qE "^- [^-]"; then
        warning "Found Markdown-style bullets (- item). Jira prefers: * item"
    fi

    # Positive checks
    if echo "$content" | grep -qE "^h[1-6]\. "; then
        success "Found correctly formatted Jira headings"
    fi

    if echo "$content" | grep -qE "{code:[a-z]+}"; then
        success "Found code blocks with language specification"
    fi

    if echo "$content" | grep -qE "\[~[a-z.]+\]"; then
        success "Found user mentions ([~username])"
    fi

    if echo "$content" | grep -qE "\[[A-Z]+-[0-9]+\]"; then
        success "Found issue links ([PROJ-123])"
    fi
}

# Main script
echo "Jira Wiki Markup Syntax Validator"
echo "=================================="

if [ $# -eq 0 ]; then
    echo "Usage: $0 <file1> [file2] [file3] ..."
    echo ""
    echo "Validates Jira wiki markup syntax in text files"
    echo ""
    echo "Example:"
    echo "  $0 issue-description.txt"
    echo "  $0 templates/*.md"
    exit 1
fi

# Validate each file
for file in "$@"; do
    validate_file "$file"
done

# Summary
echo ""
echo "=========================================="
echo "Validation Summary"
echo "=========================================="
echo "Files checked: $#"
echo -e "${RED}Errors: $ERRORS${NC}"
echo -e "${YELLOW}Warnings: $WARNINGS${NC}"

if [ $ERRORS -eq 0 ] && [ $WARNINGS -eq 0 ]; then
    echo -e "${GREEN}✅ All checks passed!${NC}"
    exit 0
elif [ $ERRORS -eq 0 ]; then
    echo -e "${YELLOW}⚠️  No errors, but $WARNINGS warnings found${NC}"
    exit 0
else
    echo -e "${RED}❌ $ERRORS errors found - please fix before submitting to Jira${NC}"
    exit 1
fi

```

### references/jira-syntax-quick-reference.md

```markdown
# Jira Wiki Markup Syntax - Quick Reference

Complete reference for Jira's wiki markup syntax to ensure proper formatting in tickets, comments, and descriptions.

## Table of Contents

- [Text Formatting](#text-formatting)
- [Headings](#headings)
- [Lists](#lists)
- [Links](#links)
- [Code Blocks](#code-blocks)
- [Tables](#tables)
- [Panels and Quotes](#panels-and-quotes)
- [Colors](#colors)
- [Special Blocks](#special-blocks)
- [Line Breaks and Horizontal Rules](#line-breaks-and-horizontal-rules)
- [Special Characters](#special-characters)
- [Emoticons](#emoticons)
- [Common Patterns](#common-patterns)
- [Validation Checklist](#validation-checklist)
- [Common Mistakes to Avoid](#common-mistakes-to-avoid)

## Text Formatting

| Syntax | Output | Use Case |
|--------|--------|----------|
| `*text*` | **text** | Bold/strong emphasis |
| `_text_` | *text* | Italic/emphasis |
| `{{text}}` | `text` | Monospace for code/paths |
| `-text-` | ~~text~~ | Strikethrough |
| `+text+` | <u>text</u> | Underline/inserted text |
| `^text^` | text^superscript^ | Superscript |
| `~text~` | text~subscript~ | Subscript |
| `??text??` | text (citation) | Citation format |

## Headings

```
h1. Heading Level 1 (largest)
h2. Heading Level 2
h3. Heading Level 3
h4. Heading Level 4
h5. Heading Level 5
h6. Heading Level 6 (smallest)
```

**Rules:**
- Space required after `h1.` through `h6.`
- One heading per line
- Use h2 for main sections, h3 for subsections

## Lists

### Bulleted Lists
```
* Level 1 item
** Level 2 nested item
*** Level 3 nested item
* Another level 1 item
```

### Numbered Lists
```
# First item
## Nested item
## Another nested item
# Second item
```

### Mixed Lists
```
# Numbered item
#* Nested bullet
#* Another bullet
# Another numbered item
```

**Rules:**
- Space after `*` or `#`
- Nesting uses additional symbols (`**`, `##`)
- Can mix list types with combined syntax (`#*`)

## Links

| Type | Syntax | Example |
|------|--------|---------|
| Issue Link | `[KEY-123]` | `[PROJ-456]` |
| User Mention | `[~username]` | `[~john.doe]` |
| External URL | `[http://url]` | `[http://example.com]` |
| Labeled Link | `[Label\|url]` | `[Google\|http://google.com]` |
| Attachment | `[^filename]` | `[^screenshot.png]` |
| Email | `[mailto:email]` | `[mailto:[email protected]]` |
| Anchor | `{anchor:name}` + `[#name]` | `{anchor:intro}` → `[#intro]` |

## Code Blocks

### Inline Code
```
Use {{code}} for inline monospace text
```

### Code Blocks with Syntax Highlighting
```
{code:java}
public class Example {
    public static void main(String[] args) {
        System.out.println("Hello, World!");
    }
}
{code}
```

**Supported Languages:**
- `java`, `javascript`, `python`, `sql`, `xml`, `json`
- `bash`, `shell`, `php`, `ruby`, `go`, `rust`
- `html`, `css`, `typescript`, `c`, `cpp`, `csharp`
- Many more - check Jira documentation

### Preformatted Text (No Highlighting)
```
{noformat}
Plain text without syntax highlighting
Preserves whitespace and formatting
{noformat}
```

## Tables

### Basic Table
```
||Header 1||Header 2||Header 3||
|Cell A1|Cell A2|Cell A3|
|Cell B1|Cell B2|Cell B3|
```

**Rules:**
- `||` for header cells (double pipe)
- `|` for regular cells (single pipe)
- Rows must have same number of cells
- No trailing pipe at end of row

### Example with Content
```
||Feature||Status||Owner||Priority||
|User Login|{color:green}Complete{color}|[~john.doe]|High|
|Password Reset|{color:yellow}In Progress{color}|[~jane.smith]|Medium|
|2FA|{color:red}Not Started{color}|Unassigned|Low|
```

## Panels and Quotes

### Panel with Title and Background
```
{panel:title=Important Information|bgColor=#FFFFCE}
Content inside the panel
{panel}
```

**Panel Parameters:**
- `title=text` - Panel heading
- `bgColor=#HEXCODE` - Background color
- `borderStyle=solid|dashed` - Border style
- `borderColor=#HEXCODE` - Border color
- `titleBGColor=#HEXCODE` - Title background

### Quote Block
```
{quote}
Multi-line quoted text
Can span multiple paragraphs
{quote}
```

### Single Line Quote
```
bq. This is a block quote on one line
```

## Colors

```
{color:red}Red text{color}
{color:blue}Blue text{color}
{color:green}Green text{color}
{color:#FF0000}Hex color text{color}
```

**Named Colors:**
- `red`, `blue`, `green`, `yellow`, `orange`, `purple`
- `black`, `white`, `gray`, `grey`
- Or use hex codes: `#FF0000`, `#00FF00`, `#0000FF`

## Special Blocks

### Notice/Info Panels
```
{panel:title=⚠️ Warning|bgColor=#FFEBE9|borderColor=#FF0000}
This is a warning message
{panel}

{panel:title=ℹ️ Information|bgColor=#DEEBFF|borderColor=#0052CC}
This is an info message
{panel}

{panel:title=✅ Success|bgColor=#E3FCEF|borderColor=#00875A}
This is a success message
{panel}
```

### Expand/Collapse Section
```
{expand:title=Click to expand}
Hidden content that can be toggled
{expand}
```

## Line Breaks and Horizontal Rules

```
Line 1\\
Line 2 (line break with \\)

First paragraph

Second paragraph (blank line creates new paragraph)

----
Horizontal rule (4 dashes)
```

## Special Characters

```
--- (em-dash: —)
-- (en-dash: –)
\\ (line break)
\{escaped brace\}
```

To escape special characters, use backslash: `\*`, `\{`, `\[`

## Emoticons

| Code | Emoji | Meaning |
|------|-------|---------|
| `:)` | 🙂 | Happy |
| `:(` | 🙁 | Sad |
| `:P` | 😛 | Tongue |
| `:D` | 😀 | Big smile |
| `;)` | 😉 | Wink |
| `(y)` | 👍 | Thumbs up |
| `(n)` | 👎 | Thumbs down |
| `(!)` | ⚠️ | Warning |
| `(?)` | ❓ | Question |
| `(on)` | 💡 | Light bulb on |
| `(off)` | 🔌 | Light bulb off |
| `(*)` | ⭐ | Star |

## Common Patterns

### Status Update Comment
```
h3. Status Update - 2025-11-06

h4. Completed
* Implemented user authentication
* Added unit tests (95% coverage)
* Updated documentation

h4. In Progress
* Integration testing
* Performance optimization

h4. Blocked
* Waiting for API key from [~admin]
* See [PROJ-123] for details

h4. Next Steps
# Deploy to staging environment
# Conduct security review
# Schedule production deployment
```

### Code Review Comment
```
h3. Code Review Findings

h4. ✅ Approved Changes
* Clean separation of concerns
* Comprehensive error handling
* Well-documented functions

h4. 🔧 Suggestions
{code:java}
// Current implementation
public void processData(String input) {
    // Process directly
}

// Suggested improvement
public void processData(String input) {
    validateInput(input);  // Add validation
    // Process after validation
}
{code}

h4. ❌ Issues Found
* Missing null check on line 45
* Potential memory leak in {{DataProcessor}}
* Security vulnerability: [OWASP-A03|https://owasp.org/Top10/A03_2021-Injection/]

[~developer] Please address these before merging.
```

### Meeting Notes
```
h2. Sprint Planning Meeting - 2025-11-06

h3. Attendees
* [~pm] - Product Manager
* [~tech-lead] - Technical Lead
* [~dev1], [~dev2], [~dev3] - Development Team

h3. Agenda
# Review last sprint outcomes
# Plan current sprint scope
# Assign tasks and estimates

h3. Decisions
||Decision||Owner||Action Items||
|Implement caching layer|[~tech-lead]|[PROJ-500] - Research Redis options|
|Upgrade to Node 20|[~dev1]|[PROJ-501] - Test compatibility|
|Refactor authentication|[~dev2]|[PROJ-502] - Design proposal needed|

h3. Action Items
# [~pm] - Update roadmap with Q1 priorities
# [~tech-lead] - Schedule architecture review
# [~dev1] - Provide effort estimates by Friday

h3. Next Meeting
*Date:* 2025-11-13 10:00 AM
*Focus:* Sprint retrospective
```

## Validation Checklist

Before submitting, verify:

### Headings
- [ ] Using `h1.` through `h6.` (not Markdown `#`)
- [ ] Space after period (`h2. Title` not `h2.Title`)
- [ ] One heading per line

### Text Formatting
- [ ] `*bold*` not `**bold**`
- [ ] `_italic_` not `*italic*`
- [ ] `{{code}}` not `` `code` ``

### Lists
- [ ] `*` for bullets, not `-`
- [ ] `#` for numbers
- [ ] Proper nesting (`**`, `##` not spaces/tabs)

### Code
- [ ] `{code:language}` not ``` language ```
- [ ] Proper language identifier
- [ ] Closing `{code}` tag

### Links
- [ ] `[Label|url]` not `[Label](url)`
- [ ] `[PROJ-123]` for issues
- [ ] `[~username]` for mentions

### Tables
- [ ] `||` for headers
- [ ] `|` for cells
- [ ] Consistent column count

### Colors
- [ ] `{color:name}text{color}` format
- [ ] Proper closing `{color}` tag

### Panels
- [ ] Opening `{panel:params}`
- [ ] Closing `{panel}`
- [ ] Valid parameters

## Common Mistakes to Avoid

| ❌ Wrong | ✅ Correct | Note |
|---------|-----------|------|
| `## Heading` | `h2. Heading` | Markdown vs Jira |
| `**bold**` | `*bold*` | Double asterisk is not bold |
| `` `code` `` | `{{code}}` | Markdown backticks don't work |
| `[text](url)` | `[text\|url]` | Markdown link format |
| `- item` | `* item` | Use asterisk for bullets |
| `h2.Title` | `h2. Title` | Missing space after period |
| `{code}` | `{code:java}` | Missing language identifier |
| `|Header|` | `||Header||` | Header needs double pipes |

## Resources

- [Official Jira Wiki Markup](https://jira.atlassian.com/secure/WikiRendererHelpAction.jspa?section=all)
- [Jira Text Formatting](https://support.atlassian.com/jira-cloud-administration/docs/advanced-formatting/)
- [JQL Reference](https://support.atlassian.com/jira-service-management-cloud/docs/use-advanced-search-with-jira-query-language-jql/)

```

### templates/bug-report-template.md

```markdown
# Jira Bug Report Template

Use this template when creating bug reports in Jira with proper wiki markup syntax.

## Template

```
h2. Bug Description

[Provide a clear, concise description of the bug]

h3. Environment
* *Browser:* Chrome 120.0
* *OS:* Windows 11
* *Version:* 2.1.0
* *Environment:* Production

h3. Steps to Reproduce
# Navigate to [specific page/feature]
# Perform [specific action]
# Observe [unexpected behavior]

h3. Expected Behavior
[Describe what should happen]

h3. Actual Behavior
[Describe what actually happens]

{panel:title=Error Message|bgColor=#FFEBE9}
{code:java}
[Paste error message or stack trace here]
{code}
{panel}

h3. Additional Context
* Frequency: [Always/Sometimes/Rare]
* User Impact: [Critical/High/Medium/Low]
* Workaround Available: [Yes/No]

h3. Screenshots
[^screenshot1.png]
[^screenshot2.png]

h3. Related Issues
* Blocks [PROJ-XXX]
* Related to [PROJ-YYY]

h3. Technical Notes
{code:javascript}
// Code snippet showing the issue
function problematicCode() {
    // Details here
}
{code}

---
*Reported by:* [~username]
*Date:* YYYY-MM-DD
```

## Example - Filled Template

```
h2. Bug Description

Login button becomes unresponsive after failed authentication attempt, requiring page refresh to retry.

h3. Environment
* *Browser:* Chrome 120.0.6099.109
* *OS:* Windows 11
* *Version:* 2.3.1
* *Environment:* Production

h3. Steps to Reproduce
# Navigate to {{/login}} page
# Enter invalid credentials
# Click *Login* button
# Observe error message
# Try to enter correct credentials
# Click *Login* button again
# Button remains disabled

h3. Expected Behavior
After a failed login attempt, the login button should become active again, allowing users to retry with different credentials.

h3. Actual Behavior
The login button remains in a disabled state after the first failed attempt. Users must refresh the page to attempt login again.

{panel:title=Error in Browser Console|bgColor=#FFEBE9}
{code:javascript}
TypeError: Cannot read property 'reset' of null
    at LoginForm.handleSubmit (login.js:45)
    at onClick (login.js:23)
{code}
{panel}

h3. Additional Context
* Frequency: Always (100% reproduction rate)
* User Impact: High (blocks login functionality)
* Workaround Available: Yes (page refresh)
* Affects ~1000 daily users based on error logs

h3. Screenshots
[^login-disabled-state.png] - Login button stuck in disabled state
[^console-error.png] - Browser console showing error

h3. Related Issues
* Blocks [PROJ-234] - User authentication improvements
* Related to [PROJ-189] - Form validation refactoring

h3. Technical Notes
{code:javascript}
// Problem in LoginForm component
handleSubmit(event) {
    event.preventDefault();
    this.setState({ isSubmitting: true });

    // Error occurs here if form ref is null
    this.formRef.reset();  // BUG: formRef can be null

    // Rest of submission logic
}
{code}

Suggested fix: Add null check before calling {{reset()}} method.

---
*Reported by:* [~john.smith]
*Date:* 2025-11-06
```

## Usage with jira-communication Skill

```bash
# Create the bug report using the script
uv run scripts/workflow/jira-create.py issue PROJ \
  "Login button unresponsive after failed authentication" \
  --type Bug \
  --priority High \
  --labels frontend,authentication,ux \
  --description-file bug-description.txt

# Or with inline description (short version)
uv run scripts/workflow/jira-create.py issue PROJ \
  "Login button unresponsive after failed authentication" \
  --type Bug \
  --priority High
```

## Checklist Before Submitting

- [ ] h2. heading for main Description section
- [ ] h3. headings for subsections
- [ ] Numbered list (#) for Steps to Reproduce
- [ ] Bulleted list (*) for Environment details
- [ ] {panel} for error messages with appropriate bgColor
- [ ] {code:language} for code snippets with correct language
- [ ] [^filename] format for attachment references
- [ ] [PROJ-XXX] format for issue links
- [ ] [~username] format for user mentions
- [ ] *bold* for emphasis on key terms
- [ ] {{monospace}} for UI elements and paths

```

### templates/feature-request-template.md

```markdown
# Jira Feature Request Template

Use this template when creating feature requests in Jira with proper wiki markup syntax.

## Template

```
h2. Feature Overview

[Provide a brief summary of the feature]

h3. Business Value
* *User Impact:* [Describe who benefits and how]
* *Business Goal:* [Align with strategic objectives]
* *Priority Justification:* [Why this should be prioritized]

h3. User Stories

h4. As a [user type]
* I want to [action]
* So that [benefit]

h4. As a [another user type]
* I want to [action]
* So that [benefit]

h3. Acceptance Criteria
# [Specific, testable criterion]
# [Specific, testable criterion]
# [Specific, testable criterion]

h3. Functional Requirements

h4. Must Have
* Requirement 1
* Requirement 2

h4. Should Have
* Requirement 3
* Requirement 4

h4. Could Have
* Requirement 5
* Requirement 6

h3. Non-Functional Requirements
* *Performance:* [Response time requirements]
* *Security:* [Security considerations]
* *Scalability:* [Scale requirements]
* *Accessibility:* [WCAG compliance level]

h3. Technical Considerations
{code:language}
// Pseudocode or technical notes
{code}

h3. UI/UX Mockups
[^wireframe-01.png] - Main interface mockup
[^user-flow.png] - User journey diagram

h3. Dependencies
* Requires [PROJ-XXX] to be completed first
* Impacts [PROJ-YYY] - needs coordination

h3. Open Questions
? Question 1 - needs clarification
? Question 2 - requires decision

h3. Success Metrics
||Metric||Target||Measurement Method||
|User Adoption|80% of active users|Analytics tracking|
|Performance|< 200ms response|Performance monitoring|
|Satisfaction|4.5/5 rating|User surveys|

---
*Requested by:* [~username]
*Stakeholders:* [~pm], [~designer], [~engineer]
```

## Example - Filled Template

```
h2. Feature Overview

Implement bulk export functionality allowing users to export multiple projects to various formats (CSV, JSON, Excel) with customizable field selection.

h3. Business Value
* *User Impact:* 500+ power users currently export data manually one project at a time (30+ clicks per export)
* *Business Goal:* Reduce data export time by 90%, improving productivity and user satisfaction
* *Priority Justification:* #1 requested feature in Q4 2024 user survey (78% of respondents), competitive gap vs competitors

h3. User Stories

h4. As a Project Manager
* I want to export multiple projects at once with selected fields
* So that I can create consolidated reports without manual data entry

h4. As a Data Analyst
* I want to export historical project data in machine-readable formats
* So that I can perform advanced analytics in external tools

h4. As a Team Lead
* I want to schedule automated exports to run daily
* So that stakeholders receive up-to-date reports without manual intervention

h3. Acceptance Criteria
# User can select 1-100 projects for bulk export from project list
# Export supports CSV, JSON, and Excel formats
# User can customize which fields to include in export
# Export progress is shown with cancel option
# Completed exports are downloadable from exports history page
# Export file size limit is 50MB with pagination for larger datasets
# Exports are available for 30 days before auto-deletion

h3. Functional Requirements

h4. Must Have
* Multi-select checkbox interface for project selection
* Format selector (CSV, JSON, Excel)
* Field customization with drag-and-drop ordering
* Progress indicator during export generation
* Download link with expiration notice
* Export history page showing last 10 exports

h4. Should Have
* Search and filter for project selection
* Save field configurations as templates
* Email notification when export completes
* Preview sample data before full export

h4. Could Have
* Schedule recurring exports
* Share export links with team members
* Export directly to cloud storage (Google Drive, Dropbox)
* Advanced filtering within export data

h3. Non-Functional Requirements
* *Performance:* Export generation completes within 30 seconds for 50 projects
* *Security:* Exports encrypted at rest, only accessible to authorized users with audit trail
* *Scalability:* Support 1000 concurrent export requests
* *Accessibility:* WCAG 2.1 AA compliance for export interface
* *Browser Support:* Chrome 90+, Firefox 88+, Safari 14+, Edge 90+

h3. Technical Considerations
{code:python}
# Proposed export architecture
class BulkExporter:
    def export_projects(self, project_ids, format, fields):
        # Use async task queue for processing
        task = ExportTask.create(
            projects=project_ids,
            format=format,
            fields=fields,
            user=current_user
        )

        # Process in background
        celery.send_task('exports.process_bulk', args=[task.id])

        return task.id

    def get_export_status(self, task_id):
        # Return progress percentage and download link when complete
        return ExportTask.get(task_id).status
{code}

*Database Impact:* New {{exports}} table for tracking, ~1GB storage for 30-day retention
*API Endpoints:*
* {{POST /api/exports}} - Initiate export
* {{GET /api/exports/:id}} - Check status
* {{GET /api/exports/:id/download}} - Download file

h3. UI/UX Mockups
[^bulk-export-interface.png] - Main export dialog with project selection
[^field-customization.png] - Field selector with drag-and-drop ordering
[^export-progress.png] - Progress indicator during generation
[^export-history.png] - Export history page design

h3. Dependencies
* Requires [PROJ-456] - Background task queue infrastructure
* Impacts [PROJ-789] - Storage quota system (needs capacity planning)
* Coordinates with [PROJ-321] - API rate limiting (exports count as API calls)

h3. Open Questions
? Should exports include archived projects or only active ones?
? What permission level is required to export data? (View vs Export permission)
? Should we support incremental exports (only new/changed data)?
? How to handle very large exports exceeding 50MB limit?

h3. Success Metrics
||Metric||Target||Measurement Method||
|User Adoption|60% of power users within 3 months|Analytics event tracking|
|Time Savings|90% reduction in export time|User session timing comparison|
|User Satisfaction|4.5/5 feature rating|In-app feedback survey|
|Export Volume|5000+ exports per month|Export usage dashboard|
|Error Rate|< 1% failed exports|Error monitoring logs|

{panel:title=Launch Plan|bgColor=#DEEBFF}
h4. Phase 1 - Beta (Week 1-2)
* Release to 50 beta users
* Gather feedback and fix critical bugs

h4. Phase 2 - Limited Release (Week 3-4)
* Release to 20% of user base
* Monitor performance and error rates

h4. Phase 3 - Full Release (Week 5+)
* Release to all users
* Announce via email and in-app notifications
{panel}

---
*Requested by:* [~sarah.johnson]
*Stakeholders:* [~product.manager], [~ux.designer], [~backend.lead], [~frontend.lead]
*Estimated Effort:* 3 sprints (6 weeks)
*Target Release:* Q1 2025
```

## Usage with jira-communication Skill

```bash
# Create the feature request using the script
uv run scripts/workflow/jira-create.py issue PROJ \
  "Bulk export functionality for multiple projects" \
  --type Story \
  --priority High \
  --labels feature-request,export,productivity \
  --description-file feature-description.txt

# Or with inline description (short version)
uv run scripts/workflow/jira-create.py issue PROJ \
  "Bulk export functionality for multiple projects" \
  --type Story \
  --priority High
```

## Checklist Before Submitting

- [ ] h2. heading for Feature Overview
- [ ] h3. headings for all major sections
- [ ] h4. headings for User Stories and subsections
- [ ] Bulleted lists (*) for requirements and criteria
- [ ] Numbered lists (#) for Acceptance Criteria
- [ ] Tables (||header|| syntax) for Success Metrics
- [ ] {code:language} blocks for technical details
- [ ] {panel} for important launch/timeline information
- [ ] [^filename] for mockup/wireframe references
- [ ] [PROJ-XXX] format for dependency links
- [ ] [~username] format for stakeholder mentions
- [ ] *bold* for emphasis on metrics and targets
- [ ] {{monospace}} for technical terms and paths
- [ ] ? prefix for Open Questions

```