@cloudkinetix/bmad-enhanced/expansion-packs/ck-jira-integration/utils/jira-formatting.md

Cloud-Kinetix enhanced fork of BMAD-METHOD - Breakthrough Method of Agile AI-driven Development with robust versioning and unified validation.

# JIRA Wiki Markup Formatting Guide

This guide provides comprehensive formatting options for JIRA using Wiki Markup syntax. Use these patterns to create well-formatted, professional JIRA content.

## Text Formatting

### Basic Text Styles

```
*bold text*
_italic text_
-strikethrough-
+underlined+
^superscript^
~subscript~
{{monospace}}
```

### Headings

```
h1. Heading 1
h2. Heading 2
h3. Heading 3
h4. Heading 4
h5. Heading 5
h6. Heading 6
```

## Lists

### Bulleted Lists

```
* Item 1
* Item 2
** Sub-item 2.1
** Sub-item 2.2
* Item 3
```

### Numbered Lists

```
# First item
# Second item
## Sub-item 2.1
## Sub-item 2.2
# Third item
```

## Code and Technical Content

### Inline Code

```
Use {{code}} for inline code snippets
```

### Code Blocks

```
{code:language=javascript}
function example() {
    return "Hello, World!";
}
{code}
```

### No Format (Preformatted)

```
{noformat}
This text will appear exactly as typed,
    preserving spacing and special characters.
{noformat}
```

## Links and References

### External Links

```
[Link text|http://example.com]
[http://example.com]
```

### JIRA Links

```
[PROJECT-123]           // Link to issue
[Project Name|PROJECT]  // Link to project
[user@domain.com]       // Link to user
```

## Tables

### Basic Table

```
||Heading 1||Heading 2||Heading 3||
|Cell 1|Cell 2|Cell 3|
|Cell 4|Cell 5|Cell 6|
```

### Table with Alignment

```
||Left||Center||Right||
|{color:red}Red text{color}|{color:blue}Blue text{color}|{color:green}Green text{color}|
```

## Visual Elements

### Colors

```
{color:red}Red text{color}
{color:blue}Blue text{color}
{color:green}Green text{color}
{color:#ff0000}Custom hex color{color}
```

### Panels

```
{panel:title=Important Note}
This is a highlighted panel with a title.
{panel}

{panel:bgColor=#ffffcc}
This panel has a custom background color.
{panel}
```

### Quote Blocks

```
{quote}
This is a quoted block of text.
It can span multiple lines.
{quote}
```

## Advanced Formatting

### Attachments and Images

```
!image.png!                    // Display image
!image.png|thumbnail!          // Thumbnail version
!image.png|width=300!          // Custom width
[^attachment.pdf]              // Link to attachment
```

### Macros

#### Info/Warning/Error Boxes

```
{info:title=Information}
This is an info box.
{info}

{warning:title=Warning}
This is a warning box.
{warning}

{error:title=Error}
This is an error box.
{error}
```

#### Expand/Collapse

```
{expand:title=Click to expand}
Hidden content goes here.
This can be multiple lines.
{expand}
```

## Best Practices for JIRA Issues

### Issue Description Structure

```
h2. Problem Statement
Brief description of the issue...

h2. Steps to Reproduce
# Step 1
# Step 2
# Step 3

h2. Expected Behavior
What should happen...

h2. Actual Behavior
What actually happens...

h2. Acceptance Criteria
* [ ] Criterion 1
* [ ] Criterion 2
* [ ] Criterion 3

h2. Technical Notes
{code:language=javascript}
// Code examples or technical details
{code}

h2. Related Issues
[PROJECT-456] - Related issue
[PROJECT-789] - Dependent issue
```

### Comment Formatting

```
h3. Update - [~username] - 2025-06-23
*Status:* In Progress
*Progress:* Completed initial implementation
*Next Steps:*
* Code review
* Testing
* Documentation

{panel:bgColor=#e3fcec}
*Note:* This approach resolves the performance issue mentioned in [PROJECT-123].
{panel}
```

## JIRA-Specific Shortcuts

### Issue References

```
PROJECT-123              // Link to specific issue
PROJECT-*                // All issues in project
fixVersion = "1.2.0"     // Issues with specific fix version
```

### User References

```
[~username]              // Link to user
[~accountid:123456789]   // Link by account ID
```

### Time and Dates

```
Created: 2025-06-23
Due Date: 2025-07-01
Time Spent: 2h 30m
```

## Integration with BMAD Methodology

### Story Templates

```
h1. User Story: [STORY-123]

h2. As a... I want... So that...
*As a* registered user
*I want* to reset my password
*So that* I can regain access to my account

h2. Acceptance Criteria
* [ ] User can request password reset via email
* [ ] Reset link expires after 24 hours
* [ ] User can set new password meeting requirements
* [ ] Success confirmation is displayed

h2. Technical Implementation
{panel:title=Architecture Notes}
- Update UserService.resetPassword() method
- Add password validation middleware
- Implement email notification service
{panel}
```

### Epic Formatting

```
h1. Epic: [EPIC-456] User Authentication System

h2. Epic Goal
Implement comprehensive user authentication and authorization system.

h2. Key Features
* User registration and login
* Password reset functionality
* Role-based access control
* Session management

h2. Success Metrics
* 99.9% authentication uptime
* Sub-second login response time
* Zero security vulnerabilities

h2. Stories
* [STORY-101] User Registration
* [STORY-102] User Login
* [STORY-103] Password Reset
* [STORY-104] Role Management
```

---

_Last Updated: 2025-06-23 | Version: 1.1.0_