From ffe96546043c440fd97a0dc833628d782f3a915c Mon Sep 17 00:00:00 2001 From: Rafael Benevides Date: Wed, 25 Mar 2026 19:39:15 -0300 Subject: [PATCH] HYPERFLEET-811: add hyperfleet-bugs-triage plugin and refactor jira-ticket-creator - Add bugs-triage skill for interactive Jira bug and GitHub issue triage - Refactor jira-ticket-creator: split into SKILL.md + 3 reference files - Correct formatting: jira-cli accepts Markdown (not wiki markup) - Add Activity Type tiebreaker rules and delegate story points to jira-story-pointer - Add language identifiers to all fenced code blocks --- .claude-plugin/marketplace.json | 5 + CLAUDE.md | 1 + .../.claude-plugin/plugin.json | 9 + hyperfleet-bugs-triage/OWNERS | 7 + hyperfleet-bugs-triage/README.md | 61 ++ .../skills/bugs-triage/SKILL.md | 289 ++++++++ .../bugs-triage/references/github-repos.md | 28 + .../skills/bugs-triage/references/owners.csv | 13 + hyperfleet-jira/.claude-plugin/plugin.json | 4 +- .../skills/jira-ticket-creator/SKILL.md | 669 ++---------------- .../references/cli-examples.md | 216 ++++++ .../references/formatting.md | 48 ++ .../references/pitfalls.md | 114 +++ 13 files changed, 849 insertions(+), 615 deletions(-) create mode 100644 hyperfleet-bugs-triage/.claude-plugin/plugin.json create mode 100644 hyperfleet-bugs-triage/OWNERS create mode 100644 hyperfleet-bugs-triage/README.md create mode 100644 hyperfleet-bugs-triage/skills/bugs-triage/SKILL.md create mode 100644 hyperfleet-bugs-triage/skills/bugs-triage/references/github-repos.md create mode 100644 hyperfleet-bugs-triage/skills/bugs-triage/references/owners.csv create mode 100644 hyperfleet-jira/skills/jira-ticket-creator/references/cli-examples.md create mode 100644 hyperfleet-jira/skills/jira-ticket-creator/references/formatting.md create mode 100644 hyperfleet-jira/skills/jira-ticket-creator/references/pitfalls.md diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index c790b60..0a53c5e 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -34,6 +34,11 @@ "name": "hyperfleet-code-review", "source": "./hyperfleet-code-review", "description": "Standardized PR review workflow with JIRA validation, HyperFleet architecture checks, impact analysis, and interactive recommendations" + }, + { + "name": "hyperfleet-bugs-triage", + "source": "./hyperfleet-bugs-triage", + "description": "Interactive JIRA bug triage (New->Backlog) and GitHub issue triage for openshift-hyperfleet repositories" } ] } diff --git a/CLAUDE.md b/CLAUDE.md index 7e3dd4c..7f644bb 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -31,6 +31,7 @@ hyperfleet-/ <- each plugin | `hyperfleet-operational-readiness` | Operational readiness audit | 1 skill | - | - | | `hyperfleet-devtools` | Dev productivity | 1 skill | 1 command | 1 agent | | `hyperfleet-adapter-authoring` | Adapter authoring | 1 skill | - | - | +| `hyperfleet-bugs-triage` | Bug & issue triage | 1 skill | - | - | ### Key Plugin: `hyperfleet-code-review` diff --git a/hyperfleet-bugs-triage/.claude-plugin/plugin.json b/hyperfleet-bugs-triage/.claude-plugin/plugin.json new file mode 100644 index 0000000..b873085 --- /dev/null +++ b/hyperfleet-bugs-triage/.claude-plugin/plugin.json @@ -0,0 +1,9 @@ +{ + "name": "hyperfleet-bugs-triage", + "version": "0.1.0", + "description": "Interactive JIRA bug triage (New->Backlog) and GitHub issue triage for openshift-hyperfleet repositories", + "author": { + "name": "Rafael Benevides", + "email": "rbenevid@redhat.com" + } +} diff --git a/hyperfleet-bugs-triage/OWNERS b/hyperfleet-bugs-triage/OWNERS new file mode 100644 index 0000000..e2d17e9 --- /dev/null +++ b/hyperfleet-bugs-triage/OWNERS @@ -0,0 +1,7 @@ +approvers: + - rafabene + - ciaranRoche + +reviewers: + - rafabene + - ciaranRoche diff --git a/hyperfleet-bugs-triage/README.md b/hyperfleet-bugs-triage/README.md new file mode 100644 index 0000000..33d4ade --- /dev/null +++ b/hyperfleet-bugs-triage/README.md @@ -0,0 +1,61 @@ +# hyperfleet-bugs-triage + +Interactive JIRA bug triage (New->Backlog) and GitHub issue triage for openshift-hyperfleet repositories. + +## Installation + +```bash +/install hyperfleet-bugs-triage@openshift-hyperfleet/hyperfleet-claude-plugins +``` + +## Usage + +```bash +/bugs-triage # Triage both JIRA bugs and GitHub issues +/bugs-triage jira # Triage only JIRA bugs +/bugs-triage github # Triage only GitHub issues +``` + +## What it does + +### JIRA Bug Triage + +1. Fetches all bugs with status "New" in the HYPERFLEET project +2. Skips bugs that already have an assignee +3. For each bug, presents an assessment and recommends an action: + - Move to Backlog + - Request more info + - Close (Won't Do / Rejected / Duplicate) + - Convert to RFE + - Set missing fields + - Escalate Blockers +4. Reports bugs open for more than 3 sprints (6 weeks) + +### GitHub Issues Triage + +1. Fetches untriaged issues across all openshift-hyperfleet repositories +2. Checks if issues are already tracked in JIRA or resolved by merged PRs +3. For each issue, presents an assessment and recommends an action: + - Accept as Bug (creates JIRA ticket) + - Accept as RFE (creates JIRA Story) + - Provide help + - Reject + - Mark as Duplicate + - Request info +4. Reports issues open for more than 3 sprints + +## Prerequisites + +- [jira-cli](https://github.com/ankitpokhrel/jira-cli) configured for the HYPERFLEET project +- [GitHub CLI](https://cli.github.com/) (`gh`) authenticated with access to openshift-hyperfleet repos + +## Reference Data + +The plugin includes reference files used during triage: + +| File | Purpose | +|------|---------| +| `references/owners.csv` | Component/domain owners for assignee suggestions | +| `references/github-repos.md` | Repositories in triage scope | + +Ticket creation (formatting, Activity Types, Story Points) is delegated to the `hyperfleet-jira:jira-ticket-creator` skill. diff --git a/hyperfleet-bugs-triage/skills/bugs-triage/SKILL.md b/hyperfleet-bugs-triage/skills/bugs-triage/SKILL.md new file mode 100644 index 0000000..cd5c41d --- /dev/null +++ b/hyperfleet-bugs-triage/skills/bugs-triage/SKILL.md @@ -0,0 +1,289 @@ +--- +name: bugs-triage +description: Triage Jira bugs (New->Backlog) and GitHub issues for openshift-hyperfleet repos interactively. +allowed-tools: Bash, Read, Grep, Glob, AskUserQuestion, Skill +argument-hint: "[jira|github] (default: both)" +--- + +# Bug Triage Skill + +## Dynamic context + +- jira CLI: !`command -v jira >/dev/null 2>&1 && echo "available" || echo "NOT available"` +- gh CLI: !`command -v gh >/dev/null 2>&1 && echo "available" || echo "NOT available"` + +## Arguments + +- No argument: Run both Jira and GitHub triage +- `jira`: Run only Jira bug triage +- `github`: Run only GitHub issues triage + +## References + +Load these files as needed during triage: + +- `references/owners.csv` — Component/domain owners for assignee suggestions +- `references/github-repos.md` — GitHub repositories in triage scope (skip issues from unlisted repos) + +## Ticket Creation + +When creating JIRA tickets (e.g., from accepted GitHub issues or RFE conversions), use the `hyperfleet-jira:jira-ticket-creator` skill via the Skill tool. This skill handles description formatting, Activity Type classification, Story Points estimation, and all ticket creation best practices. Pass the issue context (title, description, component, suggested priority) as the skill argument. + +## Link Formatting + +ALWAYS include clickable links in all tables, headings, and references: + +- Jira: `[TICKET-KEY](https://redhat.atlassian.net/browse/TICKET-KEY)` +- GitHub: `[REPO#NUMBER](https://github.com/openshift-hyperfleet/REPO/issues/NUMBER)` + +## Priority SLA Reference + +| Priority | Triage SLA | Fix/Workaround SLA | +|----------|------------|---------------------| +| **Blocker** | Within 24 hours | Within 72 working hours | +| **Critical/Major** | Per Week | Within 5 working days | +| **Normal** | Per Sprint | Must be fixed in coming release | +| **Low** | Per Sprint | Planned per capacity; max 2 sprints, re-evaluate in 3rd | + +--- + +## Part 1: Jira Bug Triage (New -> Backlog) + +### Step 1: Fetch all bugs with status "New" + +```bash +jira issue list -q"project = HYPERFLEET AND status = New AND issuetype = Bug" --plain --columns "KEY,SUMMARY,PRIORITY,STATUS,COMPONENT,ASSIGNEE,CREATED" 2>/dev/null +``` + +If no bugs found, report "No bugs in New status" and skip to Step 5. + +### Step 2: Fetch bugs open for more than 3 sprints (approximately 6 weeks) + +```bash +jira issue list -q"project = HYPERFLEET AND issuetype = Bug AND status not in (Closed, Done) AND created <= -42d" --plain --columns "KEY,SUMMARY,PRIORITY,STATUS,ASSIGNEE,CREATED" 2>/dev/null +``` + +### Step 3: Interactive triage of each "New" bug + +**Skip bugs that already have an assignee** — they are already being handled. + +For each remaining bug, do the following **one at a time**: + +#### 3a. Fetch full details + +```bash +jira issue view TICKET-KEY --plain 2>/dev/null +``` + +#### 3b. Present the bug and assess + +Start with a heading: `### [TICKET-KEY](https://redhat.atlassian.net/browse/TICKET-KEY) - Summary` + +Evaluate and present: + +| Check | Status | Notes | +|-------|--------|-------| +| Sufficient info/logs | PASS/FAIL | Logs, steps to reproduce, environment details? | +| Priority set correctly | PASS/FAIL/MISSING | Based on SLA table | +| Component identified | PASS/FAIL/MISSING | Must be: API, Adapter, Sentinel, Broker, Architecture. If multiple components apply, add ALL | +| Target version | SET/MISSING | If MVP bug, set "MVP". Otherwise set planned fix version per release strategy (if field is available) | +| Valid bug | LIKELY/UNCLEAR | Real defect? Or actually a feature request (RFE)? | +| Hyperfleet scope | YES/NO | If not in Hyperfleet scope, move to the correct Jira Project | +| Assignee | SET/MISSING | If missing, suggest owner from `references/owners.csv` | + +#### 3c. Recommend one action + +1. **Move to Backlog** — valid, enough info, fields set +2. **Request more info** — missing logs/steps/environment +3. **Close as Won't Do** — valid bug/request but out of scope or low ROI +4. **Close as Rejected** — not a real bug (environmental issue, non-reproducible) +5. **Close as Duplicate** — search for duplicates first: + ```bash + jira issue list -q"project = HYPERFLEET AND issuetype = Bug AND summary ~ 'keyword'" --plain 2>/dev/null + ``` +6. **Convert to RFE** — if the bug is actually a feature request, create a Story/Task with `[RFE]` prefix and keep in "New" status +7. **Move to another Jira Project** — if not in Hyperfleet scope, move to the correct project +8. **Set missing fields first** — priority, component, or target version missing +9. **Escalate to tech leads** — if Blocker priority. The 24h goal is to deliver a fix/workaround OR provide a high-confidence RCA with next steps. Tag tech leads and managers in Slack immediately + +#### 3d. Ask the user and execute + +Use `AskUserQuestion` to confirm the action, then execute: + +- Move to Backlog: `jira issue move TICKET-KEY "Backlog"` +- Set priority: `jira issue edit TICKET-KEY --priority "Normal" --no-input` — **always add a comment explaining why** the priority was changed +- Set component: `jira issue edit TICKET-KEY --component "Name" --no-input` — if multiple components apply, add all of them +- Set target version: `jira issue edit TICKET-KEY --custom target-version="MVP" --no-input` (if the field is available in the project) +- Request info: `jira issue comment add TICKET-KEY "..."` +- Close: `jira issue move TICKET-KEY "Closed" --resolution ""` — valid resolutions: `Won't Do`, `Rejected`, `Duplicate` +- Duplicate link: `jira issue link TICKET-KEY DUPLICATE-KEY "Duplicate"` +- Convert to RFE: Change type to Story/Task, add `[RFE]` prefix to summary, keep in "New" status +- Move to another project: Ask user which project, then move the ticket +- Escalate Blocker: Inform user to notify tech leads AND managers via Slack. Goal: fix/workaround or RCA within 24h + +### Step 4: Report bugs open > 3 sprints + +Present in a table and ask the user to re-evaluate or close each one: + +```markdown +| Ticket | Priority | Status | Assignee | Created | +``` + +**Low priority rule:** Bugs with Low priority can be held for max 2 sprints. In the 3rd sprint, recommend re-evaluating — either fix or close them. Do not defer indefinitely. + +### Step 5: Jira Triage Summary + +```markdown +| Metric | Count | +|--------|-------| +| Bugs triaged | X | +| Moved to Backlog | X | +| Closed (Won't Do/Rejected/Duplicate) | X | +| Info requested | X | +| Skipped | X | +| Bugs open > 3 sprints | X | +``` + +--- + +## Part 2: GitHub Issues Triage + +### Step 1: Fetch untriaged issues + +First, read `references/github-repos.md` to get the list of repos in scope. Build the `repo:` filter dynamically from that file — extract each repo name and prepend `repo:openshift-hyperfleet/`. The query fetches issues that are either unlabeled or have `hf-needs-triage` but NOT already triaged labels: + +```bash +# Example with 3 repos (build dynamically from references/github-repos.md): +gh api search/issues -X GET \ + -f q="is:issue is:open -label:hf-triaged/accepted -label:hf-triaged/rejected -label:hf-triaged/duplicate repo:openshift-hyperfleet/REPO1 repo:openshift-hyperfleet/REPO2 repo:openshift-hyperfleet/REPO3" \ + -f per_page=50 \ + --jq '.items[] | "\(.repository_url | split("/") | .[-1])|\(.number)|\(.title)|\(.state)|\(.labels | map(.name) | join(","))|\(.created_at[:10])"' 2>/dev/null +``` + +If none found, report "No untriaged GitHub issues" and skip to summary. + +### Step 2: Fetch issues open > 3 sprints (6 weeks) + +Query the same scoped repos (built dynamically from `references/github-repos.md`): + +```bash +DATE=$(date -d '42 days ago' '+%Y-%m-%d' 2>/dev/null || date -v-42d '+%Y-%m-%d') +# Use the same dynamically-built repo filter as Step 1 +gh api search/issues -X GET \ + -f q="is:issue is:open created:<$DATE repo:openshift-hyperfleet/REPO1 repo:openshift-hyperfleet/REPO2 repo:openshift-hyperfleet/REPO3" \ + -f per_page=50 \ + --jq '.items[] | "\(.repository_url | split("/") | .[-1])|\(.number)|\(.title)|\(.created_at[:10])|\(.labels | map(.name) | join(","))"' 2>/dev/null +``` + +### Step 3: Interactive triage of each issue + +For each untriaged issue, do the following **one at a time**: + +#### 3a. Fetch full details + +```bash +gh issue view NUMBER --repo openshift-hyperfleet/REPO_NAME 2>/dev/null +``` + +#### 3b. Check if already tracked or resolved + +Before assessing, search for existing Jira tickets and merged PRs: + +```bash +jira issue list -q"project = HYPERFLEET AND summary ~ 'keyword'" --plain --columns "KEY,SUMMARY,STATUS" 2>/dev/null +``` + +```bash +gh pr list --repo openshift-hyperfleet/REPO_NAME --state merged --search "keyword" --limit 5 2>/dev/null +``` + +- If Jira ticket exists but no merged PR found: comment on GitHub linking to the Jira ticket, add `hf-triaged/accepted` label, **keep the issue open** (a Closed/Done Jira ticket alone does not prove the fix is in the repo), skip +- If code already fixed (merged PR found): comment referencing the PR, add `hf-triaged/accepted` label, close the issue, skip + +Always add the appropriate triage label (`hf-triaged/accepted`, `hf-triaged/rejected`, or `hf-triaged/duplicate`) when closing or resolving an issue. + +#### 3c. Present the issue and assess + +Start with: `### [REPO#NUMBER](https://github.com/openshift-hyperfleet/REPO/issues/NUMBER) - Title` + +| Check | Status | Notes | +|-------|--------|-------| +| Sufficient info | PASS/FAIL | Clear description, steps, context? | +| Labels present | PASS/FAIL | Existing labels? | +| Category | Bug/RFE/Help Request | Classify the issue | +| Hyperfleet scope | YES/NO/UNCLEAR | Within Hyperfleet's scope? | + +#### 3d. Recommend one action + +1. **Accept as Bug** — create Jira Bug, label `hf-triaged/accepted` +2. **Accept as RFE** — create Jira Story with `[RFE]` prefix, label `hf-triaged/accepted` +3. **Provide help** — answer on GitHub, label `hf-triaged/accepted` +4. **Reject** — close with explanation, label `hf-triaged/rejected` +5. **Mark as Duplicate** — link to existing issue, label `hf-triaged/duplicate` +6. **Request info** — comment requesting details, label `hf-needs-info` + +#### 3e. Ask the user and execute + +Use `AskUserQuestion` to confirm, then execute. Adding labels may fail due to repo permissions — handle gracefully and report. + +**For accepted bugs/RFEs — create Jira ticket:** + +Use the `hyperfleet-jira:jira-ticket-creator` skill via the Skill tool, passing the issue context (title, description, component, suggested priority). The skill handles description formatting, Activity Type, Story Points, and all creation best practices. + +After creating the Jira ticket, comment on the GitHub issue and add label. **Keep the GitHub issue open** until the fix is available in the repository: + +```bash +gh issue comment NUMBER --repo openshift-hyperfleet/REPO_NAME --body "This issue has been accepted and is being tracked in JIRA as [HYPERFLEET-XXX](https://redhat.atlassian.net/browse/HYPERFLEET-XXX). We will update this issue when there is progress." 2>/dev/null +``` + +```bash +gh issue edit NUMBER --repo openshift-hyperfleet/REPO_NAME --add-label "hf-triaged/accepted" 2>&1 +``` + +### Step 4: Report issues open > 3 sprints + +Present in a table and ask the user to re-evaluate or close each one: + +```markdown +| Issue | Title | Created | Labels | +``` + +### Step 5: GitHub Triage Summary + +```markdown +| Metric | Count | +|--------|-------| +| Issues triaged | X | +| Accepted (Bug) | X | +| Accepted (RFE) | X | +| Help provided | X | +| Rejected | X | +| Duplicate | X | +| Info requested | X | +| Skipped | X | +| Issues open > 3 sprints | X | +``` + +--- + +## Final Summary + +Present a combined summary of all triage actions taken during the session. + +## Important Rules + +- Use `jira` CLI for Jira and `gh` CLI for GitHub; do not use other external CLIs, but allowed-tools (AskUserQuestion, Read, Skill) may be used as declared +- Process tickets **one at a time** — never batch without user confirmation +- Always provide a clear reason when closing tickets +- **Skip Jira bugs that already have an assignee** — they are already being handled +- **When changing priority**, always add a comment explaining the rationale +- **If a bug applies to multiple components**, add ALL related components +- **If a bug is not in Hyperfleet scope**, move it to the correct Jira Project +- **If a bug is really a feature request**, convert to Story/Task with `[RFE]` prefix in "New" status +- **For Blocker bugs**, immediately tag tech leads AND managers in Slack. 24h goal: fix/workaround OR high-confidence RCA + next steps +- When creating Jira tickets from GitHub issues, always link back to the original issue +- **Keep accepted GitHub issues open** until the fix is available in the repository +- Use the `hyperfleet-jira:jira-ticket-creator` skill when creating Jira tickets (handles formatting, Activity Type, and Story Points) +- Consult `references/owners.csv` to suggest assignees based on component +- Output in English +- ALWAYS include clickable links for every ticket/issue reference diff --git a/hyperfleet-bugs-triage/skills/bugs-triage/references/github-repos.md b/hyperfleet-bugs-triage/skills/bugs-triage/references/github-repos.md new file mode 100644 index 0000000..4fc9b86 --- /dev/null +++ b/hyperfleet-bugs-triage/skills/bugs-triage/references/github-repos.md @@ -0,0 +1,28 @@ +# GitHub Repositories in Triage Scope + +Only issues from these `openshift-hyperfleet` repositories should be triaged. +Issues from repos not listed here should be skipped. + +## Core Components + +- `hyperfleet-api` +- `hyperfleet-adapter` +- `hyperfleet-sentinel` +- `hyperfleet-broker` + +## Infrastructure & Deployment + +- `hyperfleet-chart` +- `hyperfleet-infra` +- `hyperfleet-credential-provider` +- `hyperfleet-logger` + +## Testing & CLI + +- `hyperfleet-e2e` +- `maestro-cli` + +## Documentation & Tooling + +- `architecture` +- `hyperfleet-claude-plugins` diff --git a/hyperfleet-bugs-triage/skills/bugs-triage/references/owners.csv b/hyperfleet-bugs-triage/skills/bugs-triage/references/owners.csv new file mode 100644 index 0000000..08b2c8f --- /dev/null +++ b/hyperfleet-bugs-triage/skills/bugs-triage/references/owners.csv @@ -0,0 +1,13 @@ +type,name,primary_owner,secondary_owner +component,Hyperfleet API,Yanming Sun,Angel Marin +component,Broker,Angel Marin,dandan wang +component,Adapter,Xue Li,Angel Marin +component,Sentinel,Rafael Benevides,"Phuongnhat Nguyen, Yanming Sun" +component,CICD,Ying Zhang, +component,Claude Code Plugin,Rafael Benevides,Yanming Sun +domain,Hyperfleet Architecture,Victor Kareh Fabregas,Ciaran Roche +domain,CLM Architecture,Ciaran Roche,Angel Marin +domain,CICD Framework,Xue Li, +domain,Test Automation Framework,Yanming Sun,Ying Zhang +domain,Deployment Strategy,Ciaran Roche,Rafael Benevides +domain,Implementation Standard,"Angel Marin, Rafael Benevides",Ciaran Roche diff --git a/hyperfleet-jira/.claude-plugin/plugin.json b/hyperfleet-jira/.claude-plugin/plugin.json index bc30891..4629a8f 100644 --- a/hyperfleet-jira/.claude-plugin/plugin.json +++ b/hyperfleet-jira/.claude-plugin/plugin.json @@ -1,7 +1,7 @@ { "name": "hyperfleet-jira", - "version": "0.4.0", - "description": "JIRA integration for HyperFleet team - sprint management, task tracking, ticket creation with proper JIRA wiki markup, triage, and story point estimation", + "version": "0.4.1", + "description": "JIRA integration for HyperFleet team - sprint management, task tracking, ticket creation, triage, and story point estimation", "author": { "name": "Ciaran Roche", "email": "croche@redhat.com" diff --git a/hyperfleet-jira/skills/jira-ticket-creator/SKILL.md b/hyperfleet-jira/skills/jira-ticket-creator/SKILL.md index 9e64864..4bf4447 100644 --- a/hyperfleet-jira/skills/jira-ticket-creator/SKILL.md +++ b/hyperfleet-jira/skills/jira-ticket-creator/SKILL.md @@ -5,25 +5,17 @@ description: Creates well-structured JIRA tickets in the HYPERFLEET project with # JIRA Ticket Creator Skill -## ⚠️ CRITICAL: JIRA Uses Wiki Markup, NOT Markdown! +## Formatting -**YOU MUST USE JIRA WIKI MARKUP SYNTAX - NEVER USE MARKDOWN!** +The `jira-cli` accepts **Markdown** and converts it to ADF (Atlassian Document Format) for JIRA Cloud. Standard Markdown works correctly — headers, bullets, bold, inline code, fenced code blocks, and curly braces all render as expected. -| 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` | +## References -**If you use Markdown syntax, the ticket will render incorrectly in JIRA!** +Load these files as needed: -See "CRITICAL: JIRA Wiki Markup Formatting" section below for complete reference. - ---- +- [references/formatting.md](references/formatting.md) — Formatting rules and known issues +- [references/cli-examples.md](references/cli-examples.md) — CLI commands and description templates for each ticket type +- [references/pitfalls.md](references/pitfalls.md) — Common pitfalls, troubleshooting, and best practices ## When to Use This Skill @@ -39,35 +31,39 @@ Activate this skill when the user: Every ticket created MUST include: -### 1. **What** (Required) +### 1. What (Required) + Clear, concise description of what needs to be done. Should be 2-4 sentences explaining the work. -### 2. **Why** (Required) +### 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) +### 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) +### 4. Story Points (Required for Stories/Tasks/Bugs) + +All Stories, Tasks, and Bugs must have story points (scale: 0, 1, 3, 5, 8, 13). + +### 5. Priority (Required) -### 5. **Priority** (Required) -Set priority via CLI using `-y` or `--priority`: +Set priority via CLI using `--priority`: - `Blocker` - Blocks development/testing, must be fixed immediately - `Critical` - Crashes, data loss, severe memory leak - `Major` - Major loss of function - `Normal` - Default priority for most work - `Minor` - Minor loss of function, easy workaround -### 6. **Activity Type** (Required for Stories/Tasks/Bugs) +### 6. Activity Type (Required for Stories/Tasks/Bugs) + Set activity type via CLI using `--custom activity-type=""`. Valid types: - `Associate Wellness & Development` - Training, onboarding, team growth - `Incidents & Support` - Customer escalations, production issues @@ -76,127 +72,18 @@ Set activity type via CLI using `--custom activity-type=""`. Valid types: - `Future Sustainability` - Tooling, automation, architecture improvements - `Product / Portfolio Work` - New features, strategic product work +**Tiebreaker Rules (when category is unclear):** +- If the ticket **fixes something existing** -> `Quality / Stability / Reliability` +- If it **prevents future problems or improves processes** -> `Future Sustainability` +- If it **delivers new value to the customer** -> `Product / Portfolio Work` + ### 7. 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--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 @@ -211,297 +98,49 @@ Ask the user clarifying questions if needed: ### 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 +Create a temporary file with the description in **Markdown**. The `jira-cli` converts Markdown to ADF automatically. -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 -``` +See [references/cli-examples.md](references/cli-examples.md) for description templates per ticket type. ### Step 3: Determine Story Points -Use the estimation scale (from jira-story-pointer): - -| 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 | +Use the `jira-story-pointer` skill via the Skill tool to estimate story points. It analyzes complexity factors (scope, technical complexity, dependencies, testing effort, risk), searches for similar historical tickets, and provides a confidence-rated recommendation. Pass the ticket context (description, acceptance criteria, type) as the skill argument. -Consider: -- Scope (lines of code, files affected, integration points) -- Complexity (new patterns, unfamiliar tech) -- Risk (ambiguity, dependencies, unknowns) -- Testing effort +Valid story points: 0, 1, 3, 5, 8, 13. Tickets estimated at 13 should be split. ### 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 +Choose based on the Activity Type table above. Evaluate in priority order (first match wins): Incidents & Support > Security & Compliance > Quality/Stability/Reliability > Associate Wellness > Future Sustainability > Product/Portfolio 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. +See [references/cli-examples.md](references/cli-examples.md) for complete CLI commands for each ticket type (Story, Task, Epic, Bug). -h3. Why +Key patterns: +- Always save descriptions to temporary files first +- Use `-b "$(cat /tmp/file.txt)"` to pass descriptions +- Use `--no-input` for non-interactive creation +- Use `--custom story-points=X` and `--custom activity-type="..."` for custom fields -* Reason 1 -* Reason 2 +### Step 6: Post-Creation Steps -h3. Acceptance Criteria: - -* Criterion 1 -* Criterion 2 -* Criterion 3 - -h3. Technical Notes: - -* Use {{package-name}} -* Configuration in {{/path/to/config}} -EOF - -# 2. Create story with story points, priority, and activity type -jira issue create --project HYPERFLEET --type Story \ - --summary "Story Title (< 100 chars)" \ - --custom story-points=5 \ - --custom activity-type="Product / Portfolio Work" \ - --priority Normal \ - --no-input \ - -b "$(cat /tmp/story-description.txt)" - -# 3. Note the ticket number from output (e.g., HYPERFLEET-123) -``` - -#### 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" \ - --custom story-points=3 \ - --custom activity-type="Future Sustainability" \ - --priority Normal \ - --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" \ - --custom story-points=5 \ - --custom activity-type="Quality / Stability / Reliability" \ - --priority Major \ - --no-input \ - -b "$(cat /tmp/bug-description.txt)" -``` - -### Step 6: Post-Creation Manual Steps - -After creating a ticket via CLI, these may need to be done manually via web UI: - -1. **Link to Epic** (for Stories) - - Edit ticket → Link → "is child of" → Epic ticket - -2. **Add Labels** - - Edit ticket → Labels field - - Add relevant tags - -3. **Add Code Examples** (if needed) - - Edit description via web UI - - Add `{code:language}...{/code}` blocks - - Code blocks don't render properly via CLI - -Note: Story points, priority, and activity type can all be set via CLI. +All fields can be set via CLI during creation: +- **Link to Epic**: use `-P EPIC-KEY` (or `--parent EPIC-KEY`) +- **Add Labels**: use `-l label1 -l label2` +- **Add Component**: use `-C ComponentName` +- **Code blocks**: use fenced code blocks (triple backticks) in the description — they render correctly 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 +- Link: https://redhat.atlassian.net/browse/HYPERFLEET-123 - Summary of what was created -- **List of manual steps needed** (story points, activity type, etc.) +- **List of manual steps needed** ## Output Format @@ -512,11 +151,11 @@ When creating a ticket, provide this output to the user: **Type:** [Story/Task/Epic/Bug] **Summary:** [Title] -**Link:** https://issues.redhat.com/browse/HYPERFLEET-XXX +**Link:** https://redhat.atlassian.net/browse/HYPERFLEET-XXX --- -#### Description Structure (✅ Created via CLI) +#### Description Structure **What:** [What description] @@ -525,9 +164,9 @@ When creating a ticket, provide this output to the user: [Why description] **Acceptance Criteria:** -* Criterion 1 -* Criterion 2 -* Criterion 3 +- Criterion 1 +- Criterion 2 +- Criterion 3 **Story Points:** [X points - set via CLI] **Priority:** [Priority - set via CLI] @@ -535,212 +174,16 @@ When creating a ticket, provide this output to the user: --- -#### Manual Steps Required (⚠️ Must be done via Web UI) - -Please complete these steps in the JIRA web interface: +#### Post-Creation (if not set during creation) -1. **Link to Epic**: [If applicable: Link to HYPERFLEET-XXX] -2. **Add Labels**: [Suggested: label1, label2] -3. **Add Code Examples**: [If needed: Add via web UI description editor] - -**Why manual?** Epic links 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 `--body-file` flag (doesn't exist!) -11. ❌ 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 story points via CLI: `--custom story-points=X` -6. Set priority via CLI: `--priority Normal` -7. Set activity type via CLI: `--custom activity-type="Product / Portfolio Work"` -8. Add code examples via web UI -9. Use bold for HTTP methods: `*POST* /api/path` -10. 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: Story Points Not Setting - -**Solution:** Use the exact syntax `--custom story-points=X` where X is 0, 1, 3, 5, 8, or 13. Example: -```bash -jira issue create --project HYPERFLEET --type Story \ - --summary "Title" --custom story-points=5 --no-input \ - -b "$(cat /tmp/desc.txt)" -``` - -Note: Activity type must still be set via web UI. - -## 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..." +1. **Link to Epic**: `jira issue edit HYPERFLEET-XXX --parent EPIC-KEY --no-input` +2. **Add Labels**: `jira issue edit HYPERFLEET-XXX -l label1 -l label2 --no-input` +3. **Add Component**: `jira issue edit HYPERFLEET-XXX -C "Sentinel" --no-input` ``` -### 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-story-pointer**: Used in Step 3 to estimate story points (complexity analysis, historical comparison) - **jira-triage**: 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" \ - --custom story-points=5 \ - --custom activity-type="Product / Portfolio Work" \ - --priority Normal \ - --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 -``` - -**Story Points via CLI:** -| Points | When to Use | -|--------|-------------| -| `--custom story-points=0` | Tracking only, negligible effort | -| `--custom story-points=1` | Trivial, one-line change | -| `--custom story-points=3` | Straightforward, time consuming | -| `--custom story-points=5` | Medium, needs investigation/collaboration | -| `--custom story-points=8` | Large, design doc required | -| `--custom story-points=13` | Too large - break it down! | - -**Priority via CLI:** -| Priority | When to Use | -|----------|-------------| -| `--priority Blocker` | Blocks development/testing, fix immediately | -| `--priority Critical` | Crashes, data loss, severe memory leak | -| `--priority Major` | Major loss of function | -| `--priority Normal` | Default for most work | -| `--priority Minor` | Minor loss of function, easy workaround | - -**Activity Type via CLI:** -| Activity Type | When to Use | -|---------------|-------------| -| `--custom activity-type="Associate Wellness & Development"` | Training, onboarding, team growth | -| `--custom activity-type="Incidents & Support"` | Customer escalations, production issues | -| `--custom activity-type="Security & Compliance"` | CVEs, security patches, compliance | -| `--custom activity-type="Quality / Stability / Reliability"` | Bugs, tech debt, toil reduction | -| `--custom activity-type="Future Sustainability"` | Tooling, automation, architecture | -| `--custom activity-type="Product / Portfolio Work"` | New features, strategic product work | - -**Manual Steps (Web UI):** -1. Link to Epic -2. Labels -3. Code examples - -**Formatting:** -- Headers: `h3. Text` (space!) -- Bullets: `*` and `**` -- Inline code: `{{code}}` -- Bold: `*text*` -- API endpoints: `*POST* /api/path/:id` diff --git a/hyperfleet-jira/skills/jira-ticket-creator/references/cli-examples.md b/hyperfleet-jira/skills/jira-ticket-creator/references/cli-examples.md new file mode 100644 index 0000000..7bc9c4c --- /dev/null +++ b/hyperfleet-jira/skills/jira-ticket-creator/references/cli-examples.md @@ -0,0 +1,216 @@ +# JIRA CLI Ticket Creation Examples + +## Creating a Story + +```bash +# 1. Save description to temporary file (use Markdown) +cat > /tmp/story-description.txt << 'EOF' +### What + +Description of what needs to be done. + +### Why + +- Reason 1 +- Reason 2 + +### Acceptance Criteria + +- Criterion 1 +- Criterion 2 +- Criterion 3 + +### Technical Notes + +- Use `package-name` for implementation +- Configuration in `/path/to/config` +EOF + +# 2. Create story with all fields +jira issue create --project HYPERFLEET --type Story \ + --summary "Story Title (< 100 chars)" \ + --custom story-points=5 \ + --custom activity-type="Product / Portfolio Work" \ + --priority Normal \ + -C "Sentinel" \ + -l feature \ + -P HYPERFLEET-100 \ + --no-input \ + -b "$(cat /tmp/story-description.txt)" + +# Note: -C = component, -l = label (repeatable), -P = parent epic +``` + +## Creating a Task + +```bash +cat > /tmp/task-description.txt << 'EOF' +### What + +Task description. + +### Why + +Justification. + +### Acceptance Criteria + +- Criterion 1 +- Criterion 2 +EOF + +jira issue create --project HYPERFLEET --type Task \ + --summary "Task Title" \ + --custom story-points=3 \ + --custom activity-type="Future Sustainability" \ + --priority Normal \ + --no-input \ + -b "$(cat /tmp/task-description.txt)" +``` + +## Creating an Epic + +**CRITICAL: Epics require the Epic Name field!** + +```bash +cat > /tmp/epic-description.txt << 'EOF' +# Epic Full Title + +### Overview + +Overview paragraph. + +### What + +- Deliverable 1 +- Deliverable 2 + +### Why + +Explanation. + +### Success Criteria + +- Criterion 1 +- Criterion 2 +EOF + +# 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' +### What + +Description of the bug and its impact. + +### Why + +Why this needs to be fixed urgently. + +### 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" \ + --custom story-points=5 \ + --custom activity-type="Quality / Stability / Reliability" \ + --priority Major \ + -C "API" \ + --no-input \ + -b "$(cat /tmp/bug-description.txt)" +``` + +## Description Templates (Markdown) + +### Story/Task Template + +```markdown +### What + +Brief description paragraph. + +Detailed explanation paragraph (optional). + +### Why + +- Reason 1 +- Reason 2 +- Reason 3 + +### Acceptance Criteria + +- `component` created/implemented/configured +- Feature X works correctly: + - Detail 1 + - Detail 2 +- Tests achieve >80% coverage +- Documentation updated + +### Technical Notes + +- Use `package-name` for implementation +- Configuration in `/path/to/config.yaml` +- Important consideration + +### Out of Scope + +- Item not included +- Another exclusion +``` + +### Epic Template + +```markdown +# Epic Title + +### Overview + +Brief overview paragraph. + +### What + +- Key deliverable 1 +- Key deliverable 2 + - Sub-item +- Key deliverable 3 + +### Why + +Explanation of business value and impact. + +### Scope + +**In Scope:** +- Item 1 +- Item 2 + +**Out of Scope:** +- Item 3 +- Item 4 + +### Success Criteria + +- Criterion 1 +- Criterion 2 +- Criterion 3 +``` + +## Important Reminders + +- Fenced code blocks (triple backticks) work correctly via CLI +- The `-b` flag takes precedence over `--template` diff --git a/hyperfleet-jira/skills/jira-ticket-creator/references/formatting.md b/hyperfleet-jira/skills/jira-ticket-creator/references/formatting.md new file mode 100644 index 0000000..a077b22 --- /dev/null +++ b/hyperfleet-jira/skills/jira-ticket-creator/references/formatting.md @@ -0,0 +1,48 @@ +# JIRA Description Formatting Reference + +The `jira-cli` accepts **Markdown** (GitHub-flavored and Jira-flavored) and automatically converts it to ADF (Atlassian Document Format) for JIRA Cloud. Use standard Markdown for descriptions — headers, bullets, bold, inline code, fenced code blocks, and curly braces all render correctly. + +## Markdown Example + +```markdown +### What + +Description paragraph. + +### Why + +- Reason 1 +- Reason 2 + +### Acceptance Criteria + +- `component` created/implemented +- Feature X works correctly: + - Detail 1 + - Detail 2 +- Tests achieve >80% coverage + +**Bold text** and `inline code` work as expected. +``` + +## Code Blocks + +Fenced code blocks (triple backticks) work correctly when created via CLI — the `jira-cli` converts them to ADF code block nodes. + +## API Endpoints in Descriptions + +```text +**POST** /api/v1/clusters/:id (bold method, colon notation) +**GET** /api/v1/clusters/{id} (curly braces work too) +``` + +## Custom Fields + +Use field aliases, NOT raw field IDs: + +```bash +--custom story-points=3 # Correct +--custom activity-type="Quality / Stability / Reliability" # Correct +--custom customfield_10028=3 # Wrong (silently ignored) +--custom customfield_10464="..." # Wrong (silently ignored) +``` diff --git a/hyperfleet-jira/skills/jira-ticket-creator/references/pitfalls.md b/hyperfleet-jira/skills/jira-ticket-creator/references/pitfalls.md new file mode 100644 index 0000000..be9dddf --- /dev/null +++ b/hyperfleet-jira/skills/jira-ticket-creator/references/pitfalls.md @@ -0,0 +1,114 @@ +# Common Pitfalls, Troubleshooting, and Best Practices + +## Common Pitfalls + +### DON'T + +1. Use `--body-file` flag — it doesn't exist! Use `-b "$(cat /tmp/file.txt)"` instead +2. Use raw field IDs like `--custom customfield_10028=3` — silently ignored! Use aliases + +### DO + +1. Use standard Markdown for descriptions +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 story points via CLI: `--custom story-points=X` +6. Set priority via CLI: `--priority Normal` +7. Set activity type via CLI: `--custom activity-type="Product / Portfolio Work"` +8. Set component via CLI: `-C "Sentinel"` +9. Set labels via CLI: `-l label1 -l label2` +10. Link to epic via CLI: `-P EPIC-KEY` +11. Use **bold** for HTTP methods: `**POST** /api/path/:id` + +## Troubleshooting + +### Issue: Epic Name Required Error + +```text +Error: customfield_12311141: Epic Name is required. +``` + +**Solution:** + +```bash +--custom epic-name="Short Name" # Correct +--custom epicName="Name" # Wrong +--custom customfield_12311141 # Wrong +``` + +### Issue: Story Points Not Setting + +**Solution:** Use the exact syntax `--custom story-points=X` where X is 0, 1, 3, 5, 8, or 13. Example: + +```bash +jira issue create --project HYPERFLEET --type Story \ + --summary "Title" --custom story-points=5 --no-input \ + -b "$(cat /tmp/desc.txt)" +``` + +### Issue: Activity Type Not Setting + +**Solution:** Use the exact syntax with quotes: `--custom activity-type="Quality / Stability / Reliability"`. Use field aliases, never raw IDs. + +### Issue: Description is Empty After Creation + +**Solution:** Sometimes `-b "$(cat ...)"` fails silently. Verify with `jira issue view HYPERFLEET-XXX --plain`. If empty, set via pipe: + +```bash +cat /tmp/description.txt | jira issue edit HYPERFLEET-XXX --no-input +``` + +## 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 +``` + +### 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 "### 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 Post-Creation Edits + +After creating multiple tickets via CLI, if any fields were missed: + +```bash +# Link to epic +jira issue edit HYPERFLEET-XXX --parent HYPERFLEET-100 --no-input + +# Add labels +jira issue edit HYPERFLEET-XXX -l label1 -l label2 --no-input + +# Add component +jira issue edit HYPERFLEET-XXX -C "Sentinel" --no-input +```