# JIRA Wiki Converter Utility

## Purpose

Automatically converts Markdown content to JIRA Wiki Markup format, ensuring professional appearance in JIRA while allowing users to write in familiar Markdown syntax.

## Core Conversion Rules

[[LLM: When converting content for JIRA, apply these transformations in order:

### 1. Headers

```
# Header 1        → h1. Header 1
## Header 2       → h2. Header 2
### Header 3      → h3. Header 3
#### Header 4     → h4. Header 4
##### Header 5    → h5. Header 5
###### Header 6   → h6. Header 6
```

### 2. Text Formatting

```
**bold**          → *bold*
*italic*          → _italic_
***bold italic*** → *_bold italic_*
~~strikethrough~~ → -strikethrough-
`inline code`     → {{inline code}}
```

### 3. Lists

```
* Item            → * Item
- Item            → * Item
  * Nested        →   * Nested
  - Nested        →   * Nested
1. Number         → # Number
2. Number         → # Number
   1. Nested      →   ## Nested
   2. Nested      →   ## Nested
```

### 4. Code Blocks

````
```language       → {code:language}
code content      → code content
```               → {code}

```               → {code}
code content      → code content
```               → {code}
````

### 5. Links

```
[text](url)       → [text|url]
[PROJ-123]        → [PROJ-123] (no change - JIRA issue links)
@username         → [~username]
```

### 6. Special Elements

```
> Quote           → {quote}Quote{quote}
---               → ----
___               → ----
***               → ----
```

### 7. Tables

```
| Header 1 | Header 2 |    → ||Header 1||Header 2||
|----------|----------|    → (remove separator line)
| Cell 1   | Cell 2   |    → |Cell 1|Cell 2|
```

### 8. Task Lists

```
- [ ] Task        → * [ ] Task
- [x] Done        → * [x] Done
```

]]

## Conversion Function

[[LLM: When converting content:

1. **Process in order**: Apply rules from top to bottom to avoid conflicts
2. **Preserve structure**: Maintain indentation and spacing
3. **Handle edge cases**:
   - Code blocks take precedence (don't convert content inside)
   - Preserve JIRA issue references (PROJECT-123)
   - Keep URLs intact in link conversions
   - Maintain list hierarchy with proper indentation

Example conversion:

````
INPUT (Markdown):
## Problem Statement
The **authentication system** has a `critical` bug where users can't reset passwords.

### Steps to Reproduce
1. Click "Forgot Password"
2. Enter email
3. Submit form

### Code Example
```javascript
function resetPassword(email) {
  // This fails
  return api.reset(email);
}
````

### Related Issues

- [AUTH-123]
- See [documentation](https://docs.example.com)

OUTPUT (JIRA Wiki):
h2. Problem Statement
The _authentication system_ has a {{critical}} bug where users can't reset passwords.

h3. Steps to Reproduce

# Click "Forgot Password"

# Enter email

# Submit form

h3. Code Example
{code:javascript}
function resetPassword(email) {
// This fails
return api.reset(email);
}
{code}

h3. Related Issues

- [AUTH-123]
- See [documentation|https://docs.example.com]

```
]]

## Preview Mode

[[LLM: When sync includes preview option:

1. Show side-by-side comparison:
```

ORIGINAL (Markdown) → CONVERTED (Wiki Markup)
─────────────────────────────────────────────────────

## Epic Overview → h2. Epic Overview

Implement **user auth** → Implement _user auth_

```

2. Highlight conversion points with color coding
3. Allow user to confirm before proceeding
]]

## Bulk Conversion Support

[[LLM: For multiple stories/issues:

1. Convert all descriptions and comments
2. Show summary: "Converting 12 issues from Markdown to Wiki Markup..."
3. Track conversion statistics:
- Headers converted: 45
- Code blocks: 8
- Links reformatted: 23
4. Offer to preview first 3 before bulk apply
]]

## Error Handling

[[LLM: Handle these edge cases:

1. **Nested formatting**: `**bold with `code` inside**`
- Convert outer formatting first
- Preserve inner code blocks

2. **Mixed lists**: Markdown allows *, -, + for bullets
- Normalize all to * in wiki markup

3. **Fenced code without language**:
- Use {code} without language parameter

4. **Multiple line quotes**:
```

> Line 1
> Line 2
> Line 3

```
Becomes:
```

{quote}
Line 1
Line 2
Line 3
{quote}

```
]]

## Integration Points

### sync.md Integration
[[LLM: In sync operations:
1. Before creating/updating JIRA issues
2. Apply conversion to description field
3. Apply to all comments being synced
4. Log conversion activity
]]

### report.md Integration
[[LLM: When generating reports:
1. Use wiki markup for JIRA display
2. Keep markdown for file storage
3. Allow format selection via parameter
]]

## Quality Assurance

[[LLM: After conversion:
1. Verify no markdown syntax remains
2. Check all JIRA references intact
3. Ensure code blocks properly closed
4. Validate table structure
5. Test links are clickable
]]

## Usage Examples

### Simple Conversion
```

User: "sync story with proper formatting"
System: "Converting description to JIRA Wiki Markup...

- 3 headers converted
- 2 code blocks formatted
- 5 links updated
  ✓ Ready to sync with professional formatting"

```

### Bulk Epic Sync
```

User: "sync epic to jira"
System: "Preparing Epic sync...
📝 Converting 11 stories from Markdown to Wiki Markup
Preview first story? (y/n)"

```

### Format Validation
```

User: "check jira formatting"
System: "Analyzing current format...
⚠️ Found 3 Markdown elements that need conversion:

- Line 23: ## Header (should be h2.)
- Line 45: **bold** (should be _bold_)
- Line 67: `code` (should be {code}...{code})
  Convert now? (y/n)"

```

## Performance Notes

[[LLM: For large conversions:
1. Process in chunks of 10 issues
2. Show progress indicator
3. Cache converted content
4. Allow incremental conversion
]]

## Testing Checklist

[[LLM: Verify these conversions work correctly:
- [ ] Headers (all 6 levels)
- [ ] Bold, italic, strikethrough
- [ ] Inline code and code blocks
- [ ] Ordered and unordered lists
- [ ] Nested lists (3 levels deep)
- [ ] Links (external and JIRA)
- [ ] Tables with headers
- [ ] Multi-line quotes
- [ ] Task lists with checkboxes
- [ ] Horizontal rules
- [ ] Mixed formatting combinations
]]
```