zhongwei/gh-openshift-hyperfleet-hyperfleet-claude-plugins-hyperfleet-jira
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:46:30 +08:00
commit 569ae39e1b
11 changed files with 1433 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

127
skills/jira-hygiene/SKILL.md Normal file
View File

@@ -0,0 +1,127 @@
---
name: JIRA Ticket Hygiene Checker
description: Validates JIRA tickets have required fields and sufficient information for development. Activates when users ask about ticket quality, readiness, or completeness, or when reviewing tickets before sprint planning.
---
# JIRA Ticket Hygiene Skill
## When to Use This Skill
Activate this skill when the user:
- Asks if a ticket is "ready", "complete", or "well-defined"
- Asks about ticket quality or completeness
- Wants to review a ticket before sprint planning
- Asks "does this ticket have enough information?"
- Wants to validate tickets meet team standards
- Asks about missing fields or requirements
## Hygiene Checklist
### Required Fields (Must Have)
- [ ] **Title**: Clear, actionable, under 100 characters
- [ ] **Description**: Detailed context (recommend > 100 characters)
- [ ] **Acceptance Criteria**: At least 2 clear, testable criteria
- [ ] **Story Points**: Set for Stories, Tasks, and Bugs (use scale: 0, 1, 3, 5, 8, 13)
- [ ] **Assignee**: Someone owns the ticket
- [ ] **Component**: Assigned to track by area
- [ ] **Activity Type**: Must be set for capacity planning (see Activity Types below)
### Recommended Fields
- [ ] **Labels**: At least 1 relevant label
- [ ] **Epic Link**: Connected to parent epic (for Stories)
- [ ] **Fix Version**: Target release identified
- [ ] **Priority**: Explicitly set (not just default)
### Quality Checks
- [ ] No ambiguous language ("maybe", "probably", "TBD", "possibly")
- [ ] Technical approach outlined or referenced
- [ ] Dependencies identified and linked
- [ ] Not a duplicate of existing ticket
- [ ] Scope is achievable in one sprint
## How to Check a Ticket
Use jira-cli to fetch ticket details:
```bash
jira issue view TICKET-KEY --plain 2>/dev/null
```
For JSON output with all fields:
```bash
jira issue view TICKET-KEY --json 2>/dev/null
```
## Output Format
When analyzing a ticket, provide:
### Ticket: TICKET-KEY
**Summary:** [Ticket title]
#### Hygiene Assessment
| Check | Status | Notes |
|-------|--------|-------|
| Title | PASS/FAIL | [Issue if any] |
| Description | PASS/FAIL | [Length: X chars] |
| Acceptance Criteria | PASS/FAIL | [Count: X criteria] |
| Story Points | PASS/FAIL | [Value or "Missing"] |
| Assignee | PASS/FAIL | [Name or "Unassigned"] |
| Component | PASS/FAIL | [Component or "None"] |
| Activity Type | PASS/FAIL | [Type or "Uncategorized"] |
#### Overall Score: X/7 Required Checks Passed
#### Verdict
- **READY FOR SPRINT** - All required fields present, good quality
- **NEEDS MINOR FIXES** - 1-2 issues to address
- **NOT READY** - Multiple critical issues
#### Recommended Actions
1. [Specific action to fix issue 1]
2. [Specific action to fix issue 2]
## Activity Types (Sankey Capacity Allocation)
Activity Type is **required** for sprint/kanban capacity planning. Tickets without an Activity Type appear as "Uncategorized" and cannot be properly allocated.
### Reactive Work (Non-Negotiable First)
| Activity Type | Description | Examples |
|---------------|-------------|----------|
| **Associate Wellness & Development** | Onboarding, team growth, training, associate experience | Training sessions, mentorship |
| **Incidents & Support** | Escalations, production issues | Customer escalations, outages |
| **Security & Compliance** | Vulnerabilities and weaknesses, CVEs | Security patches, compliance fixes |
### Core Principles (Quality Focus)
| Activity Type | Description | Examples |
|---------------|-------------|----------|
| **Quality / Stability / Reliability** | Bugs, SLOs, chores, tech debt, PMR action items, toil reduction | Bug fixes, performance improvements |
### Proactive Work (Balance Remaining Capacity)
| Activity Type | Description | Examples |
|---------------|-------------|----------|
| **Future Sustainability** | Productivity improvements, team improvements, upstream, proactive architecture, enablement | Tooling, automation, refactoring |
| **Product / Portfolio Work** | Strategic portfolio (HATSTRAT), strategic product, product outcome, BU features | New features, product enhancements |
### Priority Order
1. **Non-Negotiable**: Achieve SLAs for Escalations & CVEs
2. **Core Principles**: Reduce bug backlog, ensure quality/stability/reliability
3. **Then Balance**: Set up for long-term success by balancing remaining capacity between Future Sustainability and Product Work
## Red Flags to Highlight
- Descriptions under 50 characters
- "TBD" or placeholder text in any field
- Story points of 13+ (must be broken down)
- No acceptance criteria at all
- Vague titles like "Fix bug" or "Update feature"
- Tickets open > 30 days without progress
- **Missing Activity Type** (appears as Uncategorized in capacity planning)
## Integration with Commands
This skill complements the `/hygiene-check` command:
- Command: Bulk audit of sprint tickets
- Skill: Deep-dive on individual ticket quality

152
skills/jira-story-pointer/SKILL.md Normal file
View File

@@ -0,0 +1,152 @@
---
name: JIRA Story Point Estimator
description: Estimates story points for JIRA tickets by analyzing complexity, scope, and comparing to historical team data. Activates when users ask to estimate, point, or size a ticket, or ask "how many points should this be?"
---
# JIRA Story Point Estimator Skill
## When to Use This Skill
Activate this skill when the user:
- Asks "estimate this ticket" or "how many story points?"
- Asks to "size" or "point" a ticket
- Asks "what should this be pointed at?"
- Wants help with sprint planning estimation
- Asks "is X points right for this ticket?"
- Reviews a ticket that needs story points
## Story Point Scale Reference
HyperFleet uses a modified Fibonacci sequence for story points:
| Points | Meaning | Typical Scope | Notes |
|--------|---------|---------------|-------|
| **0** | Tracking Only | Quick/easy task with stakeholder value | Rarely used. For tasks worth tracking but with negligible effort compared to a 1-pointer |
| **1** | Trivial | One-line change, extremely simple task | The smallest issue possible - everything scales from here. No risk, very low effort, very low complexity |
| **3** | Straightforward | Time consuming but fairly straightforward work | Doesn't have to be complex, but usually time consuming. Minor risks possible |
| **5** | Medium | Requires investigation, design, collaboration | Probably needs discussion with others. Can be quite time consuming or complex. Risks involved |
| **8** | Large | Big task requiring investigation and design | Requires collaboration with others. Solution can be quite challenging. Risks are expected. **Design doc required** |
| **13** | Too Large | Should be split into smaller stories | Ideally, this shouldn't be used. If you see an issue this big, it must be broken down |
## Estimation Methodology
### Step 1: Fetch Ticket Details
```bash
jira issue view TICKET-KEY --plain 2>/dev/null
```
### Step 2: Analyze Complexity Factors
**Scope Indicators (examine description and acceptance criteria):**
- Number of acceptance criteria
- Number of components/files likely affected
- Integration points mentioned
- Testing requirements
**Complexity Indicators:**
- New feature vs. modification vs. bug fix
- Requires new patterns or unfamiliar technology
- External dependencies (APIs, services)
- Database/schema changes
- Security implications
- Documentation requirements
**Risk Indicators:**
- Ambiguity in requirements
- Dependencies on other tickets
- Time-sensitive (blocks other work)
- Requires coordination with other teams
### Step 3: Find Similar Historical Tickets
Search for comparable completed tickets:
```bash
jira issue list -q"project = HYPERFLEET AND status = Done AND type = Story" --plain 2>/dev/null | head -20
```
```bash
jira issue list -q"project = HYPERFLEET AND status = Done AND 'Story Points' is not EMPTY AND type = Story" --plain 2>/dev/null | head -20
```
### Step 4: Provide Estimation
## Output Format
### Estimation for: TICKET-KEY
**Summary:** [Ticket title]
**Type:** [Story/Task/Bug]
---
#### Complexity Analysis
| Factor | Assessment | Impact |
|--------|------------|--------|
| Scope | [Small/Medium/Large] | [Description] |
| Technical Complexity | [Low/Medium/High] | [Why] |
| Dependencies | [None/Few/Many] | [List if any] |
| Testing Effort | [Minimal/Moderate/Extensive] | [Why] |
| Risk/Uncertainty | [Low/Medium/High] | [Why] |
---
#### Recommendation
**Suggested Story Points: X**
**Confidence Level:** [High/Medium/Low]
**Reasoning:**
- [Primary factor 1]
- [Primary factor 2]
- [Comparison to similar work]
---
#### Similar Completed Tickets (for reference)
| Ticket | Summary | Points | Similarity |
|--------|---------|--------|------------|
| TICKET-A | [Summary] | 5 | High - similar scope |
| TICKET-B | [Summary] | 3 | Medium - simpler version |
---
#### Considerations
- **If higher:** [What would make this larger]
- **If lower:** [What would make this smaller]
- **Break-down suggestion:** [If 13+ points, suggest how to split]
## Setting Story Points
Once agreed, set story points using:
```bash
jira issue edit TICKET-KEY --custom story-points=X --no-input
```
Or for Story Point Estimate field (Next-gen projects):
```bash
jira issue edit TICKET-KEY --custom story-point-estimate=X --no-input
```
## Team Calibration Notes
When estimating, consider:
- Team's typical velocity (points completed per sprint)
- Recent similar work and how long it actually took
- Team familiarity with the codebase area
- Current sprint load and focus
## Anti-Patterns to Flag
- **Anchoring**: Don't let existing (wrong) estimates bias you
- **Scope Creep**: Point what's written, not what might be added
- **Hero Estimates**: Assume average team member, not expert
- **Planning Fallacy**: Add buffer for unknowns
- **Story Point Inflation**: Keep consistent with team baseline

696
skills/jira-ticket-creator/SKILL.md Normal file
View File

@@ -0,0 +1,696 @@
---
name: JIRA Ticket Creator
description: Creates well-structured JIRA tickets in the HYPERFLEET project with required fields including What/Why/Acceptance Criteria, story points, and activity type. Activates when users ask to create a ticket, story, task, or epic.
---
# JIRA Ticket Creator Skill
## ⚠️ CRITICAL: JIRA Uses Wiki Markup, NOT Markdown!
**YOU MUST USE JIRA WIKI MARKUP SYNTAX - NEVER USE MARKDOWN!**
| Element | ❌ WRONG | ✅ CORRECT |
|---------|----------|------------|
| **Header** | `### What` | `h3. What` (space required!) |
| **Bullets** | `- Item` or `• Item` | `* Item` |
| **Nested** | ` - Nested` | `** Nested` |
| **Inline Code** | `` `code` `` | `{{code}}` |
| **Bold** | `**text**` | `*text*` |
| **Path Params** | `/api/{id}` | `/api/:id` or `/api/ID` |
| **Placeholders** | `{customer-id}` | `CUSTOMER_ID` or `:customer_id` |
**If you use Markdown syntax, the ticket will render incorrectly in JIRA!**
See "CRITICAL: JIRA Wiki Markup Formatting" section below for complete reference.
---
## When to Use This Skill
Activate this skill when the user:
- Asks to "create a ticket" or "create a story/task/epic"
- Says "I need a JIRA ticket for..."
- Asks "can you create a ticket for [feature/bug/task]?"
- Wants to document work as a JIRA issue
- Asks to "file a ticket" or "add a story"
- Provides work that needs to be tracked
## Required Ticket Structure
Every ticket created MUST include:
### 1. **What** (Required)
Clear, concise description of what needs to be done. Should be 2-4 sentences explaining the work.
### 2. **Why** (Required)
Business justification and context. Explain:
- Why this work matters
- Who benefits (users, team, system)
- What problem it solves or value it delivers
### 3. **Acceptance Criteria** (Required)
Minimum 2-3 clear, testable criteria that define "done":
- Must be objective and verifiable
- Should cover functional requirements and edge cases
- Use bullet format with specific details
### 4. **Story Points** (Required for Stories/Tasks/Bugs)
All Stories, Tasks, and Bugs must have story points:
- Use scale: 0, 1, 3, 5, 8, 13
- Follow the team's estimation guide (see Story Points section)
### 5. **Activity Type** (Required for Stories/Tasks/Bugs)
Must set activity type for capacity planning. Valid types:
- `Associate Wellness & Development`
- `Incidents & Support`
- `Security & Compliance`
- `Quality / Stability / Reliability`
- `Future Sustainability`
- `Product / Portfolio Work`
### 6. Optional Context
Additional sections can be added as needed:
- **Technical Notes**: High-level implementation plan
- **Dependencies**: Linked tickets or external dependencies
- **Out of Scope**: Explicitly state what's NOT included
## CRITICAL: JIRA Wiki Markup Formatting
**JIRA uses wiki markup, NOT Markdown!**
### Headers
```
h3. What ✅ Correct (space after period!)
h3. Why ✅ Correct
**What** ❌ Wrong (Markdown syntax)
### What ❌ Wrong (Markdown syntax)
```
### Bullets
```
* Item 1 ✅ Correct
** Nested item ✅ Correct (two asterisks)
- Item 1 ❌ Wrong (Markdown syntax)
• Item 1 ❌ Wrong (Unicode bullet)
- Nested ❌ Wrong (indentation + dash)
```
**Real Example - HYPERFLEET-255 (WRONG):**
```
### Summary ❌ Markdown header - won't render!
• POST /api/... ❌ Unicode bullet - won't render!
```
**Should Have Been:**
```
h3. Summary ✅ JIRA wiki header
* POST /api/... ✅ JIRA wiki bullet
```
### Inline Code
```
{{package/path}} ✅ Correct
{{variable_name}} ✅ Correct
`package/path` ❌ Wrong (Markdown syntax)
```
### Bold/Italic
```
*bold text* ✅ Correct
_italic text_ ✅ Correct
**bold** ❌ Wrong (Markdown syntax)
```
### Code Blocks
**DO NOT use code blocks in CLI-created tickets!** They don't render properly.
```
{code:go} ❌ Don't use via CLI (renders as empty gray box)
package main
{/code}
```
**Instead:**
- Use inline code: `{{package_name}}`
- Add code examples manually via web UI after creation
- Or use descriptive text with inline code references
### API Endpoints
```
*POST* /api/v1/clusters/:id ✅ Correct (bold HTTP method, colon notation)
*GET* /api/v1/clusters/CLUSTER_ID ✅ Correct (placeholder text)
*POST* /api/v1/clusters/{id} ❌ Wrong - curly braces break rendering!
{{POST /api/v1/clusters/{id}}} ❌ Wrong (nested braces break rendering)
```
### Curly Braces Warning
**NEVER use curly braces `{}` in ticket descriptions - they break JIRA rendering!**
```
wif-{customer-id}-key ❌ Wrong - curly braces break rendering!
{{wif-{customer-id}-key}} ❌ Wrong - nested braces also break!
wif-CUSTOMER_ID-key ✅ Correct - use CAPS or other notation
/api/v1/clusters/{id} ❌ Wrong - path parameter braces break!
/api/v1/clusters/:id ✅ Correct - use colon notation
/api/v1/clusters/CLUSTER_ID ✅ Correct - use placeholder text
```
**Alternatives to curly braces:**
* Use SCREAMING_CASE: `wif-CUSTOMER_ID-key`
* Use colon notation: `/api/v1/clusters/:id`
* Use angle brackets: `wif-<customer-id>-key`
* Use square brackets: `wif-[customer-id]-key`
### YAML in Code Blocks
**NEVER include YAML comments in code blocks!** The `#` character is interpreted as `h1.` header.
**Wrong:**
```
{code:yaml}
# This is a comment
field: value
{/code}
```
**Correct Option 1 - Descriptive text:**
```
Configuration fields:
* {{field: value}} - Description of field
```
**Correct Option 2 - Code block without comments:**
```
{code:yaml}
field: value
{/code}
Explanation outside code block...
```
## Ticket Creation Workflow
### Step 1: Gather Requirements
Ask the user clarifying questions if needed:
- What type of ticket? (Epic, Story, Task, Bug)
- What needs to be done? (What)
- Why is this important? (Why)
- How will we know it's done? (Acceptance Criteria)
- How complex/large is this work? (for story points)
- What category of work is this? (for activity type)
### Step 2: Create Description File
**⚠️ CRITICAL: Always create a temporary file with JIRA wiki markup (NOT Markdown!):**
**DO NOT USE:**
- `### Headers` (Markdown)
- `- bullets` or `• bullets` (Markdown/Unicode)
- `` `inline code` `` (Markdown)
- `**bold**` (Markdown)
**USE ONLY:**
- `h3. Headers` (JIRA wiki - space required!)
- `* bullets` (JIRA wiki)
- `{{inline code}}` (JIRA wiki)
- `*bold*` (JIRA wiki)
**Template for Stories/Tasks (JIRA Wiki Markup):**
```
h3. What
Brief description paragraph.
Detailed explanation paragraph (optional).
h3. Why
* Reason 1
* Reason 2
* Reason 3
h3. Acceptance Criteria:
* {{Component}} created/implemented/configured
* Feature X works correctly:
** Detail 1
** Detail 2
* Tests achieve >80% coverage
* Documentation updated
h3. Technical Notes:
* Use {{package-name}} for implementation
* Configuration in {{/path/to/config.yaml}}
* Important consideration
* Reference {{AnotherComponent}}
h3. Out of Scope:
* Item not included
* Another exclusion
```
**Template for Epics:**
```
h1. Epic Title
h3. Overview
Brief overview paragraph.
h3. What
* Key deliverable 1
* Key deliverable 2
** Sub-item
* Key deliverable 3
h3. Why
Explanation of business value and impact.
h3. Scope
*In Scope*:
* Item 1
* Item 2
*Out of Scope*:
* Item 3
* Item 4
h3. Success Criteria
* Criterion 1
* Criterion 2
* Criterion 3
```
### Step 3: Determine Story Points
Use the estimation scale:
| Points | Meaning | Typical Scope |
|--------|---------|---------------|
| **0** | Tracking Only | Quick/easy task, negligible effort |
| **1** | Trivial | One-line change, extremely simple |
| **3** | Straightforward | Time consuming but straightforward |
| **5** | Medium | Requires investigation, design, collaboration |
| **8** | Large | Big task, investigation & design required, needs design doc |
| **13** | Too Large | MUST be broken down into smaller stories |
Consider:
- Scope (lines of code, files affected, integration points)
- Complexity (new patterns, unfamiliar tech)
- Risk (ambiguity, dependencies, unknowns)
- Testing effort
### Step 4: Assign Activity Type
Choose based on work category:
**Reactive Work (Non-Negotiable First):**
- `Associate Wellness & Development` - Training, onboarding, team growth
- `Incidents & Support` - Customer escalations, production issues
- `Security & Compliance` - CVEs, security patches, compliance
**Core Principles (Quality Focus):**
- `Quality / Stability / Reliability` - Bugs, tech debt, toil reduction, SLOs
**Proactive Work (Balance Capacity):**
- `Future Sustainability` - Tooling, automation, architecture improvements
- `Product / Portfolio Work` - New features, strategic product work
### Step 5: Create the Ticket via jira-cli
**IMPORTANT: Use the patterns that actually work!**
#### Creating a Story
```bash
# 1. Save description to temporary file
cat > /tmp/story-description.txt << 'EOF'
h3. What
Description of what needs to be done.
h3. Why
* Reason 1
* Reason 2
h3. Acceptance Criteria:
* Criterion 1
* Criterion 2
* Criterion 3
h3. Technical Notes:
* Use {{package-name}}
* Configuration in {{/path/to/config}}
EOF
# 2. Create story (NOTE: Do NOT use --custom for story points via CLI - set via web UI)
jira issue create --project HYPERFLEET --type Story \
--summary "Story Title (< 100 chars)" \
--no-input \
-b "$(cat /tmp/story-description.txt)"
# 3. Note the ticket number from output (e.g., HYPERFLEET-123)
# 4. Set story points via web UI (jira-cli custom fields can be unreliable)
```
#### Creating a Task
```bash
# Same as Story, just change --type to Task
cat > /tmp/task-description.txt << 'EOF'
h3. What
Task description.
h3. Why
Justification.
h3. Acceptance Criteria:
* Criterion 1
* Criterion 2
EOF
jira issue create --project HYPERFLEET --type Task \
--summary "Task Title" \
--no-input \
-b "$(cat /tmp/task-description.txt)"
```
#### Creating an Epic
**CRITICAL: Epics require the Epic Name field!**
```bash
# 1. Create description file
cat > /tmp/epic-description.txt << 'EOF'
h1. Epic Full Title
h3. Overview
Overview paragraph.
h3. What
* Deliverable 1
* Deliverable 2
h3. Why
Explanation.
h3. Success Criteria
* Criterion 1
* Criterion 2
EOF
# 2. Create epic with Epic Name (required field!)
jira issue create --project HYPERFLEET --type Epic \
--summary "Epic: Full Title Here" \
--custom epic-name="Short Name" \
--template /tmp/epic-description.txt \
--no-input
# Note: Use --custom epic-name="Name" (not epicName or customfield_12311141)
```
#### Creating a Bug
```bash
cat > /tmp/bug-description.txt << 'EOF'
h3. What
Description of the bug and its impact.
h3. Why
Why this needs to be fixed urgently.
h3. Acceptance Criteria:
* Bug is reproducible
* Root cause identified
* Fix is verified
* Regression test added
EOF
jira issue create --project HYPERFLEET --type Bug \
--summary "Bug: Brief Description" \
--no-input \
-b "$(cat /tmp/bug-description.txt)"
```
### Step 6: Post-Creation Manual Steps
After creating a ticket via CLI, these must be done manually via web UI:
1. **Set Story Points**
- Edit ticket → Story Points field
- Custom fields via CLI are unreliable
2. **Set Activity Type**
- Edit ticket → Activity Type field
- Select from dropdown
3. **Link to Epic** (for Stories)
- Edit ticket → Link → "is child of" → Epic ticket
4. **Add Labels**
- Edit ticket → Labels field
- Add relevant tags
5. **Add Code Examples** (if needed)
- Edit description via web UI
- Add `{code:language}...{/code}` blocks
- Code blocks don't render properly via CLI
### Step 7: Verify and Return Details
```bash
# View created ticket
jira issue view HYPERFLEET-XXX --plain
# Check in web UI
# URL: https://issues.redhat.com/browse/HYPERFLEET-XXX
```
Return to user:
- Ticket key (e.g., HYPERFLEET-123)
- Link: https://issues.redhat.com/browse/HYPERFLEET-123
- Summary of what was created
- **List of manual steps needed** (story points, activity type, etc.)
## Output Format
When creating a ticket, provide this output to the user:
```
### Ticket Created: HYPERFLEET-XXX
**Type:** [Story/Task/Epic/Bug]
**Summary:** [Title]
**Link:** https://issues.redhat.com/browse/HYPERFLEET-XXX
---
#### Description Structure (✅ Created via CLI)
**What:**
[What description]
**Why:**
[Why description]
**Acceptance Criteria:**
* Criterion 1
* Criterion 2
* Criterion 3
---
#### Manual Steps Required (⚠️ Must be done via Web UI)
Please complete these steps in the JIRA web interface:
1. **Set Story Points**: [Recommended: X points based on complexity]
2. **Set Activity Type**: [Recommended: {activity type}]
3. **Link to Epic**: [If applicable: Link to HYPERFLEET-XXX]
4. **Add Labels**: [Suggested: label1, label2]
5. **Add Code Examples**: [If needed: Add via web UI description editor]
**Why manual?** Custom fields and code blocks don't render reliably via jira-cli.
```
## Common Pitfalls to Avoid
### ❌ DON'T:
**FORMATTING (Most Common Mistakes!):**
1. ❌ Use Markdown headers: `### What`, `## Summary`
2. ❌ Use Markdown/Unicode bullets: `- Item`, `• Item`
3. ❌ Use Markdown inline code: `` `code` ``
4. ❌ Use Markdown bold: `**text**`
5. ❌ Forget space after JIRA headers: `h3.What` (needs `h3. What`)
**TICKET EXAMPLES OF WRONG FORMATTING:**
- HYPERFLEET-255: Used `### Summary` and `• bullets` - headers didn't render!
**CURLY BRACES (Break JIRA Rendering!):**
6. ❌ Use curly braces `{}` anywhere - e.g., `{customer-id}`, `/api/{id}` - breaks rendering!
7. ❌ Use `{{}}` around content with braces - doubly broken!
**OTHER MISTAKES:**
8. ❌ Include code blocks with `{code}...{/code}` via CLI (renders as empty boxes)
9. ❌ Put YAML comments (`#`) in code blocks (breaks rendering)
10. ❌ Use `--custom` fields via CLI (unreliable for story points, activity type)
11. ❌ Use `--body-file` flag (doesn't exist!)
12. ❌ Mix Markdown and JIRA wiki markup in same ticket
**TICKET EXAMPLES OF CURLY BRACE ISSUES:**
- HYPERFLEET-258: Used `{customer-id}` - broke rendering! Fixed with CUSTOMER_ID
### ✅ DO:
1. Use JIRA wiki markup consistently
2. Save descriptions to temporary files: `-b "$(cat /tmp/file.txt)"`
3. Test with ONE ticket before creating multiple
4. Use `--no-input` for non-interactive creation
5. Set custom fields via web UI after creation
6. Add code examples via web UI
7. Use bold for HTTP methods: `*POST* /api/path`
8. Use inline code for paths: `{{/path/to/file}}`
## Troubleshooting
### Issue: Epic Name Required Error
```
Error: customfield_12311141: Epic Name is required.
```
**Solution:**
```bash
--custom epic-name="Short Name" ✅ Correct
--custom epicName="Name" ❌ Wrong
--custom customfield_12311141 ❌ Wrong
```
### Issue: Code Blocks Show as Empty Gray Boxes
**Solution:** Don't include code blocks via CLI. Add them manually via web UI after creation.
### Issue: Headers Not Rendering
**Solution:** Ensure space after period: `h3. What` (not `h3.What`)
### Issue: Bullets Not Working
**Solution:** Use `*` not `-`, and `**` for nested (not indentation)
### Issue: Custom Fields Won't Set
**Solution:** Set story points and activity type via web UI. The jira-cli custom field handling is unreliable.
## Best Practices
### 1. Always Test First
```bash
# Create ONE test ticket
jira issue create --project HYPERFLEET --type Story \
--summary "TEST - Delete Me" \
-b "$(cat /tmp/test-description.txt)" \
--no-input
# Verify in CLI and web UI
jira issue view HYPERFLEET-XXX
# If good, create remaining tickets
# Delete test ticket when done
```
### 2. Store Description Files
Don't create tickets with inline strings. Always use files:
```bash
# Good
cat > /tmp/description.txt << 'EOF'
...
EOF
jira issue create ... -b "$(cat /tmp/description.txt)"
# Bad
jira issue create ... -b "h3. What\n\nLong description..."
```
### 3. Document Ticket Numbers
As tickets are created, track them:
```bash
# Epic created: HYPERFLEET-105
# Stories: HYPERFLEET-106, HYPERFLEET-107, HYPERFLEET-108
```
### 4. Batch Manual Steps
After creating multiple tickets via CLI:
1. List all ticket numbers
2. Open each in web UI
3. Batch set: story points, activity type, labels, epic links
4. More efficient than doing each individually
## Integration with Other Skills
This skill complements:
- **jira-story-pointer**: Use to refine story point estimates after creation
- **jira-hygiene**: Use to validate ticket quality after creation
- **jira-cli**: All operations use jira-cli under the hood
## Quick Reference Card
**Create Story:**
```bash
cat > /tmp/desc.txt << 'EOF'
h3. What
...
h3. Why
...
h3. Acceptance Criteria:
* ...
EOF
jira issue create --project HYPERFLEET --type Story \
--summary "Title" --no-input \
-b "$(cat /tmp/desc.txt)"
```
**Create Epic:**
```bash
jira issue create --project HYPERFLEET --type Epic \
--summary "Epic: Title" \
--custom epic-name="Short Name" \
--template /tmp/epic-desc.txt \
--no-input
```
**Manual Steps (Web UI):**
1. Story Points
2. Activity Type
3. Link to Epic
4. Labels
5. Code examples
**Formatting:**
- Headers: `h3. Text` (space!)
- Bullets: `*` and `**`
- Inline code: `{{code}}`
- Bold: `*text*`
- API endpoints: `*POST* /api/path/{id}`