diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json index f632ecd5..449eac32 100644 --- a/.agents/plugins/marketplace.json +++ b/.agents/plugins/marketplace.json @@ -16,6 +16,18 @@ }, "category": "Productivity" }, + { + "name": "atlassian-rovo", + "source": { + "source": "local", + "path": "./plugins/atlassian-rovo" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Productivity" + }, { "name": "google-calendar", "source": { diff --git a/plugins/atlassian-rovo/.app.json b/plugins/atlassian-rovo/.app.json new file mode 100644 index 00000000..eda6cbda --- /dev/null +++ b/plugins/atlassian-rovo/.app.json @@ -0,0 +1,7 @@ +{ + "apps": { + "atlassian-rovo": { + "id": "connector_692de805e3ec8191834719067174a384" + } + } +} diff --git a/plugins/atlassian-rovo/.codex-plugin/plugin.json b/plugins/atlassian-rovo/.codex-plugin/plugin.json new file mode 100644 index 00000000..6be926c0 --- /dev/null +++ b/plugins/atlassian-rovo/.codex-plugin/plugin.json @@ -0,0 +1,34 @@ +{ + "name": "atlassian-rovo", + "version": "1.0.0", + "description": "Manage Jira and Confluence fast", + "author": { + "url": "https://www.atlassian.com" + }, + "homepage": "https://www.atlassian.com", + "repository": "https://github.com/openai/plugins", + "license": "MIT", + "keywords": [ + "atlassian" + ], + "skills": "./skills/", + "apps": "./.app.json", + "interface": { + "displayName": "Atlassian Rovo", + "shortDescription": "Manage Jira and Confluence fast", + "longDescription": "Manage Jira and Confluence fast", + "category": "Productivity", + "capabilities": [ + "Interactive", + "Write" + ], + "websiteURL": "https://www.atlassian.com", + "privacyPolicyURL": "https://www.atlassian.com/legal/privacy-policy", + "defaultPrompt": [ + "Create Jira tasks in project Vita MVP" + ], + "screenshots": [], + "composerIcon": "./assets/app-icon.png", + "logo": "./assets/app-icon.png" + } +} diff --git a/plugins/atlassian-rovo/agents/openai.yaml b/plugins/atlassian-rovo/agents/openai.yaml new file mode 100644 index 00000000..2c5cd9f9 --- /dev/null +++ b/plugins/atlassian-rovo/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Atlassian Rovo" + short_description: "Manage Jira and Confluence fast" + icon_small: "./assets/app-icon.png" + icon_large: "./assets/app-icon.png" diff --git a/plugins/atlassian-rovo/assets/app-icon.png b/plugins/atlassian-rovo/assets/app-icon.png new file mode 100644 index 00000000..859036a6 Binary files /dev/null and b/plugins/atlassian-rovo/assets/app-icon.png differ diff --git a/plugins/atlassian-rovo/skills/capture-tasks-from-meeting-notes/SKILL.md b/plugins/atlassian-rovo/skills/capture-tasks-from-meeting-notes/SKILL.md new file mode 100644 index 00000000..9bd7560a --- /dev/null +++ b/plugins/atlassian-rovo/skills/capture-tasks-from-meeting-notes/SKILL.md @@ -0,0 +1,679 @@ +--- +name: capture-tasks-from-meeting-notes +description: "Analyze meeting notes to find action items and create Jira tasks for assigned work. When an agent needs to: (1) Create Jira tasks or tickets from meeting notes, (2) Extract or find action items from notes or Confluence pages, (3) Parse meeting notes for assigned tasks, or (4) Analyze notes and generate tasks for team members. Identifies assignees, looks up account IDs, and creates tasks with proper context." +--- + +# Capture Tasks from Meeting Notes + +## Keywords +meeting notes, action items, create tasks, create tickets, extract tasks, parse notes, analyze notes, assigned work, assignees, from meeting, post-meeting, capture tasks, generate tasks, turn into tasks, convert to tasks, action item, to-do, task list, follow-up, assigned to, create Jira tasks, create Jira tickets, meeting action items, extract action items, find action items, analyze meeting + +## Overview + +Automatically extract action items from meeting notes and create Jira tasks with proper assignees. This skill parses unstructured meeting notes (from Confluence or pasted text), identifies action items with assignees, looks up Jira account IDs, and creates tasks—eliminating the tedious post-meeting ticket creation process. + +**Use this skill when:** Users have meeting notes with action items that need to become Jira tasks. + +--- + +## Workflow + +Follow this 7-step process to turn meeting notes into actionable Jira tasks: + +### Step 1: Get Meeting Notes + +Obtain the meeting notes from the user. + +#### Option A: Confluence Page URL + +If user provides a Confluence URL: + +``` +getConfluencePage( + cloudId="...", + pageId="[extracted from URL]", + contentFormat="markdown" +) +``` + +**URL patterns:** +- `https://[site].atlassian.net/wiki/spaces/[SPACE]/pages/[PAGE_ID]/[title]` +- Extract PAGE_ID from the numeric portion +- Get cloudId from site name or use `getAccessibleAtlassianResources` + +#### Option B: Pasted Text + +If user pastes meeting notes directly: +- Use the text as-is +- No fetching needed + +#### If Unclear + +Ask: "Do you have a Confluence link to the meeting notes, or would you like to paste them directly?" + +--- + +### Step 2: Parse Action Items + +Scan the notes for action items with assignees. + +#### Common Patterns + +**Pattern 1: @mention format** (highest priority) +``` +@Sarah to create user stories for chat feature +@Mike will update architecture doc +``` + +**Pattern 2: Name + action verb** +``` +Sarah to create user stories +Mike will update architecture doc +Lisa should review the mockups +``` + +**Pattern 3: Action: Name - Task** +``` +Action: Sarah - create user stories +Action Item: Mike - update architecture +``` + +**Pattern 4: TODO with assignee** +``` +TODO: Create user stories (Sarah) +TODO: Update docs - Mike +``` + +**Pattern 5: Bullet with name** +``` +- Sarah: create user stories +- Mike - update architecture +``` + +#### Extraction Logic + +**For each action item, extract:** + +1. **Assignee Name** + - Text after @ symbol + - Name before "to", "will", "should" + - Name after "Action:" or in parentheses + - First/last name or full name + +2. **Task Description** + - Text after "to", "will", "should", "-", ":" + - Remove markers (@, Action:, TODO:) + - Keep original wording + - Include enough context + +3. **Context** (optional but helpful) + - Meeting title/date if available + - Surrounding discussion context + - Related decisions + +#### Example Parsing + +**Input:** +``` +# Product Planning - Dec 3 + +Action Items: +- @Sarah to create user stories for chat feature +- Mike will update the architecture doc +- Lisa: review and approve design mockups +``` + +**Parsed:** +``` +1. Assignee: Sarah + Task: Create user stories for chat feature + Context: Product Planning meeting - Dec 3 + +2. Assignee: Mike + Task: Update the architecture doc + Context: Product Planning meeting - Dec 3 + +3. Assignee: Lisa + Task: Review and approve design mockups + Context: Product Planning meeting - Dec 3 +``` + +--- + +### Step 3: Ask for Project Key + +Before looking up users or creating tasks, identify the Jira project. + +**Ask:** "Which Jira project should I create these tasks in? (e.g., PROJ, PRODUCT, ENG)" + +#### If User is Unsure + +Call `getVisibleJiraProjects` to show options: + +``` +getVisibleJiraProjects( + cloudId="...", + action="create" +) +``` + +Present: "I found these projects you can create tasks in: PROJ (Project Alpha), PRODUCT (Product Team), ENG (Engineering)" + +--- + +### Step 4: Lookup Account IDs + +For each assignee name, find their Jira account ID. + +#### Lookup Process + +``` +lookupJiraAccountId( + cloudId="...", + searchString="[assignee name]" +) +``` + +**The search string can be:** +- Full name: "Sarah Johnson" +- First name: "Sarah" +- Last name: "Johnson" +- Email: "sarah@company.com" + +#### Handle Results + +**Scenario A: Exact Match (1 result)** +``` +✅ Found: Sarah Johnson (sarah.johnson@company.com) +→ Use accountId from result +``` + +**Scenario B: No Match (0 results)** +``` +⚠️ Couldn't find user "Sarah" in Jira. + +Options: +1. Create task unassigned (assign manually later) +2. Skip this task +3. Try different name format (e.g., "Sarah Johnson") + +Which would you prefer? +``` + +**Scenario C: Multiple Matches (2+ results)** +``` +⚠️ Found multiple users named "Sarah": +1. Sarah Johnson (sarah.johnson@company.com) +2. Sarah Smith (sarah.smith@company.com) + +Which user should be assigned the task "Create user stories"? +``` + +#### Best Practices + +- Try full name first ("Sarah Johnson") +- If no match, try first name only ("Sarah") +- If still no match, ask user +- Cache results (don't lookup same person twice) + +--- + +### Step 5: Present Action Items + +**CRITICAL:** Always show the parsed action items to the user BEFORE creating any tasks. + +#### Presentation Format + +``` +I found [N] action items from the meeting notes. Should I create these Jira tasks in [PROJECT]? + +1. [TASK] [Task description] + Assigned to: [Name] ([email if found]) + Context: [Meeting title/date] + +2. [TASK] [Task description] + Assigned to: [Name] ([email if found]) + Context: [Meeting title/date] + +[...continue for all tasks...] + +Would you like me to: +1. Create all tasks +2. Skip some tasks (which ones?) +3. Modify any descriptions or assignees +``` + +#### Wait for Confirmation + +Do NOT create tasks until user confirms. Options: +- "Yes, create all" → proceed +- "Skip task 3" → create all except #3 +- "Change assignee for task 2" → ask for new assignee +- "Edit description" → ask for changes + +--- + +### Step 6: Create Tasks + +Once confirmed, create each Jira task. + +#### Determine Issue Type + +Before creating tasks, check what issue types are available in the project: + +``` +getJiraProjectIssueTypesMetadata( + cloudId="...", + projectIdOrKey="PROJ" +) +``` + +**Choose the appropriate issue type:** +- Use "Task" if available (most common) +- Use "Story" for user-facing features +- Use "Bug" if it's a defect +- If "Task" doesn't exist, use the first available issue type or ask the user + +#### For Each Action Item + +``` +createJiraIssue( + cloudId="...", + projectKey="PROJ", + issueTypeName="[Task or available type]", + summary="[Task description]", + description="[Full description with context]", + assignee_account_id="[looked up account ID]" +) +``` + +#### Task Summary Format + +Use action verbs and be specific: +- ✅ "Create user stories for chat feature" +- ✅ "Update architecture documentation" +- ✅ "Review and approve design mockups" +- ❌ "Do the thing" (too vague) + +#### Task Description Format + +```markdown +**Action Item from Meeting Notes** + +**Task:** [Original action item text] + +**Context:** +[Meeting title/date] +[Relevant discussion points or decisions] + +**Source:** [Link to Confluence meeting notes if available] + +**Original Note:** +> [Exact quote from meeting notes] +``` + +**Example:** +```markdown +**Action Item from Meeting Notes** + +**Task:** Create user stories for chat feature + +**Context:** +Product Planning Meeting - December 3, 2025 +Discussed Q1 roadmap priorities and new feature requirements + +**Source:** https://yoursite.atlassian.net/wiki/spaces/TEAM/pages/12345 + +**Original Note:** +> @Sarah to create user stories for chat feature +``` + +--- + +### Step 7: Provide Summary + +After all tasks are created, present a comprehensive summary. + +**Format:** +``` +✅ Created [N] tasks in [PROJECT]: + +1. [PROJ-123] - [Task summary] + Assigned to: [Name] + https://yoursite.atlassian.net/browse/PROJ-123 + +2. [PROJ-124] - [Task summary] + Assigned to: [Name] + https://yoursite.atlassian.net/browse/PROJ-124 + +[...continue for all created tasks...] + +**Source:** [Link to meeting notes] + +**Next Steps:** +- Review tasks in Jira for accuracy +- Add any additional details or attachments +- Adjust priorities if needed +- Link related tickets if applicable +``` + +--- + +## Action Item Pattern Examples + +### Pattern 1: @Mentions (Most Explicit) + +``` +@john to update documentation +@sarah will create the report +@mike should review PR #123 +``` + +**Parsed:** +- Assignee: john/sarah/mike +- Task: update documentation / create the report / review PR #123 + +--- + +### Pattern 2: Name + Action Verb + +``` +John to update documentation +Sarah will create the report +Mike should review PR #123 +Lisa needs to test the feature +``` + +**Parsed:** +- Assignee: name before action verb +- Task: text after "to/will/should/needs to" + +--- + +### Pattern 3: Structured Action Format + +``` +Action: John - update documentation +Action Item: Sarah - create the report +AI: Mike - review PR #123 +``` + +**Parsed:** +- Assignee: name after "Action:" and before "-" +- Task: text after "-" + +--- + +### Pattern 4: TODO Format + +``` +TODO: Update documentation (John) +TODO: Create report - Sarah +[ ] Mike: review PR #123 +``` + +**Parsed:** +- Assignee: name in parentheses or after ":" +- Task: text between TODO and assignee + +--- + +### Pattern 5: Bullet Lists + +``` +- John: update documentation +- Sarah - create the report +* Mike will review PR #123 +``` + +**Parsed:** +- Assignee: name before ":" or "-" or action verb +- Task: remaining text + +--- + +## Handling Edge Cases + +### No Action Items Found + +If no action items with assignees are detected: + +``` +I analyzed the meeting notes but couldn't find any action items with clear assignees. + +Action items typically follow patterns like: +- @Name to do X +- Name will do X +- Action: Name - do X +- TODO: X (Name) + +Options: +1. I can search for TODO items without assignees +2. You can point out specific action items to create +3. I can create tasks for bullet points you specify + +What would you like to do? +``` + +--- + +### Mixed Formats + +If some action items have assignees and some don't: + +``` +I found [N] action items: +- [X] with clear assignees +- [Y] without assignees + +Should I: +1. Create all [N] tasks ([X] assigned, [Y] unassigned) +2. Only create the [X] tasks with assignees +3. Ask you to assign the [Y] unassigned tasks + +Which option would you prefer? +``` + +--- + +### Assignee Name Variations + +If the same person is mentioned different ways: + +``` +Notes mention: @sarah, Sarah, Sarah J. + +These likely refer to the same person. I'll look up "Sarah" once and use +that account ID for all three mentions. Is that correct? +``` + +--- + +### Duplicate Action Items + +If the same task appears multiple times: + +``` +I found what appears to be the same action item twice: +1. "@Sarah to create user stories" (line 15) +2. "Action: Sarah - create user stories" (line 42) + +Should I: +1. Create one task (combine duplicates) +2. Create two separate tasks +3. Skip the duplicate + +What would you prefer? +``` + +--- + +### Long Task Descriptions + +If action item text is very long (>200 characters): + +``` +The task "[long text...]" is quite detailed. + +Should I: +1. Use first sentence as summary, rest in description +2. Use full text as summary +3. Let you edit it to be more concise + +Which would you prefer? +``` + +--- + +## Tips for High-Quality Results + +### Do: +✅ Use consistent @mention format in notes +✅ Include full names when possible +✅ Be specific in action item descriptions +✅ Add context (why/what/when) +✅ Review parsed tasks before confirming + +### Don't: +❌ Mix multiple tasks for one person in one bullet +❌ Use ambiguous names (just "John" if you have 5 Johns) +❌ Skip action verbs (unclear what to do) +❌ Forget to specify project + +### Best Meeting Notes Format + +``` +# Meeting Title - Date + +Attendees: [Names] + +## Decisions +[What was decided] + +## Action Items +- @FullName to [specific task with context] +- @AnotherPerson will [specific task with context] +- etc. +``` + +--- + +## When NOT to Use This Skill + +This skill is for **converting meeting action items to Jira tasks only**. + +**Don't use for:** +❌ Summarizing meetings (no task creation) +❌ Finding meeting notes (use search skill) +❌ Creating calendar events +❌ Sending meeting notes via email +❌ General note-taking + +**Use only when:** Meeting notes exist and action items need to become Jira tasks. + +--- + +## Examples + +### Example 1: Simple @Mentions + +**Input:** +``` +Team Sync - Dec 3, 2025 + +Action Items: +- @Sarah to create user stories for chat feature +- @Mike will update the architecture doc +- @Lisa should review design mockups +``` + +**Process:** +1. Parse → 3 action items found +2. Project → "PROJ" +3. Lookup → Sarah (123), Mike (456), Lisa (789) +4. Present → User confirms +5. Create → PROJ-100, PROJ-101, PROJ-102 + +**Output:** +``` +✅ Created 3 tasks in PROJ: + +1. PROJ-100 - Create user stories for chat feature + Assigned to: Sarah Johnson + +2. PROJ-101 - Update the architecture doc + Assigned to: Mike Chen + +3. PROJ-102 - Review design mockups + Assigned to: Lisa Park +``` + +--- + +### Example 2: Mixed Formats + +**Input:** +``` +Product Review Meeting + +Discussed new features and priorities. + +Follow-ups: +- Sarah will draft the PRD +- Mike: implement API changes +- TODO: Review security audit (Lisa) +- Update stakeholders on timeline +``` + +**Process:** +1. Parse → Found 4 items (3 with assignees, 1 without) +2. Ask → "Found 3 with assignees, 1 without. Create all or only assigned?" +3. User → "All, make the last one unassigned" +4. Create → 4 tasks (3 assigned, 1 unassigned) + +--- + +### Example 3: Name Lookup Issue + +**Input:** +``` +Sprint Planning + +Action Items: +- @John to update tests +- @Sarah to refactor code +``` + +**Process:** +1. Parse → 2 action items +2. Lookup "John" → Found 3 Johns! +3. Ask → "Which John? (John Smith, John Doe, John Wilson)" +4. User → "John Smith" +5. Create → Both tasks assigned correctly + +--- + +## Quick Reference + +**Primary tool:** `getConfluencePage` (if URL) or use pasted text +**Account lookup:** `lookupJiraAccountId(searchString)` +**Task creation:** `createJiraIssue` with `assignee_account_id` + +**Action patterns to look for:** +- `@Name to/will/should X` +- `Name to/will/should X` +- `Action: Name - X` +- `TODO: X (Name)` +- `Name: X` + +**Always:** +- Present parsed tasks before creating +- Handle name lookup failures gracefully +- Include context in task descriptions +- Provide summary with links + +**Remember:** +- Human-in-loop is critical (show before creating) +- Name lookup can fail (have fallback) +- Be flexible with pattern matching +- Context preservation is important diff --git a/plugins/atlassian-rovo/skills/capture-tasks-from-meeting-notes/agents/openai.yaml b/plugins/atlassian-rovo/skills/capture-tasks-from-meeting-notes/agents/openai.yaml new file mode 100644 index 00000000..d2c64433 --- /dev/null +++ b/plugins/atlassian-rovo/skills/capture-tasks-from-meeting-notes/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Capture Tasks From Meeting Notes" + short_description: "Extract action items and create Jira tasks" + icon_small: "./assets/app-icon.png" + icon_large: "./assets/app-icon.png" diff --git a/plugins/atlassian-rovo/skills/capture-tasks-from-meeting-notes/references/action-item-patterns.md b/plugins/atlassian-rovo/skills/capture-tasks-from-meeting-notes/references/action-item-patterns.md new file mode 100644 index 00000000..02cbaf08 --- /dev/null +++ b/plugins/atlassian-rovo/skills/capture-tasks-from-meeting-notes/references/action-item-patterns.md @@ -0,0 +1,445 @@ +# Action Item Patterns Reference + +Common patterns found in meeting notes and how to parse them. + +--- + +## Pattern Categories + +### Category 1: @Mentions (Highest Confidence) + +**Format:** `@Name [action verb] [task]` + +**Examples:** +``` +@john to update documentation +@sarah will create the report +@mike should review PR #123 +@lisa needs to test the feature +``` + +**Parsing:** +- Assignee: Text immediately after @ +- Task: Everything after action verb (to/will/should/needs to) +- Confidence: Very High (explicit assignment) + +--- + +### Category 2: Name + Action Verb (High Confidence) + +**Format:** `Name [action verb] [task]` + +**Examples:** +``` +John to update documentation +Sarah will create the report +Mike should review PR #123 +Lisa needs to test the feature +``` + +**Parsing:** +- Assignee: First word(s) before action verb +- Task: Everything after action verb +- Confidence: High (clear structure) + +**Action verbs to detect:** +- to, will, should, needs to, must, has to, is to, going to + +--- + +### Category 3: Structured Action Format (High Confidence) + +**Format:** `Action: Name - [task]` or `AI: Name - [task]` + +**Examples:** +``` +Action: John - update documentation +Action Item: Sarah - create the report +AI: Mike - review PR #123 +Task: Lisa - test the feature +``` + +**Parsing:** +- Assignee: Between "Action:" and "-" +- Task: After "-" +- Confidence: High (structured format) + +**Variants:** +- Action: +- Action Item: +- AI: +- Task: +- Assigned: + +--- + +### Category 4: TODO Format (Medium Confidence) + +**Format:** `TODO: [task] (Name)` or `TODO: [task] - Name` + +**Examples:** +``` +TODO: Update documentation (John) +TODO: Create report - Sarah +[ ] Review PR #123 (Mike) +- [ ] Test feature - Lisa +``` + +**Parsing:** +- Assignee: In parentheses or after "-" +- Task: Between TODO and assignee +- Confidence: Medium (format varies) + +**Markers to detect:** +- TODO: +- [ ] +- - [ ] +- To-do: +- Action item: + +--- + +### Category 5: Colon or Dash Format (Medium Confidence) + +**Format:** `Name: [task]` or `Name - [task]` + +**Examples:** +``` +John: update documentation +Sarah - create the report +Mike: review PR #123 +Lisa - test the feature +``` + +**Parsing:** +- Assignee: Before ":" or "-" +- Task: After ":" or "-" +- Confidence: Medium (could be other uses of colons/dashes) + +**Detection:** +- Look for name-like word before ":" or "-" +- Followed by action verb or imperative +- Usually in bulleted lists + +--- + +## Complex Patterns + +### Multiple Assignees + +**Format:** `Name1 and Name2 to [task]` + +**Examples:** +``` +John and Sarah to update documentation +Mike, Lisa to review PR +``` + +**Handling:** +- Create separate tasks for each person +- OR create one task, ask user who should be assigned +- Include both names in description + +--- + +### Conditional Actions + +**Format:** `Name to [task] if [condition]` + +**Examples:** +``` +John to update docs if approved +Sarah will create report pending review +``` + +**Handling:** +- Include condition in task description +- Note that it's conditional +- User can adjust later + +--- + +### Time-Bound Actions + +**Format:** `Name to [task] by [date]` + +**Examples:** +``` +John to update docs by EOD +Sarah will finish report by Friday +Mike to review before next meeting +``` + +**Handling:** +- Extract deadline and add to task description +- Could use due date field if available +- Include urgency in task + +--- + +## Anti-Patterns (Not Action Items) + +### Discussion Notes + +**Not an action item:** +``` +John mentioned the documentation needs updating +Sarah suggested we create a report +Mike talked about reviewing the code +``` + +**Why:** These are discussions, not assignments + +--- + +### General Statements + +**Not an action item:** +``` +Documentation needs to be updated +Someone should create a report +The code requires review +``` + +**Why:** No specific assignee + +--- + +### Past Actions + +**Not an action item:** +``` +John updated the documentation +Sarah created the report +Mike reviewed the code +``` + +**Why:** Already completed (past tense) + +--- + +## Context Extraction + +### Meeting Metadata + +**Look for:** +``` +# [Meeting Title] - [Date] +Meeting: [Title] +Date: [Date] +Subject: [Title] +``` + +**Extract:** +- Meeting title +- Date +- Attendees (if listed) + +--- + +### Related Information + +**Look for:** +``` +Related to: [project/epic/initiative] +Context: [background info] +Decision: [relevant decision] +``` + +**Include in task:** +- Links to related work +- Background context +- Relevant decisions + +--- + +## Name Extraction Tips + +### Full Names + +**Preferred:** +``` +@Sarah Johnson to create report +Sarah Johnson will create report +``` + +**Extract:** "Sarah Johnson" + +--- + +### First Name Only + +**Common:** +``` +@Sarah to create report +Sarah will create report +``` + +**Extract:** "Sarah" (will need to lookup) + +--- + +### Nicknames or Short Forms + +**Handle carefully:** +``` +@SJ to create report +Sara (no h) will create report +``` + +**Strategy:** Ask user or try multiple lookups + +--- + +## Priority Indicators + +### Urgent/High Priority + +**Detect:** +``` +URGENT: John to update docs +HIGH PRIORITY: Sarah to create report +ASAP: Mike to review code +``` + +**Handling:** +- Note priority in task description +- Could set priority field +- Highlight in presentation + +--- + +### Low Priority + +**Detect:** +``` +If time: John to update docs +Nice to have: Sarah create report +Eventually: Mike review code +``` + +**Handling:** +- Note as lower priority +- Could defer creation +- User can decide + +--- + +## Confidence Scoring + +When parsing, assign confidence: + +**High Confidence (90%+):** +- @Mentions with clear action +- "Name to do X" format +- "Action: Name - X" format + +**Medium Confidence (60-90%):** +- Name: task format +- TODO with name +- Name without action verb but clear task + +**Low Confidence (<60%):** +- Ambiguous wording +- No clear assignee +- Could be discussion not action + +**Handling:** +- Present all to user +- Flag low-confidence items +- Let user confirm or skip + +--- + +## Special Cases + +### Group Actions + +``` +Everyone to review the document +Team to provide feedback +``` + +**Handling:** +- Ask user who specifically +- OR create one task unassigned +- Note it's for the whole team + +--- + +### Optional Actions + +``` +Sarah could create a report if needed +Mike might review the code +``` + +**Handling:** +- Flag as optional +- Ask user if should create +- Include "optional" in description + +--- + +### Delegated Actions + +``` +John will ask Sarah to create the report +``` + +**Handling:** +- Assign to Sarah (the actual doer) +- Note John is requestor +- Include context + +--- + +## Testing Patterns + +Use these to validate pattern matching: + +``` +✅ @john to update tests +✅ Sarah will write docs +✅ Mike: review code +✅ TODO: Deploy (Lisa) +✅ Action: John - fix bug + +⚠️ Maybe John can help? +⚠️ Documentation needs work +⚠️ We should test this + +❌ John mentioned testing +❌ Tests were updated +❌ Someone needs to deploy +``` + +--- + +## Regular Expression Examples + +**@Mention pattern:** +```regex +@(\w+)\s+(to|will|should)\s+(.+) +``` + +**Name + action verb:** +```regex +([A-Z][\w\s]+?)\s+(to|will|should)\s+(.+) +``` + +**Action format:** +```regex +Action:\s*([A-Z][\w\s]+?)\s*-\s*(.+) +``` + +**TODO format:** +```regex +TODO:\s*(.+)\s*\((\w+)\) +``` + +**Note:** These patterns use `[A-Z][\w\s]+?` to match names flexibly: +- Starts with a capital letter +- Matches one or more word characters or spaces +- Non-greedy (`+?`) to stop at action verbs +- Handles single names ("Sarah"), two-part names ("Sarah Johnson"), and longer names ("Mary Jane Smith") diff --git a/plugins/atlassian-rovo/skills/generate-status-report/SKILL.md b/plugins/atlassian-rovo/skills/generate-status-report/SKILL.md new file mode 100644 index 00000000..b02e8b57 --- /dev/null +++ b/plugins/atlassian-rovo/skills/generate-status-report/SKILL.md @@ -0,0 +1,335 @@ +--- +name: generate-status-report +description: "Generate project status reports from Jira issues and publish to Confluence. When an agent needs to: (1) Create a status report for a project, (2) Summarize project progress or updates, (3) Generate weekly/daily reports from Jira, (4) Publish status summaries to Confluence, or (5) Analyze project blockers and completion. Queries Jira issues, categorizes by status/priority, and creates formatted reports for delivery managers and executives." +--- + +# Generate Status Report + +## Keywords +status report, project status, weekly update, daily standup, Jira report, project summary, blockers, progress update, Confluence report, sprint report, project update, publish to Confluence, write to Confluence, post report + +Automatically query Jira for project status, analyze issues, and generate formatted status reports published to Confluence. + +**CRITICAL**: This skill should be **interactive**. Always clarify scope (time period, audience, Confluence destination) with the user before or after generating the report. Do not silently skip Confluence publishing—always offer it. + +## Workflow + +Generating a status report follows these steps: + +1. **Identify scope** - Determine project, time period, and target audience +2. **Query Jira** - Fetch relevant issues using JQL queries +3. **Analyze data** - Categorize issues and identify key insights +4. **Format report** - Structure content based on audience and purpose +5. **Publish to Confluence** - Create or update a page with the report + +## Step 1: Identify Scope + +**IMPORTANT**: If the user's request is missing key information, ASK before proceeding with queries. Do not assume defaults without confirmation for Confluence publishing. + +Clarify these details: + +**Project identification:** +- Which Jira project key? (e.g., "PROJ", "ENG", "MKTG") +- If the user mentions a project by name but not key, search Jira to find the project key + +**Time period:** +- If not specified, ask: "What time period should this report cover? (default: last 7 days)" +- Options: Weekly (7 days), Daily (24 hours), Sprint-based (2 weeks), Custom period + +**Target audience:** +- If not specified, ask: "Who is this report for? (Executives/Delivery Managers, Team-level, or Daily standup)" +- **Executives/Delivery Managers**: High-level summary with key metrics and blockers +- **Team-level**: Detailed breakdown with issue-by-issue status +- **Daily standup**: Brief update on yesterday/today/blockers + +**Report destination:** +- **ALWAYS ASK** if not specified: "Would you like me to publish this report to Confluence? If so, which space should I use?" +- If user says yes: Ask for space name or offer to list available spaces +- Determine: New page or update existing page? +- Ask about parent page if creating under a specific section + +## Step 2: Query Jira + +Use the `searchJiraIssuesUsingJql` tool to fetch issues. Build JQL queries based on report needs. + +### Common Query Patterns + +For comprehensive queries, use the `scripts/jql_builder.py` utility to programmatically build JQL strings. For quick queries, reference `references/jql-patterns.md` for examples. + +**All open issues in project:** +```jql +project = "PROJECT_KEY" AND status != Done ORDER BY priority DESC, updated DESC +``` + +**Issues updated in last week:** +```jql +project = "PROJECT_KEY" AND updated >= -7d ORDER BY priority DESC +``` + +**High priority and blocked issues:** +```jql +project = "PROJECT_KEY" AND (priority IN (Highest, High) OR status = Blocked) AND status != Done ORDER BY priority DESC +``` + +**Completed in reporting period:** +```jql +project = "PROJECT_KEY" AND status = Done AND resolved >= -7d ORDER BY resolved DESC +``` + +### Query Strategy + +For most reports, execute multiple targeted queries rather than one large query: + +1. **Completed issues**: Get recently resolved tickets +2. **In-progress issues**: Get active work items +3. **Blocked issues**: Get blockers requiring attention +4. **High priority open**: Get critical upcoming work + +Use `maxResults: 100` for initial queries. If pagination is needed, use `nextPageToken` from results. + +### Data to Extract + +For each issue, capture: +- `key` (e.g., "PROJ-123") +- `summary` (issue title) +- `status` (current state) +- `priority` (importance level) +- `assignee` (who's working on it) +- `created` / `updated` / `resolved` dates +- `description` (if needed for context on blockers) + +## Step 3: Analyze Data + +Process the retrieved issues to identify: + +**Metrics:** +- Total issues by status (Done, In Progress, Blocked, etc.) +- Completion rate (if historical data available) +- Number of high priority items +- Unassigned issue count + +**Key insights:** +- Major accomplishments (recently completed high-value items) +- Critical blockers (blocked high priority issues) +- At-risk items (overdue or stuck in progress) +- Resource bottlenecks (one assignee with many issues) + +**Categorization:** +Group issues logically: +- By status (Done, In Progress, Blocked) +- By priority (Highest → Low) +- By assignee or team +- By component or epic (if relevant) + +## Step 4: Format Report + +Select the appropriate template based on audience. Templates are in `references/report-templates.md`. + +### For Executives and Delivery Managers + +Use **Executive Summary Format**: +- Brief overall status (🟢 On Track / 🟡 At Risk / 🔴 Blocked) +- Key metrics (total, completed, in progress, blocked) +- Top 3 highlights (major accomplishments) +- Critical blockers with impact +- Upcoming priorities + +**Keep it concise** - 1-2 pages maximum. Focus on what matters to decision-makers. + +### For Team-Level Reports + +Use **Detailed Technical Format**: +- Completed issues listed with keys +- In-progress issues with assignee and priority +- Blocked issues with blocker description and action needed +- Risks and dependencies +- Next period priorities + +**Include more detail** - Team needs issue-level visibility. + +### For Daily Updates + +Use **Daily Standup Format**: +- What was completed yesterday +- What's planned for today +- Current blockers +- Brief notes + +**Keep it brief** - This is a quick sync, not comprehensive analysis. + +## Step 5: Publish to Confluence + +**After generating the report, ALWAYS offer to publish to Confluence** (unless user explicitly said not to). + +If user hasn't specified Confluence details yet, ask: +- "Would you like me to publish this report to Confluence?" +- "Which Confluence space should I use?" +- "Should this be nested under a specific parent page?" + +Use the `createConfluencePage` tool to publish the report. + +**Page creation:** +``` +createConfluencePage( + cloudId="[obtained from getConfluenceSpaces or URL]", + spaceId="[numerical space ID]", + title="[Project Name] - Status Report - [Date]", + body="[formatted report in Markdown]", + contentFormat="markdown", + parentId="[optional - parent page ID if nesting under another page]" +) +``` + +**Title format examples:** +- "Project Phoenix - Weekly Status - Dec 3, 2025" +- "Engineering Sprint 23 - Status Report" +- "Q4 Initiatives - Status Update - Week 49" + +**Body formatting:** +Write the report content in Markdown. The tool will convert it to Confluence format. Use: +- Headers (`#`, `##`, `###`) for structure +- Bullet points for lists +- Bold (`**text**`) for emphasis +- Tables for metrics if needed +- Links to Jira issues: `[PROJ-123](https://yourinstance.atlassian.net/browse/PROJ-123)` + +**Best practices:** +- Include the report date prominently +- Link directly to relevant Jira issues +- Use consistent naming conventions for recurring reports +- Consider creating under a "Status Reports" parent page for organization + +### Finding the Right Space + +If the user doesn't specify a Confluence space: + +1. Use `getConfluenceSpaces` to list available spaces +2. Look for spaces related to the project (matching project name or key) +3. If unsure, ask the user which space to use +4. Default to creating in the most relevant team or project space + +### Updating Existing Reports + +If updating an existing page instead of creating new: + +1. Get the current page content: +``` +getConfluencePage( + cloudId="...", + pageId="123456", + contentFormat="markdown" +) +``` + +2. Update the page with new content: +``` +updateConfluencePage( + cloudId="...", + pageId="123456", + body="[updated report content]", + contentFormat="markdown", + versionMessage="Updated with latest status - Dec 8, 2025" +) +``` + +## Complete Example Workflow + +**User request:** "Generate a status report for Project Phoenix and publish it to Confluence" + +**Step 1 - Identify scope:** +- Project: Phoenix (need to find project key) +- Time period: Last week (default) +- Audience: Not specified, assume executive level +- Destination: Confluence, need to find appropriate space + +**Step 2 - Query Jira:** +```python +# Find project key first +searchJiraIssuesUsingJql( + cloudId="...", + jql='project = "PHOENIX" OR project = "PHX"', + maxResults=1 +) + +# Query completed issues +searchJiraIssuesUsingJql( + cloudId="...", + jql='project = "PHX" AND status = Done AND resolved >= -7d', + maxResults=50 +) + +# Query blocked issues +searchJiraIssuesUsingJql( + cloudId="...", + jql='project = "PHX" AND status = Blocked', + maxResults=50 +) + +# Query in-progress high priority +searchJiraIssuesUsingJql( + cloudId="...", + jql='project = "PHX" AND status IN ("In Progress", "In Review") AND priority IN (Highest, High)', + maxResults=50 +) +``` + +**Step 3 - Analyze:** +- 15 issues completed (metrics) +- 3 critical blockers (key insight) +- Major accomplishment: API integration completed (highlight) + +**Step 4 - Format:** +Use Executive Summary Format from templates. Create concise report with metrics, highlights, and blockers. + +**Step 5 - Publish:** +```python +# Find appropriate space +getConfluenceSpaces(cloudId="...") + +# Create page +createConfluencePage( + cloudId="...", + spaceId="12345", + title="Project Phoenix - Weekly Status - Dec 3, 2025", + body="[formatted markdown report]", + contentFormat="markdown" +) +``` + +## Tips for Quality Reports + +**Be data-driven:** +- Include specific numbers and metrics +- Reference issue keys directly +- Show trends when possible (e.g., "completed 15 vs 12 last week") + +**Highlight what matters:** +- Lead with the most important information +- Flag blockers prominently +- Celebrate significant wins + +**Make it actionable:** +- For blockers, state what action is needed and from whom +- For risks, provide mitigation options +- For priorities, be specific about next steps + +**Keep it consistent:** +- Use the same format for recurring reports +- Maintain predictable structure +- Include comparable metrics week-over-week + +**Provide context:** +- Link to Jira for details +- Explain the impact of blockers +- Connect work to business objectives when possible + +## Resources + +### scripts/jql_builder.py +Python utility for programmatically building JQL queries. Use this when you need to construct complex or dynamic queries. Import and use the helper functions rather than manually concatenating JQL strings. + +### references/jql-patterns.md +Quick reference of common JQL query patterns for status reports. Use this for standard queries or as a starting point for custom queries. + +### references/report-templates.md +Detailed templates for different report types and audiences. Reference this to select the appropriate format and structure for your report. diff --git a/plugins/atlassian-rovo/skills/generate-status-report/agents/openai.yaml b/plugins/atlassian-rovo/skills/generate-status-report/agents/openai.yaml new file mode 100644 index 00000000..f1fd6d54 --- /dev/null +++ b/plugins/atlassian-rovo/skills/generate-status-report/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Generate Status Report" + short_description: "Create project status reports from Jira" + icon_small: "./assets/app-icon.png" + icon_large: "./assets/app-icon.png" diff --git a/plugins/atlassian-rovo/skills/generate-status-report/references/jql-patterns.md b/plugins/atlassian-rovo/skills/generate-status-report/references/jql-patterns.md new file mode 100644 index 00000000..b71bb259 --- /dev/null +++ b/plugins/atlassian-rovo/skills/generate-status-report/references/jql-patterns.md @@ -0,0 +1,82 @@ +# JQL Query Patterns + +Common JQL patterns for status report generation. + +## Basic Project Queries + +**All open issues in a project:** +```jql +project = "PROJECT_KEY" AND status != Done +``` + +**Open issues by status:** +```jql +project = "PROJECT_KEY" AND status IN ("To Do", "In Progress", "In Review") +``` + +## Priority-Based Queries + +**High priority open issues:** +```jql +project = "PROJECT_KEY" AND status != Done AND priority IN ("Highest", "High") +``` + +**Blocked issues:** +```jql +project = "PROJECT_KEY" AND status = Blocked +``` + +## Time-Based Queries + +**Updated in last week:** +```jql +project = "PROJECT_KEY" AND updated >= -7d +``` + +**Completed in reporting period:** +```jql +project = "PROJECT_KEY" AND status = Done AND resolved >= -7d +``` + +**Created this sprint:** +```jql +project = "PROJECT_KEY" AND created >= -14d +``` + +## Assignee Queries + +**Unassigned issues:** +```jql +project = "PROJECT_KEY" AND assignee is EMPTY AND status != Done +``` + +**Issues by team member:** +```jql +project = "PROJECT_KEY" AND assignee = "user@example.com" AND status != Done +``` + +## Combined Queries for Reports + +**Current sprint overview:** +```jql +project = "PROJECT_KEY" AND status IN ("To Do", "In Progress", "In Review", "Done") AND updated >= -7d ORDER BY priority DESC, updated DESC +``` + +**Risk items (high priority blocked or overdue):** +```jql +project = "PROJECT_KEY" AND (status = Blocked OR (duedate < now() AND status != Done)) AND priority IN ("Highest", "High") ORDER BY priority DESC +``` + +## Epic and Component Queries + +**Issues by epic:** +```jql +parent = "EPIC_KEY" AND status != Done +``` + +Note: Older Jira instances may use `"Epic Link" = "EPIC_KEY"` instead of `parent`. + +**Issues by component:** +```jql +project = "PROJECT_KEY" AND component = "ComponentName" AND status != Done +``` diff --git a/plugins/atlassian-rovo/skills/generate-status-report/references/report-templates.md b/plugins/atlassian-rovo/skills/generate-status-report/references/report-templates.md new file mode 100644 index 00000000..d6b835c8 --- /dev/null +++ b/plugins/atlassian-rovo/skills/generate-status-report/references/report-templates.md @@ -0,0 +1,120 @@ +# Status Report Templates + +This file provides templates for different report formats based on audience and context. + +## Executive Summary Format + +For delivery managers and executives who need high-level overview: + +```markdown +# [Project Name] - Status Report +**Date:** [Date] +**Reporting Period:** [Period] + +## Executive Summary +[2-3 sentences summarizing overall status, major accomplishments, and critical blockers] + +## Overall Status +🟢 On Track | 🟡 At Risk | 🔴 Blocked | ⚪ Not Started + +## Key Metrics +- **Total Issues:** [number] +- **Completed This Period:** [number] +- **In Progress:** [number] +- **Blocked:** [number] + +## Highlights +- [Major accomplishment 1] +- [Major accomplishment 2] +- [Major accomplishment 3] + +## Critical Blockers +- **[Blocker Title]** - [Brief description and impact] +- **[Blocker Title]** - [Brief description and impact] + +## Upcoming Priorities +- [Priority 1] +- [Priority 2] +- [Priority 3] +``` + +## Detailed Technical Format + +For team-level reports with more technical detail: + +```markdown +# [Project Name] - Status Report +**Date:** [Date] +**Reporting Period:** [Period] + +## Summary +[Overall project status and key takeaways] + +## Progress This Period + +### Completed +- [Issue Key] - [Summary] +- [Issue Key] - [Summary] + +### In Progress +- [Issue Key] - [Summary] ([Assignee], [Priority]) +- [Issue Key] - [Summary] ([Assignee], [Priority]) + +### Blocked +- [Issue Key] - [Summary] + - **Blocker:** [Description of blocker] + - **Impact:** [How this affects timeline/deliverables] + - **Action Needed:** [What needs to happen to unblock] + +## Risks and Issues +- [Risk/Issue description with mitigation plan] + +## Next Period Priorities +- [Planned work item 1] +- [Planned work item 2] + +## Dependencies +- [External dependency description] +``` + +## Daily Standup Format + +For daily status updates: + +```markdown +# Daily Status - [Date] +**Project:** [Project Name] + +## Completed Yesterday +- [Issue Key] - [Brief summary] + +## Planned for Today +- [Issue Key] - [Brief summary] + +## Blockers +- [Blocker description] (Assigned to: [name]) + +## Notes +[Any additional context or observations] +``` + +## By Priority Breakdown + +For priority-focused reporting: + +```markdown +# [Project Name] - Status by Priority +**Date:** [Date] + +## Highest Priority (P0/Blocker) +- [Issue Key] - [Summary] - Status: [status] + +## High Priority (P1/Critical) +- [Issue Key] - [Summary] - Status: [status] + +## Medium Priority (P2/Major) +- [Issue Key] - [Summary] - Status: [status] + +## Low Priority (P3/Minor) +[Summary count only unless specifically requested] +``` diff --git a/plugins/atlassian-rovo/skills/generate-status-report/scripts/jql_builder.py b/plugins/atlassian-rovo/skills/generate-status-report/scripts/jql_builder.py new file mode 100644 index 00000000..4d0f56a6 --- /dev/null +++ b/plugins/atlassian-rovo/skills/generate-status-report/scripts/jql_builder.py @@ -0,0 +1,225 @@ +#!/usr/bin/env python3 +""" +JQL Query Builder Utility + +Helper functions for building common JQL queries for status reports. +""" + +from typing import List, Optional +import re + + +def sanitize_jql_value(value: str) -> str: + """ + Sanitize a value for use in JQL to prevent injection attacks. + + Args: + value: The input value to sanitize + + Returns: + Sanitized value safe for JQL queries + """ + if not value: + return value + + # Remove or escape potentially dangerous characters + # Allow alphanumeric, spaces, hyphens, underscores, dots, @ + safe_pattern = re.compile(r'^[a-zA-Z0-9\s\-_.@]+$') + + if not safe_pattern.match(value): + raise ValueError( + f"Invalid characters in input: '{value}'. " + f"Only alphanumeric characters, spaces, hyphens, underscores, dots, and @ are allowed." + ) + + # Escape double quotes by doubling them (JQL escaping) + return value.replace('"', '""') + + +def sanitize_jql_list(values: List[str]) -> List[str]: + """ + Sanitize a list of values for use in JQL. + + Args: + values: List of input values to sanitize + + Returns: + List of sanitized values + """ + return [sanitize_jql_value(v) for v in values] + + +def build_project_query( + project_key: str, + statuses: Optional[List[str]] = None, + exclude_done: bool = True, + priorities: Optional[List[str]] = None, + days_back: Optional[int] = None, + assignee: Optional[str] = None, + order_by: str = "priority DESC, updated DESC" +) -> str: + """ + Build a JQL query for project status. + + Args: + project_key: The Jira project key + statuses: List of statuses to include (e.g., ["To Do", "In Progress"]) + exclude_done: Whether to exclude Done status (default True) + priorities: List of priorities to include (e.g., ["Highest", "High"]) + days_back: Number of days to look back for updates (e.g., 7) + assignee: Specific assignee email or "EMPTY" for unassigned + order_by: JQL order by clause (default: "priority DESC, updated DESC") + + Returns: + JQL query string + """ + # Sanitize inputs to prevent JQL injection + project_key = sanitize_jql_value(project_key) + conditions = [f'project = "{project_key}"'] + + if statuses: + statuses = sanitize_jql_list(statuses) + status_list = '", "'.join(statuses) + conditions.append(f'status IN ("{status_list}")') + elif exclude_done: + conditions.append('status != Done') + + if priorities: + priorities = sanitize_jql_list(priorities) + priority_list = '", "'.join(priorities) + conditions.append(f'priority IN ("{priority_list}")') + + if days_back: + if not isinstance(days_back, int) or days_back < 0: + raise ValueError(f"days_back must be a non-negative integer, got: {days_back}") + conditions.append(f'updated >= -{days_back}d') + + if assignee: + if assignee.upper() == "EMPTY": + conditions.append('assignee is EMPTY') + else: + assignee = sanitize_jql_value(assignee) + conditions.append(f'assignee = "{assignee}"') + + query = " AND ".join(conditions) + + if order_by: + # Validate order_by contains only safe keywords + order_by = sanitize_jql_value(order_by) + query += f' ORDER BY {order_by}' + + return query + + +def build_blocked_query( + project_key: str, + high_priority_only: bool = False +) -> str: + """Build query for blocked issues.""" + project_key = sanitize_jql_value(project_key) + query = f'project = "{project_key}" AND status = Blocked' + + if high_priority_only: + query += ' AND priority IN (Highest, High)' + + query += ' ORDER BY priority DESC, created ASC' + return query + + +def build_completed_query( + project_key: str, + days_back: int = 7 +) -> str: + """Build query for recently completed issues.""" + project_key = sanitize_jql_value(project_key) + + if not isinstance(days_back, int) or days_back < 0: + raise ValueError(f"days_back must be a non-negative integer, got: {days_back}") + + return ( + f'project = "{project_key}" AND ' + f'status = Done AND ' + f'resolved >= -{days_back}d ' + f'ORDER BY resolved DESC' + ) + + +def build_in_progress_query( + project_key: str, + priorities: Optional[List[str]] = None +) -> str: + """Build query for in-progress issues.""" + project_key = sanitize_jql_value(project_key) + query = f'project = "{project_key}" AND status IN ("In Progress", "In Review")' + + if priorities: + priorities = sanitize_jql_list(priorities) + priority_list = '", "'.join(priorities) + query += f' AND priority IN ("{priority_list}")' + + query += ' ORDER BY priority DESC, updated DESC' + return query + + +def build_risk_query( + project_key: str, + include_overdue: bool = True +) -> str: + """Build query for risk items (blocked or overdue high priority).""" + project_key = sanitize_jql_value(project_key) + conditions = [f'project = "{project_key}"'] + + risk_conditions = ['status = Blocked'] + if include_overdue: + risk_conditions.append('(duedate < now() AND status != Done)') + + conditions.append(f'({" OR ".join(risk_conditions)})') + conditions.append('priority IN (Highest, High)') + + query = " AND ".join(conditions) + query += ' ORDER BY priority DESC, duedate ASC' + return query + + +def build_unassigned_query( + project_key: str, + exclude_done: bool = True +) -> str: + """Build query for unassigned issues.""" + project_key = sanitize_jql_value(project_key) + query = f'project = "{project_key}" AND assignee is EMPTY' + + if exclude_done: + query += ' AND status != Done' + + query += ' ORDER BY priority DESC, created ASC' + return query + + +# Example usage +if __name__ == "__main__": + # Example queries + project = "PROJ" + + print("Open Issues Query:") + print(build_project_query(project)) + print() + + print("High Priority In Progress:") + print(build_in_progress_query(project, priorities=["Highest", "High"])) + print() + + print("Blocked Issues:") + print(build_blocked_query(project, high_priority_only=True)) + print() + + print("Completed Last Week:") + print(build_completed_query(project, days_back=7)) + print() + + print("Risk Items:") + print(build_risk_query(project)) + print() + + print("Unassigned Open Issues:") + print(build_unassigned_query(project)) diff --git a/plugins/atlassian-rovo/skills/search-company-knowledge/SKILL.md b/plugins/atlassian-rovo/skills/search-company-knowledge/SKILL.md new file mode 100644 index 00000000..61f42ed0 --- /dev/null +++ b/plugins/atlassian-rovo/skills/search-company-knowledge/SKILL.md @@ -0,0 +1,575 @@ +--- +name: search-company-knowledge +description: "Search across company knowledge bases (Confluence, Jira, internal docs) to find and explain internal concepts, processes, and technical details. When an agent needs to: (1) Find or search for information about systems, terminology, processes, deployment, authentication, infrastructure, architecture, or technical concepts, (2) Search internal documentation, knowledge base, company docs, or our docs, (3) Explain what something is, how it works, or look up information, or (4) Synthesize information from multiple sources. Searches in parallel and provides cited answers." +--- + +# Search Company Knowledge + +## Keywords +find information, search company knowledge, look up, what is, explain, company docs, internal documentation, Confluence search, Jira search, our documentation, internal knowledge, knowledge base, search for, tell me about, get information about, company systems, terminology, find everything about, what do we know about, deployment, authentication, infrastructure, processes, procedures, how to, how does, our systems, our processes, internal systems, company processes, technical documentation, engineering docs, architecture, configuration, search our docs, search internal docs, find in our docs + +## Overview + +Search across siloed company knowledge systems (Confluence, Jira, internal documentation) to find comprehensive answers to questions about internal concepts, systems, and terminology. This skill performs parallel searches across multiple sources and synthesizes results with proper citations. + +**Use this skill when:** Users ask about internal company knowledge that might be documented in Confluence pages, Jira tickets, or internal documentation. + +--- + +## Workflow + +Follow this 5-step process to provide comprehensive, well-cited answers: + +### Step 1: Identify Search Query + +Extract the core search terms from the user's question. + +**Examples:** +- User: "Find everything about Stratus minions" → Search: "Stratus minions" +- User: "What do we know about the billing system?" → Search: "billing system" +- User: "Explain our deployment process" → Search: "deployment process" + +**Consider:** +- Main topic or concept +- Any specific system/component names +- Technical terms or jargon + +--- + +### Step 2: Execute Parallel Search + +Search across all available knowledge sources simultaneously for comprehensive coverage. + +#### Option A: Cross-System Search (Recommended First) + +Use the **`search`** tool (Rovo Search) to search across Confluence and Jira at once: + +``` +search( + cloudId="...", + query="[extracted search terms]" +) +``` + +**When to use:** +- Default approach for most queries +- When you don't know which system has the information +- Fastest way to get results from multiple sources + +**Example:** +``` +search( + cloudId="...", + query="Stratus minions" +) +``` + +This returns results from both Confluence pages and Jira issues. + +#### Option B: Targeted Confluence Search + +Use **`searchConfluenceUsingCql`** when specifically searching Confluence: + +``` +searchConfluenceUsingCql( + cloudId="...", + cql="text ~ 'search terms' OR title ~ 'search terms'" +) +``` + +**When to use:** +- User specifically mentions "in Confluence" or "in our docs" +- Cross-system search returns too many Jira results +- Looking for documentation rather than tickets + +**Example CQL patterns:** +``` +text ~ "Stratus minions" +text ~ "authentication" AND type = page +title ~ "deployment guide" +``` + +#### Option C: Targeted Jira Search + +Use **`searchJiraIssuesUsingJql`** when specifically searching Jira: + +``` +searchJiraIssuesUsingJql( + cloudId="...", + jql="text ~ 'search terms' OR summary ~ 'search terms'" +) +``` + +**When to use:** +- User mentions "tickets", "issues", or "bugs" +- Looking for historical problems or implementation details +- Cross-system search returns mostly documentation + +**Example JQL patterns:** +``` +text ~ "Stratus minions" +summary ~ "authentication" AND type = Bug +text ~ "deployment" AND created >= -90d +``` + +#### Search Strategy + +**For most queries, use this sequence:** + +1. Start with `search` (cross-system) - **always try this first** +2. If results are unclear, follow up with targeted searches +3. If results mention specific pages/tickets, fetch them for details + +--- + +### Step 3: Fetch Detailed Content + +After identifying relevant sources, fetch full content for comprehensive answers. + +#### For Confluence Pages + +When search results reference Confluence pages: + +``` +getConfluencePage( + cloudId="...", + pageId="[page ID from search results]", + contentFormat="markdown" +) +``` + +**Returns:** Full page content in Markdown format + +**When to fetch:** +- Search result snippet is too brief +- Need complete context +- Page seems to be the primary documentation + +#### For Jira Issues + +When search results reference Jira issues: + +``` +getJiraIssue( + cloudId="...", + issueIdOrKey="PROJ-123" +) +``` + +**Returns:** Full issue details including description, comments, status + +**When to fetch:** +- Need to understand a reported bug or issue +- Search result doesn't show full context +- Issue contains important implementation notes + +#### Prioritization + +**Fetch in this order:** +1. **Official documentation pages** (Confluence pages with "guide", "documentation", "overview" in title) +2. **Recent/relevant issues** (Jira tickets that are relevant and recent) +3. **Additional context** (related pages mentioned in initial results) + +**Don't fetch everything** - be selective based on relevance to user's question. + +--- + +### Step 4: Synthesize Results + +Combine information from multiple sources into a coherent answer. + +#### Synthesis Guidelines + +**Structure your answer:** + +1. **Direct Answer First** + - Start with a clear, concise answer to the question + - "Stratus minions are..." + +2. **Detailed Explanation** + - Provide comprehensive details from all sources + - Organize by topic, not by source + +3. **Source Attribution** + - Note where each piece of information comes from + - Format: "According to [source], ..." + +4. **Highlight Discrepancies** + - If sources conflict, note it explicitly + - Example: "The Confluence documentation states X, however Jira ticket PROJ-123 indicates that due to bug Y, the behavior is actually Z" + +5. **Provide Context** + - Mention if information is outdated + - Note if a feature is deprecated or in development + +#### Synthesis Patterns + +**Pattern 1: Multiple sources agree** +``` +Stratus minions are background worker processes that handle async tasks. + +According to the Confluence documentation, they process jobs from the queue and +can be scaled horizontally. This is confirmed by several Jira tickets (PROJ-145, +PROJ-203) which discuss minion configuration and scaling strategies. +``` + +**Pattern 2: Sources provide different aspects** +``` +The billing system has two main components: + +**Payment Processing** (from Confluence "Billing Architecture" page) +- Handles credit card transactions +- Integrates with Stripe API +- Runs nightly reconciliation + +**Invoice Generation** (from Jira PROJ-189) +- Creates monthly invoices +- Note: Currently has a bug where tax calculation fails for EU customers +- Fix planned for Q1 2024 +``` + +**Pattern 3: Conflicting information** +``` +There is conflicting information about the authentication timeout: + +- **Official Documentation** (Confluence) states: 30-minute session timeout +- **Implementation Reality** (Jira PROJ-456, filed Oct 2023): Actual timeout is + 15 minutes due to load balancer configuration +- **Status:** Engineering team aware, fix planned but no timeline yet + +Current behavior: Expect 15-minute timeout despite docs saying 30 minutes. +``` + +**Pattern 4: Incomplete information** +``` +Based on available documentation: + +[What we know about deployment process from Confluence and Jira] + +However, I couldn't find information about: +- Rollback procedures +- Database migration handling + +You may want to check with the DevOps team or search for additional documentation. +``` + +--- + +### Step 5: Provide Citations + +Always include links to source materials so users can explore further. + +#### Citation Format + +**For Confluence pages:** +``` +**Source:** [Page Title](https://yoursite.atlassian.net/wiki/spaces/SPACE/pages/123456) +``` + +**For Jira issues:** +``` +**Related Tickets:** +- [PROJ-123](https://yoursite.atlassian.net/browse/PROJ-123) - Brief description +- [PROJ-456](https://yoursite.atlassian.net/browse/PROJ-456) - Brief description +``` + +**Complete citation section:** +``` +## Sources + +**Confluence Documentation:** +- [Stratus Architecture Guide](https://yoursite.atlassian.net/wiki/spaces/DOCS/pages/12345) +- [Minion Configuration](https://yoursite.atlassian.net/wiki/spaces/DEVOPS/pages/67890) + +**Jira Issues:** +- [PROJ-145](https://yoursite.atlassian.net/browse/PROJ-145) - Minion scaling implementation +- [PROJ-203](https://yoursite.atlassian.net/browse/PROJ-203) - Performance optimization + +**Additional Resources:** +- [Internal architecture doc link if found] +``` + +--- + +## Search Best Practices + +### Effective Search Terms + +**Do:** +- ✅ Use specific technical terms: "OAuth authentication flow" +- ✅ Include system names: "Stratus minions" +- ✅ Use acronyms if they're common: "API rate limiting" +- ✅ Try variations if first search fails: "deploy process" → "deployment pipeline" + +**Don't:** +- ❌ Be too generic: "how things work" +- ❌ Use full sentences: Use key terms instead +- ❌ Include filler words: "the", "our", "about" + +### Search Result Quality + +**Good results:** +- Recent documentation (< 1 year old) +- Official/canonical pages (titled "Guide", "Documentation", "Overview") +- Multiple sources confirming same information +- Detailed implementation notes + +**Questionable results:** +- Very old tickets (> 2 years, may be outdated) +- Duplicate or conflicting information +- Draft pages or work-in-progress docs +- Personal pages (may not be official) + +**When results are poor:** +- Try different search terms +- Expand search to include related concepts +- Search for specific error messages or codes +- Ask user for more context + +--- + +## Handling Common Scenarios + +### Scenario 1: No Results Found + +If searches return no results: + +``` +I searched across Confluence and Jira but couldn't find information about "[topic]". + +This could mean: +- The concept hasn't been documented yet +- It might be called something else (can you provide alternative names?) +- Documentation might be in a different system I don't have access to + +Would you like me to: +1. Try searching with different terms? +2. Search for related concepts? +3. Look for mentions in recent Jira tickets? +``` + +### Scenario 2: Too Many Results + +If search returns 50+ results: + +- Focus on most recent and most relevant (top 10-15) +- Prioritize official documentation over random tickets +- Group similar results: "I found 15 tickets related to authentication bugs..." +- Offer to narrow search: "Would you like me to focus on [specific aspect]?" + +### Scenario 3: Ambiguous Query + +If the user's question is vague: + +``` +I found information about several topics related to "[term]": +1. [Topic A] - from Confluence page X +2. [Topic B] - from Jira tickets Y, Z +3. [Topic C] - from documentation W + +Which aspect are you most interested in? +``` + +### Scenario 4: Outdated Information + +If you find information is old: + +``` +I found documentation about [topic], but note that it's from [date] and may be outdated. + +[Provide the information anyway] + +You may want to verify this is still current, especially if it's from more than +a year ago. +``` + +### Scenario 5: Restricted/Private Content + +If search returns inaccessible content: + +``` +Search results mention [topic] in the following locations, but I don't have +access to view the full content: +- Confluence page: [title] (Space: [SPACE]) +- Jira issue: PROJ-123 + +You may need to access these directly or check your permissions. +``` + +--- + +## Examples + +### Example 1: Clear Documentation Available + +**User:** "What are Stratus minions?" + +**Process:** +1. Search: `search(cloudId="...", query="Stratus minions")` +2. Find: Confluence page "Stratus Architecture" + 3 Jira tickets +3. Fetch: Get full Confluence page content +4. Synthesize: Combine architectural overview with implementation details from tickets +5. Cite: Provide links to all sources + +**Answer:** +``` +Stratus minions are background worker processes that handle asynchronous task +processing in the Stratus system. + +**Key Characteristics:** +- Run independently from web servers +- Process jobs from a Redis queue +- Can be scaled horizontally for increased throughput +- Handle tasks like email sending, report generation, and data processing + +**Architecture:** +According to the Stratus Architecture documentation, minions follow a +worker-queue pattern where: +1. Web application enqueues tasks +2. Minions poll the queue for work +3. Tasks are processed asynchronously +4. Results are stored in the database + +**Implementation Notes:** +From Jira ticket PROJ-203, the current deployment runs 5 minion instances, +with plans to scale to 10 for handling increased load. + +## Sources +- [Stratus Architecture Guide](link) +- [PROJ-203](link) - Minion scaling implementation +``` + +### Example 2: Conflicting Information + +**User:** "How long is our session timeout?" + +**Process:** +1. Search across Confluence and Jira +2. Find: Docs say 30 min, but ticket reports actual timeout is 15 min +3. Fetch both sources for complete context +4. Clearly note the discrepancy + +**Answer:** +``` +There is a discrepancy between documented and actual behavior: + +**Official Documentation** (Security Guidelines): +Session timeout is configured for 30 minutes of inactivity. + +**Actual Behavior** (PROJ-456, reported Oct 2023): +Users are being logged out after 15 minutes due to a load balancer configuration +that overrides the application setting. + +**Current Status:** +The engineering team is aware of this issue. The load balancer timeout needs to +be adjusted to match the application setting. No fix timeline has been set. + +**Recommendation:** Plan for 15-minute timeout until this is resolved. + +## Sources +- [Security Guidelines](link) - Official documentation +- [PROJ-456](link) - Timeout discrepancy bug report +``` + +### Example 3: Partial Information + +**User:** "Explain our deployment process" + +**Process:** +1. Search finds some information but not complete +2. Synthesize what is available +3. Note gaps in documentation + +**Answer:** +``` +Based on available documentation, here's what I found about the deployment process: + +**Build Phase** (from Confluence "CI/CD Guide"): +1. Code pushed to main branch triggers GitHub Actions +2. Automated tests run (unit, integration) +3. Docker image built and pushed to registry + +**Deployment Phase** (from Jira PROJ-789): +4. Staging deployment happens automatically +5. Manual approval required for production +6. Blue-green deployment strategy used + +**Gaps in Documentation:** +I couldn't find documented information about: +- Rollback procedures +- Database migration handling +- Post-deployment verification steps + +These details may exist in tribal knowledge or need to be documented. + +## Sources +- [CI/CD Guide](link) +- [PROJ-789](link) - Deployment pipeline implementation + +Would you like me to search for more specific aspects of deployment? +``` + +--- + +## Tips for High-Quality Answers + +### Do: +✅ Always search before answering (don't rely on general knowledge) +✅ Cite all sources with links +✅ Note discrepancies explicitly +✅ Mention when information is old +✅ Provide context and examples +✅ Structure answers clearly with headers +✅ Link to related documentation + +### Don't: +❌ Assume general knowledge applies to this company +❌ Make up information if search returns nothing +❌ Ignore conflicting information +❌ Quote entire documents (summarize instead) +❌ Overwhelm with too many sources (curate top 5-10) +❌ Forget to fetch details when snippets are insufficient + +--- + +## When NOT to Use This Skill + +This skill is for **internal company knowledge only**. Do NOT use for: + +❌ General technology questions (use your training knowledge) +❌ External documentation (use web_search) +❌ Company-agnostic questions +❌ Questions about other companies +❌ Current events or news + +**Examples of what NOT to use this skill for:** +- "What is machine learning?" (general knowledge) +- "How does React work?" (external documentation) +- "What's the weather?" (not knowledge search) +- "Find a restaurant" (not work-related) + +--- + +## Quick Reference + +**Primary tool:** `search(cloudId, query)` - Use this first, always + +**Follow-up tools:** +- `getConfluencePage(cloudId, pageId, contentFormat)` - Get full page content +- `getJiraIssue(cloudId, issueIdOrKey)` - Get full issue details +- `searchConfluenceUsingCql(cloudId, cql)` - Targeted Confluence search +- `searchJiraIssuesUsingJql(cloudId, jql)` - Targeted Jira search + +**Answer structure:** +1. Direct answer +2. Detailed explanation +3. Source attribution +4. Discrepancies (if any) +5. Citations with links + +**Remember:** +- Parallel search > Sequential search +- Synthesize, don't just list +- Always cite sources +- Note conflicts explicitly +- Be clear about gaps in documentation diff --git a/plugins/atlassian-rovo/skills/search-company-knowledge/agents/openai.yaml b/plugins/atlassian-rovo/skills/search-company-knowledge/agents/openai.yaml new file mode 100644 index 00000000..89c52200 --- /dev/null +++ b/plugins/atlassian-rovo/skills/search-company-knowledge/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Search Company Knowledge" + short_description: "Search Confluence, Jira, and internal Atlassian context" + icon_small: "./assets/app-icon.png" + icon_large: "./assets/app-icon.png" diff --git a/plugins/atlassian-rovo/skills/spec-to-backlog/SKILL.md b/plugins/atlassian-rovo/skills/spec-to-backlog/SKILL.md new file mode 100644 index 00000000..fc9f5623 --- /dev/null +++ b/plugins/atlassian-rovo/skills/spec-to-backlog/SKILL.md @@ -0,0 +1,543 @@ +--- +name: spec-to-backlog +description: "Automatically convert Confluence specification documents into structured Jira backlogs with Epics and implementation tickets. When an agent needs to: (1) Create Jira tickets from a Confluence page, (2) Generate a backlog from a specification, (3) Break down a spec into implementation tasks, or (4) Convert requirements into Jira issues. Handles reading Confluence pages, analyzing specifications, creating Epics with proper structure, and generating detailed implementation tickets linked to the Epic." +--- + +# Spec to Backlog + +## Overview + +Transform Confluence specification documents into structured Jira backlogs automatically. This skill reads requirement documents from Confluence, intelligently breaks them down into logical implementation tasks, **creates an Epic first** to organize the work, then generates individual Jira tickets linked to that Epic—eliminating tedious manual copy-pasting. + +## Core Workflow + +**CRITICAL: Always follow this exact sequence:** + +1. **Fetch Confluence Page** → Get the specification content +2. **Ask for Project Key** → Identify target Jira project +3. **Analyze Specification** → Break down into logical tasks (internally, don't create yet) +4. **Present Breakdown** → Show user the planned Epic and tickets +5. **Create Epic FIRST** → Establish parent Epic and capture its key +6. **Create Child Tickets** → Generate tickets linked to the Epic +7. **Provide Summary** → Present all created items with links + +**Why Epic must be created first:** Child tickets need the Epic key to link properly during creation. Creating tickets first will result in orphaned tickets. + +--- + +## Step 1: Fetch Confluence Page + +When triggered, obtain the Confluence page content: + +### If user provides a Confluence URL: + +Extract the cloud ID and page ID from the URL pattern: +- Standard format: `https://[site].atlassian.net/wiki/spaces/[SPACE]/pages/[PAGE_ID]/[title]` +- The cloud ID can be extracted from `[site].atlassian.net` or by calling `getAccessibleAtlassianResources` +- The page ID is the numeric value in the URL path + +### If user provides only a page title or description: + +Use the `search` tool to find the page: +``` +search( + cloudId="...", + query="type=page AND title~'[search terms]'" +) +``` + +If multiple pages match, ask the user to clarify which one to use. + +### Fetch the page: + +Call `getConfluencePage` with the cloudId and pageId: +``` +getConfluencePage( + cloudId="...", + pageId="123456", + contentFormat="markdown" +) +``` + +This returns the page content in Markdown format, which you'll analyze in Step 3. + +--- + +## Step 2: Ask for Project Key + +**Before analyzing the spec**, determine the target Jira project: + +### Ask the user: +"Which Jira project should I create these tickets in? Please provide the project key (e.g., PROJ, ENG, PRODUCT)." + +### If user is unsure: +Call `getVisibleJiraProjects` to show available projects: +``` +getVisibleJiraProjects( + cloudId="...", + action="create" +) +``` + +Present the list: "I found these projects you can create issues in: PROJ (Project Alpha), ENG (Engineering), PRODUCT (Product Team)." + +### Once you have the project key: +Call `getJiraProjectIssueTypesMetadata` to understand what issue types are available: +``` +getJiraProjectIssueTypesMetadata( + cloudId="...", + projectIdOrKey="PROJ" +) +``` + +**Identify available issue types:** +- Which issue type is "Epic" (or similar parent type like "Initiative") +- What child issue types are available: "Story", "Task", "Bug", "Sub-task", etc. + +**Select appropriate issue types for child tickets:** + +The skill should intelligently choose issue types based on the specification content: + +**Use "Bug" when the spec describes:** +- Fixing existing problems or defects +- Resolving errors or incorrect behavior +- Addressing performance issues +- Correcting data inconsistencies +- Keywords: "fix", "resolve", "bug", "issue", "problem", "error", "broken" + +**Use "Story" when the spec describes:** +- New user-facing features or functionality +- User experience improvements +- Customer-requested capabilities +- Product enhancements +- Keywords: "feature", "user can", "add ability to", "new", "enable users" + +**Use "Task" when the spec describes:** +- Technical work without direct user impact +- Infrastructure or DevOps work +- Refactoring or optimization +- Documentation or tooling +- Configuration or setup +- Keywords: "implement", "setup", "configure", "optimize", "refactor", "infrastructure" + +**Fallback logic:** +1. If "Story" is available and content suggests new features → use "Story" +2. If "Bug" is available and content suggests fixes → use "Bug" +3. If "Task" is available → use "Task" for technical work +4. If none of the above are available → use the first available non-Epic, non-Subtask issue type + +**Store the selected issue types for use in Step 6:** +- Epic issue type name (e.g., "Epic") +- Default child issue type (e.g., "Story" or "Task") +- Bug issue type name if available (e.g., "Bug") + +--- + +## Step 3: Analyze Specification + +Read the Confluence page content and **internally** decompose it into: + +### Epic-Level Goal +What is the overall objective or feature being implemented? This becomes your Epic. + +**Example Epic summaries:** +- "User Authentication System" +- "Payment Gateway Integration" +- "Dashboard Performance Optimization" +- "Mobile App Notifications Feature" + +### Implementation Tasks +Break the work into logical, independently implementable tasks. + +**Breakdown principles:** +- **Size:** 3-10 tasks per spec typically (avoid over-granularity) +- **Clarity:** Each task should be specific and actionable +- **Independence:** Tasks can be worked on separately when possible +- **Completeness:** Include backend, frontend, testing, documentation, infrastructure as needed +- **Grouping:** Related functionality stays in the same ticket + +**Consider these dimensions:** +- Technical layers: Backend API, Frontend UI, Database, Infrastructure +- Work types: Implementation, Testing, Documentation, Deployment +- Features: Break complex features into sub-features +- Dependencies: Identify prerequisite work + +**Common task patterns:** +- "Design [component] database schema" +- "Implement [feature] API endpoints" +- "Build [component] UI components" +- "Add [integration] to existing [system]" +- "Write tests for [feature]" +- "Update documentation for [feature]" + +**Use action verbs:** +- Implement, Create, Build, Add, Design, Integrate, Update, Fix, Optimize, Configure, Deploy, Test, Document + +--- + +## Step 4: Present Breakdown to User + +**Before creating anything**, show the user your planned breakdown: + +**Format:** +``` +I've analyzed the spec and here's the backlog I'll create: + +**Epic:** [Epic Summary] +[Brief description of epic scope] + +**Implementation Tickets (7):** +1. [Story] [Task 1 Summary] +2. [Task] [Task 2 Summary] +3. [Story] [Task 3 Summary] +4. [Bug] [Task 4 Summary] +5. [Task] [Task 5 Summary] +6. [Story] [Task 6 Summary] +7. [Task] [Task 7 Summary] + +Shall I create these tickets in [PROJECT KEY]? +``` + +**The issue type labels show what type each ticket will be created as:** +- [Story] - New user-facing feature +- [Task] - Technical implementation work +- [Bug] - Fix or resolve an issue + +**Wait for user confirmation** before proceeding. This allows them to: +- Request changes to the breakdown +- Confirm the scope is correct +- Adjust the number or focus of tickets + +If user requests changes, adjust the breakdown and re-present. + +--- + +## Step 5: Create Epic FIRST + +**CRITICAL:** The Epic must be created before any child tickets. + +### Create the Epic: + +Call `createJiraIssue` with: + +``` +createJiraIssue( + cloudId="...", + projectKey="PROJ", + issueTypeName="Epic", + summary="[Epic Summary from Step 3]", + description="[Epic Description - see below]" +) +``` + +### Epic Description Structure: + +```markdown +## Overview +[1-2 sentence summary of what this epic delivers] + +## Source +Confluence Spec: [Link to Confluence page] + +## Objectives +- [Key objective 1] +- [Key objective 2] +- [Key objective 3] + +## Scope +[Brief description of what's included and what's not] + +## Success Criteria +- [Measurable criterion 1] +- [Measurable criterion 2] +- [Measurable criterion 3] + +## Technical Notes +[Any important technical context from the spec] +``` + +### Capture the Epic Key: + +The response will include the Epic's key (e.g., "PROJ-123"). **Save this key**—you'll need it for every child ticket. + +**Example response:** +```json +{ + "key": "PROJ-123", + "id": "10001", + "self": "https://yoursite.atlassian.net/rest/api/3/issue/10001" +} +``` + +**Confirm Epic creation to user:** +"✅ Created Epic: PROJ-123 - User Authentication System" + +--- + +## Step 6: Create Child Tickets + +Now create each implementation task as a child ticket linked to the Epic. + +### For each task: + +**Determine the appropriate issue type for this specific task:** +- If the task involves fixing/resolving an issue → use "Bug" (if available) +- If the task involves new user-facing features → use "Story" (if available) +- If the task involves technical/infrastructure work → use "Task" (if available) +- Otherwise → use the default child issue type from Step 2 + +Call `createJiraIssue` with: + +``` +createJiraIssue( + cloudId="...", + projectKey="PROJ", + issueTypeName="[Story/Task/Bug based on task content]", + summary="[Task Summary]", + description="[Task Description - see below]", + parent="PROJ-123" # The Epic key from Step 5 +) +``` + +**Example issue type selection:** +- "Fix authentication timeout bug" → Use "Bug" +- "Build user dashboard UI" → Use "Story" +- "Configure CI/CD pipeline" → Use "Task" +- "Implement password reset API" → Use "Story" (new user feature) + +### Task Summary Format: + +Use action verbs and be specific: +- ✅ "Implement user registration API endpoint" +- ✅ "Design authentication database schema" +- ✅ "Build login form UI components" +- ❌ "Do backend work" (too vague) +- ❌ "Frontend" (not actionable) + +### Task Description Structure: + +```markdown +## Context +[Brief context for this task from the Confluence spec] + +## Requirements +- [Requirement 1] +- [Requirement 2] +- [Requirement 3] + +## Technical Details +[Specific technical information relevant to this task] +- Technologies: [e.g., Node.js, React, PostgreSQL] +- Components: [e.g., API routes, database tables, UI components] +- Dependencies: [e.g., requires PROJ-124 to be completed first] + +## Acceptance Criteria +- [ ] [Testable criterion 1] +- [ ] [Testable criterion 2] +- [ ] [Testable criterion 3] + +## Related +- Confluence Spec: [Link to relevant section if possible] +- Epic: PROJ-123 +``` + +### Acceptance Criteria Best Practices: + +Make them **testable** and **specific**: +- ✅ "API returns 201 status on successful user creation" +- ✅ "Password must be at least 8 characters and hashed with bcrypt" +- ✅ "Login form validates email format before submission" +- ❌ "User can log in" (too vague) +- ❌ "It works correctly" (not testable) + +### Create all tickets sequentially: + +Track each created ticket key for the summary. + +--- + +## Step 7: Provide Summary + +After all tickets are created, present a comprehensive summary: + +``` +✅ Backlog created successfully! + +**Epic:** PROJ-123 - User Authentication System +https://yoursite.atlassian.net/browse/PROJ-123 + +**Implementation Tickets (7):** + +1. PROJ-124 - Design authentication database schema + https://yoursite.atlassian.net/browse/PROJ-124 + +2. PROJ-125 - Implement user registration API endpoint + https://yoursite.atlassian.net/browse/PROJ-125 + +3. PROJ-126 - Implement user login API endpoint + https://yoursite.atlassian.net/browse/PROJ-126 + +4. PROJ-127 - Build login form UI components + https://yoursite.atlassian.net/browse/PROJ-127 + +5. PROJ-128 - Build registration form UI components + https://yoursite.atlassian.net/browse/PROJ-128 + +6. PROJ-129 - Add authentication integration to existing features + https://yoursite.atlassian.net/browse/PROJ-129 + +7. PROJ-130 - Write authentication tests and documentation + https://yoursite.atlassian.net/browse/PROJ-130 + +**Source:** https://yoursite.atlassian.net/wiki/spaces/SPECS/pages/123456 + +**Next Steps:** +- Review tickets in Jira for accuracy and completeness +- Assign tickets to team members +- Estimate story points if your team uses them +- Add any additional labels or custom field values +- Schedule work for the upcoming sprint +``` + +--- + +## Edge Cases & Troubleshooting + +### Multiple Specs or Pages + +**If user references multiple Confluence pages:** +- Process each separately, or ask which to prioritize +- Consider creating separate Epics for distinct features +- "I see you've provided 3 spec pages. Should I create separate Epics for each, or would you like me to focus on one first?" + +### Existing Epic + +**If user wants to add tickets to an existing Epic:** +- Skip Epic creation (Step 5) +- Ask for the existing Epic key: "What's the Epic key you'd like to add tickets to? (e.g., PROJ-100)" +- Proceed with Step 6 using the provided Epic key + +### Custom Required Fields + +**If ticket creation fails due to required fields:** +1. Use `getJiraIssueTypeMetaWithFields` to identify what fields are required: + ``` + getJiraIssueTypeMetaWithFields( + cloudId="...", + projectIdOrKey="PROJ", + issueTypeId="10001" + ) + ``` + +2. Ask user for values: "This project requires a 'Priority' field. What priority should I use? (e.g., High, Medium, Low)" + +3. Include in `additional_fields` when creating: + ``` + additional_fields={ + "priority": {"name": "High"} + } + ``` + +### Large Specifications + +**For specs that would generate 15+ tickets:** +- Present the full breakdown to user +- Ask: "This spec would create 18 tickets. Should I create all of them, or would you like to adjust the scope?" +- Offer to create a subset first: "I can create the first 10 tickets now and wait for your feedback before creating the rest." + +### Subtasks vs Tasks + +**Some projects use "Subtask" issue types:** +- If metadata shows "Subtask" is available, you can use it for more granular work +- Subtasks link to parent tasks (not Epics directly) +- Structure: Epic → Task → Subtasks + +### Ambiguous Specifications + +**If the Confluence page lacks detail:** +- Create fewer, broader tickets +- Note in ticket descriptions: "Detailed requirements need to be defined during refinement" +- Ask user: "The spec is light on implementation details. Should I create high-level tickets that can be refined later?" + +### Failed API Calls + +**If `createJiraIssue` fails:** +1. Check the error message for specific issues (permissions, required fields, invalid values) +2. Use `getJiraProjectIssueTypesMetadata` to verify issue type availability +3. Inform user: "I encountered an error creating tickets: [error message]. This might be due to project permissions or required fields." + +--- + +## Tips for High-Quality Breakdowns + +### Be Specific +- ❌ "Do frontend work" +- ✅ "Create login form UI with email/password inputs and validation" + +### Include Technical Context +- Mention specific technologies when clear from spec +- Reference components, services, or modules +- Note integration points + +### Logical Grouping +- Related work stays in the same ticket +- Don't split artificially: "Build user profile page" includes both UI and API integration +- Do split when different specialties: Separate backend API task from frontend UI task if worked on by different people + +### Avoid Duplication +- Don't create redundant tickets for the same functionality +- If multiple features need the same infrastructure, create one infrastructure ticket they all depend on + +### Explicit Testing +- Include testing as part of feature tasks ("Implement X with unit tests") +- OR create separate testing tasks for complex features ("Write integration tests for authentication flow") + +### Documentation Tasks +- For user-facing features: Include "Update user documentation" or "Create help articles" +- For developer tools: Include "Update API documentation" or "Write integration guide" + +### Dependencies +- Note prerequisites in ticket descriptions +- Use "Depends on" or "Blocks" relationships in Jira if available +- Sequence tickets logically (infrastructure → implementation → testing) + +--- + +## Examples of Good Breakdowns + +### Example 1: New Feature - Search Functionality + +**Epic:** Product Search and Filtering + +**Tickets:** +1. [Task] Design search index schema and data structure +2. [Task] Implement backend search API with Elasticsearch +3. [Story] Build search input and results UI components +4. [Story] Add advanced filtering (price, category, ratings) +5. [Story] Implement search suggestions and autocomplete +6. [Task] Optimize search performance and add caching +7. [Task] Write search integration tests and documentation + +### Example 2: Bug Fix - Performance Issue + +**Epic:** Resolve Dashboard Load Time Issues + +**Tickets:** +1. [Task] Profile and identify performance bottlenecks +2. [Bug] Optimize database queries with indexes and caching +3. [Bug] Implement lazy loading for dashboard widgets +4. [Bug] Add pagination to large data tables +5. [Task] Set up performance monitoring and alerts + +### Example 3: Infrastructure - CI/CD Pipeline + +**Epic:** Automated Deployment Pipeline + +**Tickets:** +1. [Task] Set up GitHub Actions workflow configuration +2. [Task] Implement automated testing in CI pipeline +3. [Task] Configure staging environment deployment +4. [Task] Implement blue-green production deployment +5. [Task] Add deployment rollback mechanism +6. [Task] Create deployment runbook and documentation + diff --git a/plugins/atlassian-rovo/skills/spec-to-backlog/agents/openai.yaml b/plugins/atlassian-rovo/skills/spec-to-backlog/agents/openai.yaml new file mode 100644 index 00000000..faee61c3 --- /dev/null +++ b/plugins/atlassian-rovo/skills/spec-to-backlog/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Spec to Backlog" + short_description: "Convert Confluence specs into Jira backlogs" + icon_small: "./assets/app-icon.png" + icon_large: "./assets/app-icon.png" diff --git a/plugins/atlassian-rovo/skills/spec-to-backlog/references/breakdown-examples.md b/plugins/atlassian-rovo/skills/spec-to-backlog/references/breakdown-examples.md new file mode 100644 index 00000000..a40d326b --- /dev/null +++ b/plugins/atlassian-rovo/skills/spec-to-backlog/references/breakdown-examples.md @@ -0,0 +1,327 @@ +# Task Breakdown Examples + +This reference provides examples of effective task breakdowns for different types of specifications. + +## Principles of Good Breakdowns + +**DO:** +- Create tasks that are independently testable +- Group related frontend/backend work logically +- Include explicit testing and documentation tasks +- Use specific, actionable language +- Size tasks for 1-3 days of work typically + +**DON'T:** +- Create overly granular tasks (e.g., "Write one function") +- Make tasks too large (e.g., "Build entire feature") +- Duplicate work across multiple tickets +- Use vague descriptions (e.g., "Do backend stuff") + +## Example 1: New Feature - User Notifications System + +### Spec Summary +Add email and in-app notifications for user actions (comments, mentions, updates). + +### Good Breakdown (8 tasks) + +**Epic:** User Notifications System + +1. **Design notification data model and database schema** + - Define notification types and attributes + - Create database tables and indexes + - Document schema in API docs + +2. **Implement notification service backend** + - Create notification creation/retrieval APIs + - Add notification storage logic + - Implement marking notifications as read + +3. **Build email notification dispatcher** + - Set up email template system + - Implement async email sending queue + - Add email preferences handling + +4. **Create notification preferences API** + - User settings for notification types + - Email vs in-app preferences + - Frequency controls (immediate, digest) + +5. **Build notification UI components** + - Notification bell icon with unread count + - Notification dropdown panel + - Individual notification cards + +6. **Implement notification settings page** + - Frontend for user preferences + - Connect to preferences API + - Add toggle controls for notification types + +7. **Add notification triggers to existing features** + - Hook into comment system + - Hook into mention system + - Hook into update/edit events + +8. **Write tests and documentation** + - Unit tests for notification service + - Integration tests for email delivery + - Update user documentation + +### Why This Works +- Each task is independently completable +- Clear separation between backend, frontend, and integration +- Testing is explicit +- Tasks are sized appropriately (1-3 days each) + +--- + +## Example 2: Bug Fix - Payment Processing Errors + +### Spec Summary +Users report intermittent payment failures. Investigation shows timeout issues with payment gateway and inadequate error handling. + +### Good Breakdown (5 tasks) + +**Epic:** Fix Payment Processing Reliability + +1. **Investigate and document payment failure patterns** + - Analyze error logs and failure rates + - Document specific error scenarios + - Create reproduction steps + +2. **Implement payment gateway timeout handling** + - Add configurable timeout settings + - Implement retry logic with exponential backoff + - Add circuit breaker pattern + +3. **Improve payment error messaging** + - Enhance error categorization + - Add user-friendly error messages + - Log detailed errors for debugging + +4. **Add payment status reconciliation job** + - Create background job to verify payment status + - Handle stuck/pending payments + - Send notifications for payment issues + +5. **Add monitoring and alerting** + - Set up payment failure rate alerts + - Add dashboard for payment health metrics + - Document troubleshooting procedures + +### Why This Works +- Starts with investigation (important for bugs) +- Addresses root cause and symptoms +- Includes monitoring to prevent recurrence +- Each task delivers incremental value + +--- + +## Example 3: Infrastructure - Migration to New Database + +### Spec Summary +Migrate from PostgreSQL 12 to PostgreSQL 15, update queries to use new features, ensure zero downtime. + +### Good Breakdown (7 tasks) + +**Epic:** PostgreSQL 15 Migration + +1. **Set up PostgreSQL 15 staging environment** + - Provision new database instances + - Configure replication from production + - Verify data consistency + +2. **Audit and update database queries** + - Identify queries using deprecated features + - Update to PostgreSQL 15 syntax + - Optimize queries for new planner + +3. **Update application connection pooling** + - Upgrade database drivers + - Adjust connection pool settings + - Test connection handling under load + +4. **Create migration runbook** + - Document step-by-step migration process + - Define rollback procedures + - List success criteria and validation steps + +5. **Perform dry-run migration in staging** + - Execute full migration process + - Validate data integrity + - Measure downtime duration + - Test rollback procedure + +6. **Execute production migration** + - Follow migration runbook + - Monitor system health during migration + - Validate all services post-migration + +7. **Post-migration cleanup and monitoring** + - Remove old database instances after verification period + - Update monitoring dashboards + - Document lessons learned + +### Why This Works +- Emphasizes planning and validation +- Includes explicit dry-run +- Risk mitigation with rollback planning +- Clear separation between prep, execution, and cleanup + +--- + +## Example 4: API Development - Public REST API + +### Spec Summary +Create public REST API for third-party integrations. Include authentication, rate limiting, and documentation. + +### Good Breakdown (9 tasks) + +**Epic:** Public REST API v1 + +1. **Design API specification** + - Define endpoints and request/response schemas + - Create OpenAPI/Swagger specification + - Review with stakeholders + +2. **Implement API authentication system** + - Add API key generation and management + - Implement OAuth2 flow + - Create authentication middleware + +3. **Build rate limiting infrastructure** + - Implement token bucket algorithm + - Add per-key rate limit tracking + - Create rate limit headers and responses + +4. **Implement core API endpoints - Users** + - GET /users endpoints + - POST /users endpoints + - PUT/DELETE /users endpoints + +5. **Implement core API endpoints - Resources** + - GET /resources endpoints + - POST /resources endpoints + - PUT/DELETE /resources endpoints + +6. **Add API versioning support** + - Implement version routing + - Add deprecation headers + - Document versioning strategy + +7. **Create developer portal and documentation** + - Set up documentation site + - Add interactive API explorer + - Write getting started guide and examples + +8. **Build API monitoring and analytics** + - Track API usage metrics + - Add error rate monitoring + - Create usage dashboards for customers + +9. **Write integration tests and SDK examples** + - Create comprehensive API test suite + - Write example code in Python/JavaScript + - Document common integration patterns + +### Why This Works +- Separates authentication and rate limiting (critical infrastructure) +- Groups endpoints by resource type +- Documentation is a first-class task +- Monitoring and developer experience are explicit + +--- + +## Example 5: Frontend Redesign - Dashboard Modernization + +### Spec Summary +Redesign main dashboard with modern UI framework, improve performance, maintain feature parity. + +### Good Breakdown (8 tasks) + +**Epic:** Dashboard UI Modernization + +1. **Create new component library foundation** + - Set up new UI framework (e.g., React + Tailwind) + - Build reusable component primitives + - Establish design system tokens + +2. **Build dashboard layout and navigation** + - Implement responsive grid layout + - Create new navigation sidebar + - Add breadcrumb and header components + +3. **Rebuild analytics widgets** + - Port existing chart components + - Implement new data visualization library + - Add loading and error states + +4. **Rebuild data table components** + - Create sortable/filterable table + - Add pagination and search + - Implement column customization + +5. **Implement user settings panel** + - Dashboard customization options + - Widget arrangement and visibility + - Preferences persistence + +6. **Optimize performance and lazy loading** + - Implement code splitting + - Add lazy loading for heavy widgets + - Optimize bundle size + +7. **Add responsive mobile views** + - Create mobile-optimized layouts + - Test on various screen sizes + - Implement touch gestures + +8. **Migration and A/B testing setup** + - Create feature flag for new dashboard + - Set up A/B test framework + - Plan gradual rollout strategy + +### Why This Works +- Foundation first (component library) +- Groups by feature area (analytics, tables) +- Performance and mobile are explicit tasks +- Includes rollout strategy + +--- + +## Anti-Patterns to Avoid + +### Too Granular +❌ **Bad:** +- "Create User model" +- "Create User controller" +- "Create User view" +- "Write User tests" +- "Update User documentation" + +✅ **Better:** +- "Implement User management feature (model, controller, views, tests)" + +### Too Vague +❌ **Bad:** +- "Do backend work" +- "Fix frontend issues" +- "Update database" + +✅ **Better:** +- "Implement user authentication API endpoints" +- "Resolve navigation menu rendering bugs" +- "Add indexes to orders table for query performance" + +### Missing Testing +❌ **Bad:** +- Only feature implementation tasks, no testing mentioned + +✅ **Better:** +- Include explicit testing tasks or ensure testing is part of each feature task + +### No Clear Ownership +❌ **Bad:** +- Tasks that require both frontend and backend work without clear boundaries + +✅ **Better:** +- Split into "Backend API for X" and "Frontend UI for X" when different people work on each diff --git a/plugins/atlassian-rovo/skills/spec-to-backlog/references/epic-templates.md b/plugins/atlassian-rovo/skills/spec-to-backlog/references/epic-templates.md new file mode 100644 index 00000000..cddafd2c --- /dev/null +++ b/plugins/atlassian-rovo/skills/spec-to-backlog/references/epic-templates.md @@ -0,0 +1,401 @@ +# Epic Description Templates + +Effective Epic descriptions provide context, goals, and success criteria. Use these templates based on the type of work. + +## Template 1: New Feature Epic + +```markdown +## Overview +[1-2 sentence description of what this Epic delivers] + +## Source Specification +[Link to Confluence page or design doc] + +## Business Value +[Why we're building this - user impact, business goals] + +## Success Criteria +- [ ] [Measurable outcome 1] +- [ ] [Measurable outcome 2] +- [ ] [Measurable outcome 3] + +## Technical Scope +- **Frontend**: [High-level frontend work] +- **Backend**: [High-level backend work] +- **Infrastructure**: [Any infrastructure needs] +- **Third-party**: [External integrations] + +## Out of Scope +- [Explicitly list what's NOT included to prevent scope creep] + +## Dependencies +- [List any blocking or related work] + +## Launch Plan +- **Target completion**: [Date or sprint] +- **Rollout strategy**: [All at once, gradual, A/B test, etc.] +``` + +### Example: User Notifications System + +```markdown +## Overview +Add comprehensive notification system supporting email and in-app notifications for user activity (comments, mentions, updates). + +## Source Specification +https://company.atlassian.net/wiki/spaces/PRODUCT/pages/123456/Notifications-Spec + +## Business Value +Users currently miss important updates, leading to delayed responses and reduced engagement. Notifications will increase daily active usage by an estimated 20% and improve user satisfaction scores. + +## Success Criteria +- [ ] Users receive email notifications within 5 minutes of trigger event +- [ ] In-app notifications appear in real-time (< 2 second delay) +- [ ] 80% of users enable at least one notification type +- [ ] Email delivery rate > 95% +- [ ] System handles 10,000 notifications/minute at peak + +## Technical Scope +- **Frontend**: Notification bell UI, preferences page, notification cards +- **Backend**: Notification service, email dispatcher, real-time delivery +- **Infrastructure**: Email service integration (SendGrid), websocket server +- **Third-party**: SendGrid for email delivery + +## Out of Scope +- Push notifications (mobile) - planned for Q2 +- SMS notifications - not in current roadmap +- Notification history beyond 30 days + +## Dependencies +- None - self-contained feature + +## Launch Plan +- **Target completion**: Sprint 24 (March 15) +- **Rollout strategy**: Gradual rollout, 10% → 50% → 100% over 1 week +``` + +--- + +## Template 2: Bug Fix Epic + +```markdown +## Problem Statement +[Clear description of the bug and its impact] + +## Source Documentation +[Link to Confluence investigation, incident report, or bug analysis] + +## Current Impact +- **Severity**: [Critical/High/Medium/Low] +- **Users affected**: [Percentage or number] +- **Frequency**: [How often it occurs] +- **Business impact**: [Revenue, reputation, etc.] + +## Root Cause +[Technical explanation of what's causing the issue] + +## Solution Approach +[High-level approach to fixing the issue] + +## Success Criteria +- [ ] [Bug no longer reproducible] +- [ ] [Related edge cases handled] +- [ ] [Monitoring in place to detect recurrence] + +## Verification Plan +[How we'll confirm the fix works] +``` + +### Example: Payment Processing Failures + +```markdown +## Problem Statement +Users experiencing intermittent payment failures during checkout, resulting in abandoned transactions and support tickets. Error rate spiked to 8% on Nov 15, up from baseline 0.5%. + +## Source Documentation +https://company.atlassian.net/wiki/spaces/ENG/pages/789012/Payment-Failure-Investigation + +## Current Impact +- **Severity**: Critical +- **Users affected**: ~800 customers per day +- **Frequency**: 8% of all payment attempts +- **Business impact**: $45K/day in lost revenue, customer trust erosion + +## Root Cause +Payment gateway timeouts due to insufficient timeout settings (5s) and no retry logic. During high load, 3rd party payment API occasionally takes 6-8s to respond, causing failures. + +## Solution Approach +1. Increase timeout to 15s with exponential backoff retry +2. Implement circuit breaker to prevent cascade failures +3. Add payment reconciliation job to handle stuck transactions +4. Improve error messaging for users + +## Success Criteria +- [ ] Payment failure rate below 1% +- [ ] Zero timeout-related failures +- [ ] 100% of stuck payments reconciled within 15 minutes +- [ ] User-facing error messages are clear and actionable + +## Verification Plan +- Load testing with simulated gateway delays +- Monitor production metrics for 1 week post-deployment +- Review support tickets for payment-related issues +``` + +--- + +## Template 3: Infrastructure/Technical Epic + +```markdown +## Objective +[What infrastructure change or technical improvement we're making] + +## Source Documentation +[Link to technical design doc or RFC] + +## Current State +[Description of existing system/approach] + +## Target State +[Description of desired system/approach after completion] + +## Motivation +[Why we need to make this change - performance, cost, maintainability, etc.] + +## Success Criteria +- [ ] [Technical metric 1] +- [ ] [Technical metric 2] +- [ ] [Zero downtime or minimal disruption] + +## Risk Mitigation +- **Rollback plan**: [How to revert if issues occur] +- **Monitoring**: [What metrics we'll watch] +- **Testing strategy**: [Dry runs, canary deployments, etc.] + +## Timeline Constraints +[Any time-sensitive factors like deprecations, costs] +``` + +### Example: PostgreSQL Migration + +```markdown +## Objective +Migrate primary database from PostgreSQL 12 to PostgreSQL 15 to leverage performance improvements and new features before PostgreSQL 12 EOL. + +## Source Documentation +https://company.atlassian.net/wiki/spaces/ENG/pages/345678/PG15-Migration-RFC + +## Current State +Running PostgreSQL 12.8 on AWS RDS with 2TB data, 50K queries/minute at peak. Some queries use deprecated features. + +## Target State +PostgreSQL 15.2 with optimized queries, improved query planner, and better connection pooling. Estimated 15-20% performance improvement on read-heavy queries. + +## Motivation +- PostgreSQL 12 reaches EOL in November 2024 +- PG15 query planner improvements will reduce latency on dashboard queries +- New features enable better monitoring and troubleshooting +- Cost savings: ~$800/month from improved efficiency + +## Success Criteria +- [ ] Zero data loss during migration +- [ ] < 5 minutes of downtime during cutover +- [ ] All application queries working correctly +- [ ] Query performance same or better than PG12 +- [ ] Monitoring confirms system health for 2 weeks + +## Risk Mitigation +- **Rollback plan**: Keep PG12 instance available for 2 weeks; can revert in < 15 minutes +- **Monitoring**: Track query latency, error rates, connection pool health +- **Testing strategy**: Full migration dry-run in staging, 24-hour soak test + +## Timeline Constraints +Must complete by October 2024 (1 month before PG12 EOL). Testing requires 3 weeks. +``` + +--- + +## Template 4: API Development Epic + +```markdown +## Overview +[What API or integration we're building] + +## Source Specification +[Link to API design doc or requirements] + +## Use Cases +[Primary scenarios this API will enable] + +## API Design +- **Authentication**: [Method - API keys, OAuth, etc.] +- **Rate limiting**: [Limits and quotas] +- **Versioning**: [Strategy] +- **Base URL**: [Endpoint structure] + +## Endpoints Summary +[High-level list of main endpoint categories] + +## Success Criteria +- [ ] [API stability metric] +- [ ] [Performance target] +- [ ] [Documentation completeness] +- [ ] [Developer adoption metric] + +## Documentation Deliverables +- [ ] OpenAPI/Swagger spec +- [ ] Getting started guide +- [ ] Code examples (Python, JavaScript) +- [ ] Interactive API explorer + +## Timeline +- **Beta release**: [Date] +- **GA release**: [Date] +``` + +### Example: Public REST API + +```markdown +## Overview +Launch v1 of public REST API enabling third-party developers to integrate with our platform for user management and resource access. + +## Source Specification +https://company.atlassian.net/wiki/spaces/API/pages/456789/Public-API-v1-Spec + +## Use Cases +- SaaS companies integrating our user management into their products +- Data analytics tools pulling resource data +- Automation platforms connecting workflows +- Mobile app developers building custom clients + +## API Design +- **Authentication**: OAuth 2.0 + API keys +- **Rate limiting**: 1,000 requests/hour per API key (higher tiers available) +- **Versioning**: URI-based (/v1/, /v2/) +- **Base URL**: https://api.company.com/v1 + +## Endpoints Summary +- User management (CRUD operations) +- Resource access (read-only initially) +- Webhooks for event notifications +- Account administration + +## Success Criteria +- [ ] 99.9% uptime +- [ ] p95 latency < 200ms +- [ ] Complete OpenAPI documentation +- [ ] 50+ developers signed up for beta +- [ ] Zero security vulnerabilities in initial audit + +## Documentation Deliverables +- [x] OpenAPI/Swagger spec +- [ ] Getting started guide +- [ ] Code examples (Python, JavaScript, Ruby) +- [ ] Interactive API explorer (Swagger UI) +- [ ] Authentication tutorial +- [ ] Best practices guide + +## Timeline +- **Beta release**: February 15 (invite-only, 10 partners) +- **GA release**: March 30 (public availability) +``` + +--- + +## Template 5: Redesign/Modernization Epic + +```markdown +## Overview +[What's being redesigned and why] + +## Source Documentation +[Link to design specs, mockups, or requirements] + +## Current Pain Points +- [Problem 1 with existing implementation] +- [Problem 2 with existing implementation] +- [Problem 3 with existing implementation] + +## New Design Goals +- [Goal 1] +- [Goal 2] +- [Goal 3] + +## Success Criteria +- [ ] [User experience metric] +- [ ] [Performance improvement] +- [ ] [Feature parity or improvements] +- [ ] [Accessibility standards met] + +## Migration Strategy +[How users transition from old to new] + +## Rollout Plan +[Phased rollout, A/B testing, feature flags] +``` + +### Example: Dashboard Modernization + +```markdown +## Overview +Redesign main analytics dashboard with modern UI framework, improved performance, and better mobile support while maintaining all existing functionality. + +## Source Documentation +https://company.atlassian.net/wiki/spaces/DESIGN/pages/567890/Dashboard-Redesign + +## Current Pain Points +- Slow initial load time (4-6 seconds) +- Poor mobile experience (not responsive) +- Outdated UI feels "legacy" +- Difficult to customize widget layout +- Accessibility issues (WCAG 2.1 violations) + +## New Design Goals +- Modern, clean visual design aligned with brand refresh +- < 2 second initial load time +- Fully responsive (desktop, tablet, mobile) +- Customizable dashboard layouts +- WCAG 2.1 AA compliant +- Improved data visualization clarity + +## Success Criteria +- [ ] Initial load time < 2s (50% improvement) +- [ ] Perfect Lighthouse score (90+) +- [ ] Zero WCAG 2.1 AA violations +- [ ] 80% user approval rating in beta test +- [ ] Feature parity with legacy dashboard +- [ ] Mobile usage increases by 30% + +## Migration Strategy +- Side-by-side availability during transition +- Users can switch between old/new with toggle +- Preferences automatically migrated +- 30-day sunset period for legacy dashboard + +## Rollout Plan +1. Week 1: Internal beta (engineering team) +2. Week 2-3: Customer beta (10% of users via feature flag) +3. Week 4: Expand to 50% of users +4. Week 5: 100% rollout, legacy available via toggle +5. Week 9: Remove legacy dashboard +``` + +--- + +## Key Elements in Every Epic + +Regardless of template, ensure every Epic includes: + +1. **Clear objective** - Anyone should understand what's being built/fixed +2. **Source link** - Always link to the Confluence spec or design doc +3. **Success criteria** - Measurable outcomes that define "done" +4. **Scope clarity** - What IS and ISN'T included +5. **Context** - Enough background for someone new to understand why this matters + +## Common Mistakes to Avoid + +❌ **Too brief**: "Build notifications" - lacks context +❌ **Too detailed**: Including implementation details that belong in tickets +❌ **No success criteria**: How do we know when it's done? +❌ **Missing source link**: Hard to trace back to requirements +❌ **Vague scope**: Leads to scope creep and confusion diff --git a/plugins/atlassian-rovo/skills/spec-to-backlog/references/ticket-writing-guide.md b/plugins/atlassian-rovo/skills/spec-to-backlog/references/ticket-writing-guide.md new file mode 100644 index 00000000..d381843e --- /dev/null +++ b/plugins/atlassian-rovo/skills/spec-to-backlog/references/ticket-writing-guide.md @@ -0,0 +1,354 @@ +# Ticket Writing Guide + +Guidelines for creating clear, actionable Jira tickets with effective summaries and descriptions. + +## Summary Guidelines + +The ticket summary should be a clear, concise action statement that immediately tells someone what needs to be done. + +### Formula + +**[Action Verb] + [Component/Feature] + [Optional: Context]** + +### Good Examples + +✅ "Implement user registration API endpoint" +✅ "Fix pagination bug in search results" +✅ "Add email validation to signup form" +✅ "Optimize database query for dashboard load time" +✅ "Create documentation for payment webhook" +✅ "Design user preferences data schema" + +### Bad Examples + +❌ "Users" - Not actionable +❌ "Do backend work" - Too vague +❌ "Fix bug" - Lacks specificity +❌ "API" - Not a task +❌ "There's an issue with the login page that needs to be addressed" - Too wordy + +### Action Verbs by Task Type + +**Development:** +- Implement, Build, Create, Add, Develop + +**Bug Fixes:** +- Fix, Resolve, Correct, Debug + +**Design/Planning:** +- Design, Plan, Research, Investigate, Define + +**Infrastructure:** +- Set up, Configure, Deploy, Migrate, Upgrade + +**Documentation:** +- Write, Document, Update, Create + +**Improvement:** +- Optimize, Refactor, Improve, Enhance + +**Testing:** +- Test, Verify, Validate + +--- + +## Description Structure + +A good ticket description provides context, requirements, and guidance without being overwhelming. + +### Recommended Template + +```markdown +## Context +[1-2 sentences: Why we're doing this, what problem it solves] + +## Requirements +- [Specific requirement 1] +- [Specific requirement 2] +- [Specific requirement 3] + +## Technical Notes +[Any technical constraints, preferred approaches, or implementation hints] + +## Acceptance Criteria +- [ ] [Testable outcome 1] +- [ ] [Testable outcome 2] +- [ ] [Testable outcome 3] + +## Resources +- [Link to design mockup if applicable] +- [Link to API documentation] +- [Link to related tickets] +``` + +### Example 1: Feature Implementation + +**Summary:** Implement user registration API endpoint + +**Description:** +```markdown +## Context +Users need to create accounts through our REST API. This endpoint will be used by our web app and future mobile apps. + +## Requirements +- Accept email, password, and name via POST request +- Validate email format and uniqueness +- Hash password using bcrypt +- Return JWT token for immediate authentication +- Send welcome email asynchronously + +## Technical Notes +- Use existing email service for welcome emails +- Follow authentication patterns from login endpoint +- Rate limit: 5 registration attempts per IP per hour + +## Acceptance Criteria +- [ ] Endpoint accepts valid registration data and returns 201 with JWT +- [ ] Duplicate email returns 409 error +- [ ] Invalid email format returns 400 error +- [ ] Password must be 8+ characters +- [ ] Welcome email sent within 1 minute +- [ ] Unit tests cover happy path and error cases + +## Resources +- API Spec: https://company.atlassian.net/wiki/API-Design +- Related: AUTH-123 (Login endpoint) +``` + +### Example 2: Bug Fix + +**Summary:** Fix pagination bug in search results + +**Description:** +```markdown +## Context +Users report that clicking "Next Page" in search results sometimes shows duplicate items from the previous page. This happens intermittently when search results are sorted by date. + +## Problem +The pagination offset calculation doesn't account for items with identical timestamps, causing cursor position drift when using timestamp-based pagination. + +## Requirements +- Ensure each search result appears exactly once +- Maintain current sort order (date descending) +- Fix applies to all search endpoints + +## Technical Notes +- Current implementation uses timestamp as cursor: `?cursor=2024-01-15T10:30:00Z` +- Suggested fix: Composite cursor using timestamp + ID +- Consider adding unique index on (timestamp, id) for better query performance + +## Acceptance Criteria +- [ ] No duplicate items appear across paginated results +- [ ] Pagination works correctly with items having identical timestamps +- [ ] All existing search API tests still pass +- [ ] Added test case reproducing the original bug +- [ ] Performance impact < 5ms per query + +## Resources +- Bug Report: https://company.atlassian.net/wiki/BUG-456 +- Related: SEARCH-789 (Original search implementation) +``` + +### Example 3: Infrastructure Task + +**Summary:** Set up PostgreSQL 15 staging environment + +**Description:** +```markdown +## Context +First step in database migration from PG12 to PG15. Need staging environment to validate migration process and test query compatibility. + +## Requirements +- Provision PG15 instance matching production specs +- Set up replication from production to staging +- Configure backup retention (7 days) +- Enable query logging for testing + +## Technical Notes +- Use AWS RDS PostgreSQL 15.2 +- Instance type: db.r6g.2xlarge (same as prod) +- Enable logical replication for zero-downtime testing +- VPC: staging-vpc-us-east-1 + +## Acceptance Criteria +- [ ] PG15 instance running and accessible from staging apps +- [ ] Replication lag < 30 seconds from production +- [ ] Can connect using standard credentials +- [ ] Query logs enabled and viewable +- [ ] Monitoring dashboards created +- [ ] Backup configured and tested (restore test) + +## Resources +- Migration RFC: https://company.atlassian.net/wiki/PG15-Migration +- Infrastructure docs: https://wiki/Database-Setup +- Parent Epic: INFRA-100 +``` + +### Example 4: Frontend Task + +**Summary:** Create notification bell UI component + +**Description:** +```markdown +## Context +Part of notification system. Need UI component showing unread notification count and opening notification panel. + +## Requirements +- Bell icon in top navigation bar +- Display unread count badge (e.g., "5") +- Click opens notification dropdown panel +- Real-time updates via WebSocket +- Badge turns red for urgent notifications + +## Technical Notes +- Use existing Icon component library +- WebSocket events: 'notification:new', 'notification:read' +- State management: Context API or Zustand +- Position: Right side of nav, left of user avatar + +## Acceptance Criteria +- [ ] Bell icon displays in navigation bar +- [ ] Unread count badge shows accurate count +- [ ] Badge updates in real-time when new notification arrives +- [ ] Click opens/closes notification panel +- [ ] No badge shown when count is 0 +- [ ] Component is accessible (keyboard navigation, screen reader) +- [ ] Responsive design (mobile, tablet, desktop) + +## Resources +- Design mockup: [Figma link] +- WebSocket docs: https://wiki/Notifications-API +- Related: NOTIF-123 (Notification panel component) +``` + +--- + +## Descriptions by Task Type + +### Backend Development + +Focus on: +- API contract (request/response format) +- Data validation rules +- Error handling requirements +- Performance expectations +- Security considerations + +### Frontend Development + +Focus on: +- Visual design reference +- User interactions +- State management approach +- Responsive behavior +- Accessibility requirements + +### Bug Fixes + +Focus on: +- Reproduction steps +- Expected vs actual behavior +- Root cause (if known) +- Affected users/scenarios +- Verification approach + +### Testing + +Focus on: +- What needs testing (features, edge cases) +- Test coverage targets +- Types of tests (unit, integration, e2e) +- Performance benchmarks +- Test data requirements + +### Documentation + +Focus on: +- Target audience +- Required sections/topics +- Examples to include +- Existing docs to update +- Review/approval process + +--- + +## Acceptance Criteria Best Practices + +Acceptance criteria should be: + +1. **Testable** - Can verify by testing or observation +2. **Specific** - No ambiguity about what "done" means +3. **Complete** - Covers all requirements in description +4. **User-focused** - When possible, frame from user perspective + +### Good Acceptance Criteria + +✅ "User can submit form and receive confirmation email within 30 seconds" +✅ "API returns 400 error when email field is empty" +✅ "Dashboard loads in under 2 seconds on 3G connection" +✅ "All text meets WCAG 2.1 AA contrast ratios" + +### Bad Acceptance Criteria + +❌ "Feature works well" - Not specific +❌ "Code is clean" - Subjective, not testable +❌ "Fast performance" - Not measurable +❌ "No bugs" - Too broad + +--- + +## Technical Notes Guidelines + +Use "Technical Notes" section for: + +- **Architectural decisions**: "Use Redis for session caching" +- **Implementation hints**: "Follow pattern from UserService class" +- **Performance constraints**: "Query must complete in < 100ms" +- **Security requirements**: "Use parameterized queries to prevent SQL injection" +- **Dependencies**: "Requires AUTH-456 to be deployed first" +- **Gotchas**: "Watch out for timezone handling in date comparisons" + +Keep it concise - detailed technical specs belong in Confluence or code comments. + +--- + +## Common Mistakes to Avoid + +### 1. Information Overload +❌ Pages of requirements copied from spec doc +✅ Summary with link to full spec + +### 2. Assuming Context +❌ "Fix the bug we discussed" +✅ Clear description of the bug with reproduction steps + +### 3. Implementation as Requirement +❌ "Use React hooks for state management" +✅ "Component updates in real-time" (let developer choose approach unless there's a specific reason) + +### 4. Vague Acceptance Criteria +❌ "Everything works correctly" +✅ Specific, testable outcomes + +### 5. Missing Links +❌ No reference to designs, specs, or related work +✅ Links to all relevant documentation + +--- + +## Length Guidelines + +**Summary:** +- Target: 3-8 words +- Max: 12 words + +**Description:** +- Target: 100-300 words +- Min: Include at minimum context and acceptance criteria +- Max: 500 words (link to docs for more detail) + +**Acceptance Criteria:** +- Target: 3-7 items +- Each item: 1 sentence + +Remember: Ticket descriptions are not documentation. They're instructions for completing a specific task. diff --git a/plugins/atlassian-rovo/skills/triage-issue/SKILL.md b/plugins/atlassian-rovo/skills/triage-issue/SKILL.md new file mode 100644 index 00000000..3b8665da --- /dev/null +++ b/plugins/atlassian-rovo/skills/triage-issue/SKILL.md @@ -0,0 +1,700 @@ +--- +name: triage-issue +description: "Intelligently triage bug reports and error messages by searching for duplicates in Jira and offering to create new issues or add comments to existing ones. When an agent needs to: (1) Triage a bug report or error message, (2) Check if an issue is a duplicate, (3) Find similar past issues, (4) Create a new bug ticket with proper context, or (5) Add information to an existing ticket. Searches Jira for similar issues, identifies duplicates, checks fix history, and helps create well-structured bug reports." +--- + +# Triage Issue + +## Keywords +triage bug, check duplicate, is this a duplicate, search for similar issues, create bug ticket, file a bug, report this error, triage this error, bug report, error message, similar issues, duplicate bug, who fixed this, has this been reported, search bugs, find similar bugs, create issue, file issue + +## Overview + +Automatically triage bug reports and error messages by searching Jira for duplicates, identifying similar past issues, and helping create well-structured bug tickets or add context to existing issues. This skill eliminates manual duplicate checking and ensures bugs are properly documented with relevant historical context. + +**Use this skill when:** Users need to triage error messages, bug reports, or issues to determine if they're duplicates and take appropriate action. + +--- + +## Workflow + +Follow this 6-step process to effectively triage issues: + +### Step 1: Extract Key Information + +Analyze the bug report or error message to identify search terms. + +#### Extract These Elements: + +**Error signature:** +- Error type or exception name (e.g., "NullPointerException", "TimeoutError") +- Error code or status (e.g., "500", "404", "ERR_CONNECTION_REFUSED") +- Specific error message text (key phrases, not full stack trace) + +**Context:** +- Component or system affected (e.g., "authentication", "payment gateway", "API") +- Environment (e.g., "production", "staging", "mobile app") +- User actions leading to error (e.g., "during login", "when uploading file") + +**Symptoms:** +- Observable behavior (e.g., "page blank", "infinite loading", "data not saving") +- Impact (e.g., "users can't login", "payments failing") + +#### Example Extractions: + +**Input:** "Users getting 'Connection timeout' error when trying to login on mobile app" +**Extracted:** +- Error: "Connection timeout" +- Component: "login", "mobile app" +- Symptom: "can't login" + +**Input:** "NullPointerException in PaymentProcessor.processRefund() line 245" +**Extracted:** +- Error: "NullPointerException" +- Component: "PaymentProcessor", "refund" +- Location: "processRefund line 245" + +--- + +### Step 2: Search for Duplicates + +Search Jira using extracted keywords to find similar or duplicate issues. + +#### Search Strategy: + +Execute **multiple targeted searches** to catch duplicates that may use different wording: + +**Search 1: Error-focused** +``` +searchJiraIssuesUsingJql( + cloudId="...", + jql='project = "PROJ" AND (text ~ "error signature" OR summary ~ "error signature") AND type = Bug ORDER BY created DESC', + fields=["summary", "description", "status", "resolution", "created", "updated", "assignee"], + maxResults=20 +) +``` + +**Search 2: Component-focused** +``` +searchJiraIssuesUsingJql( + cloudId="...", + jql='project = "PROJ" AND text ~ "component keywords" AND type = Bug ORDER BY updated DESC', + fields=["summary", "description", "status", "resolution", "created", "updated", "assignee"], + maxResults=20 +) +``` + +**Search 3: Symptom-focused** +``` +searchJiraIssuesUsingJql( + cloudId="...", + jql='project = "PROJ" AND summary ~ "symptom keywords" AND type = Bug ORDER BY priority DESC, updated DESC', + fields=["summary", "description", "status", "resolution", "created", "updated", "assignee"], + maxResults=20 +) +``` + +#### Search Tips: + +**Use key terms only:** +- ✅ "timeout login mobile" +- ✅ "NullPointerException PaymentProcessor refund" +- ❌ "Users are getting a connection timeout error when..." (too verbose) + +**Search recent first:** +- Order by `created DESC` or `updated DESC` to find recent similar issues +- Recent bugs are more likely to be relevant duplicates + +**Don't over-filter:** +- Include resolved issues (might have been reopened or regression) +- Search across all bug statuses to find fix history + +--- + +### Step 3: Analyze Search Results + +Evaluate the search results to determine if this is a duplicate or a new issue. + +#### Duplicate Detection: + +**High confidence duplicate (>90%):** +- Exact same error message in summary or description +- Same component + same error type +- Recent issue (< 30 days) with identical symptoms +- **Action:** Strongly recommend adding comment to existing issue + +**Likely duplicate (70-90%):** +- Similar error with slight variations +- Same component but different context +- Resolved issue with same root cause +- **Action:** Present as possible duplicate, let user decide + +**Possibly related (40-70%):** +- Similar symptoms but different error +- Same component area but different specific error +- Old issue (> 6 months) that might be unrelated +- **Action:** Mention as potentially related + +**Likely new issue (<40%):** +- No similar issues found +- Different error signature and component +- Unique symptom or context +- **Action:** Recommend creating new issue + +#### Check Fix History: + +If similar resolved issues are found: + +**Extract relevant information:** +- Who fixed it? (assignee on resolved issues) +- How was it fixed? (resolution comment or linked PRs) +- When was it fixed? (resolution date) +- Has it regressed? (any reopened issues) + +**Present this context** to help with triage decision. + +--- + +### Step 4: Present Findings to User + +**CRITICAL:** Always present findings and wait for user decision before taking any action. + +#### Format for Likely Duplicate: + +``` +🔍 **Triage Results: Likely Duplicate** + +I found a very similar issue already reported: + +**PROJ-456** - Connection timeout during mobile login +Status: Open | Priority: High | Created: 3 days ago +Assignee: @john.doe +https://yoursite.atlassian.net/browse/PROJ-456 + +**Similarity:** +- Same error: "Connection timeout" +- Same component: Mobile app login +- Same symptoms: Users unable to login + +**Difference:** +- Original report mentioned iOS specifically, this report doesn't specify platform + +**Recommendation:** Add your details as a comment to PROJ-456 + +Would you like me to: +1. Add a comment to PROJ-456 with your error details +2. Create a new issue anyway (if you think this is different) +3. Show me more details about PROJ-456 first +``` + +#### Format for Possibly Related: + +``` +🔍 **Triage Results: Possibly Related Issues Found** + +I found 2 potentially related issues: + +**1. PROJ-789** - Mobile app authentication failures +Status: Resolved | Fixed: 2 weeks ago | Fixed by: @jane.smith +https://yoursite.atlassian.net/browse/PROJ-789 + +**2. PROJ-234** - Login timeout on slow connections +Status: Open | Priority: Medium | Created: 1 month ago +https://yoursite.atlassian.net/browse/PROJ-234 + +**Assessment:** Your error seems related but has unique aspects + +**Recommendation:** Create a new issue, but reference these related tickets + +Would you like me to create a new bug ticket? +``` + +#### Format for No Duplicates: + +``` +🔍 **Triage Results: No Duplicates Found** + +I searched Jira for: +- "Connection timeout" errors +- Mobile login issues +- Authentication failures + +No similar open or recent issues found. + +**Recommendation:** Create a new bug ticket + +**Note:** I found 1 old resolved issue (PROJ-123 from 8 months ago) about login timeouts, but it was for web, not mobile, and was resolved as "configuration error." + +Would you like me to create a new bug ticket for this issue? +``` + +--- + +### Step 5: Execute User Decision + +Based on user's choice, either add a comment or create a new issue. + +#### Option A: Add Comment to Existing Issue + +If user wants to add to existing issue: + +**Fetch the full issue first** to understand context: +``` +getJiraIssue( + cloudId="...", + issueIdOrKey="PROJ-456" +) +``` + +**Then add the comment:** +``` +addCommentToJiraIssue( + cloudId="...", + issueIdOrKey="PROJ-456", + commentBody="[formatted comment - see below]" +) +``` + +**Comment Structure:** +```markdown +## Additional Instance Reported + +**Reporter:** [User's name or context] +**Date:** [Current date] + +**Error Details:** +[Paste relevant error message or stack trace] + +**Context:** +- Environment: [e.g., Production, iOS 16.5] +- User Impact: [e.g., 50+ users affected in last hour] +- Steps to Reproduce: [if provided] + +**Additional Notes:** +[Any unique aspects of this instance] + +--- +*Added via triage automation* +``` + +#### Option B: Create New Issue + +If user wants to create new issue: + +**First, check available issue types:** +``` +getJiraProjectIssueTypesMetadata( + cloudId="...", + projectIdOrKey="PROJ" +) +``` + +**Determine appropriate issue type:** +- For bugs/errors → Use "Bug" (if available) +- For issues without errors → Use "Task" or "Issue" +- Fallback → First available non-Epic, non-Subtask type + +**Create the issue:** +``` +createJiraIssue( + cloudId="...", + projectKey="PROJ", + issueTypeName="Bug", + summary="[Clear, specific summary - see below]", + description="[Detailed description - see below]", + additional_fields={ + "priority": {"name": "Medium"} # Adjust based on user input severity assessment + } +) +``` + +**Summary Format:** +Use the pattern: `[Component] [Error Type] - [Brief Symptom]` + +**Examples:** +- ✅ "Mobile Login: Connection timeout during authentication" +- ✅ "Payment API: NullPointerException in refund processing" +- ✅ "Dashboard: Infinite loading on reports page" +- ❌ "Error in production" (too vague) +- ❌ "Users experiencing issues" (not specific) + +**Description Structure:** +```markdown +## Issue Description +[1-2 sentence summary of the problem] + +## Error Details +``` +[Error message or stack trace] +``` + +## Environment +- **Platform:** [e.g., Mobile iOS, Web, API] +- **Version:** [if known] +- **Environment:** [Production/Staging/etc] + +## Steps to Reproduce +1. [Step 1] +2. [Step 2] +3. [Step 3] + +## Expected Behavior +[What should happen] + +## Actual Behavior +[What actually happens] + +## User Impact +- **Frequency:** [e.g., Every time, Intermittent] +- **Affected Users:** [e.g., All users, Mobile users only] +- **Severity:** [e.g., Users cannot complete checkout] + +## Additional Context +[Any other relevant information] + +## Related Issues +[If applicable, reference similar issues found during triage] +- See also: PROJ-123 (similar but resolved) + +--- +*Created via automated triage* +``` + +--- + +### Step 6: Provide Summary + +After taking action, confirm what was done. + +#### If Comment Added: + +``` +✅ **Comment Added Successfully** + +Added details to existing issue: **PROJ-456** +https://yoursite.atlassian.net/browse/PROJ-456 + +**What I included:** +- Your error details +- Environment context +- User impact information + +**Next Steps:** +- The assignee (@john.doe) will be notified +- Monitor PROJ-456 for updates +- If this turns out to be different, we can still create a separate ticket +``` + +#### If New Issue Created: + +``` +✅ **New Issue Created** + +**PROJ-890** - Mobile Login: Connection timeout during authentication +https://yoursite.atlassian.net/browse/PROJ-890 + +Type: Bug | Priority: Medium | Status: Open + +**What's Included:** +- Complete error details and stack trace +- Environment and reproduction steps +- User impact assessment +- References to related issues (PROJ-123, PROJ-789) + +**Next Steps:** +- Issue will be reviewed during next triage meeting +- Consider setting priority based on user impact +- Assign to appropriate team member +``` + +--- + +## Edge Cases & Troubleshooting + +### Multiple Potential Duplicates + +If you find 3+ very similar issues: + +``` +🔍 **Triage Results: Multiple Possible Duplicates** + +I found 3 issues that might be related: + +**Most Likely Duplicate:** +**PROJ-456** - [summary] (Open, 2 days ago) +Match: 95% - Same error and component + +**Also Possibly Related:** +**PROJ-234** - [summary] (Open, 1 month ago) +Match: 70% - Similar symptoms, different error + +**PROJ-123** - [summary] (Resolved, 8 months ago) +Match: 60% - Related component, but was fixed + +**Recommendation:** +1. Add to PROJ-456 (most similar) +2. Reference PROJ-234 in your comment (might be related) +3. Note PROJ-123 was previously fixed (possible regression) + +Which issue should I add your details to? (Or create new) +``` + +### Unclear Project Context + +If user doesn't specify which project: + +``` +Which Jira project should I search for similar issues? + +Available projects: +- BACKEND (Backend Services) +- MOBILE (Mobile Apps) +- WEB (Web Platform) +- INFRA (Infrastructure) + +Or tell me the project key directly (e.g., BACKEND, MOBILE) +``` + +### Insufficient Information + +If the bug report lacks critical details: + +``` +I need more information to effectively triage this issue: + +**What I have:** +- Error: "Something went wrong" + +**What would help:** +- Specific error message or code +- Which part of the system (login, payment, etc.) +- What the user was trying to do +- Which environment (production, staging, mobile, web) + +Can you provide any of these details? +``` + +### Resolved Regression + +If you find a resolved issue that matches: + +``` +🔍 **Triage Results: Possible Regression** + +This looks like it might be a regression of a previously fixed issue: + +**PROJ-567** - [Same issue description] +Status: Resolved (Fixed) | Fixed: 3 months ago | Fixed by: @jane.smith +Resolution: [Brief description of fix] +https://yoursite.atlassian.net/browse/PROJ-567 + +**This suggests:** +- The original fix may not have fully addressed the root cause +- OR there's been a regression in recent changes +- OR this is a different issue with similar symptoms + +**Recommendation:** Create a new issue and link it to PROJ-567 as "may be related to" or "regression of" + +Should I create a new issue with this context? +``` + +### Custom Required Fields + +If creating an issue fails due to required fields: + +1. **Check what fields are required:** +``` +getJiraIssueTypeMetaWithFields( + cloudId="...", + projectIdOrKey="PROJ", + issueTypeId="10001" +) +``` + +2. **Ask user for values:** +``` +This project requires additional fields to create a Bug: +- Severity: [High/Medium/Low] +- Affected Version: [Version number] + +Please provide these values so I can create the issue. +``` + +3. **Retry with additional fields:** +``` +createJiraIssue( + ...existing parameters..., + additional_fields={ + "priority": {"name": "High"}, + "customfield_10001": {"value": "Production"} + } +) +``` + +--- + +## Tips for Effective Triage + +### For Search: + +**Do:** +✅ Use multiple search queries with different angles +✅ Include both open and resolved issues in search +✅ Search for error signatures and symptoms separately +✅ Look at recent issues first (last 30-90 days) +✅ Check for patterns (multiple reports of same thing) + +**Don't:** +❌ Search with entire error messages (too specific) +❌ Only search open issues (miss fix history) +❌ Ignore resolved issues (miss regressions) +❌ Use too many keywords (reduces matches) + +### For Issue Creation: + +**Do:** +✅ Write clear, specific summaries with component names +✅ Include complete error messages in code blocks +✅ Add environment and impact details +✅ Reference related issues found during search +✅ Use "Bug" issue type for actual bugs + +**Don't:** +❌ Create vague summaries like "Error in production" +❌ Paste entire stack traces in summary (use description) +❌ Skip reproduction steps +❌ Forget to mention user impact +❌ Hard-code issue type without checking availability + +### For Duplicate Assessment: + +**High Confidence Duplicates:** +- Exact same error + same component + recent (< 30 days) +- Same root cause identified + +**Likely Different Issues:** +- Different error signatures +- Different components/systems +- Significantly different contexts + +**When Unsure:** +- Present both options to user +- Lean toward creating new issue (can be closed as duplicate later) +- Linking issues is better than hiding information + +--- + +## Examples + +### Example 1: Clear Duplicate Found + +**User Input:** +``` +Triage this error: "Connection timeout error when users try to login on iOS app" +``` + +**Process:** +1. Extract: "Connection timeout", "login", "iOS" +2. Search: Find PROJ-456 (open, 2 days ago) with exact same error +3. Analyze: 95% match - same error, component, symptom +4. Present: Show PROJ-456 as duplicate, recommend adding comment +5. Execute: User confirms, add comment with iOS-specific details +6. Confirm: Comment added to PROJ-456 + +**Output:** +``` +✅ Comment added to PROJ-456 + +Your iOS-specific error details have been added to the existing issue. +The assignee will be notified. +``` + +### Example 2: New Issue with Related Context + +**User Input:** +``` +Error: NullPointerException in PaymentProcessor.processRefund() at line 245 +Stack trace: [full stack trace] +``` + +**Process:** +1. Extract: "NullPointerException", "PaymentProcessor", "processRefund", "line 245" +2. Search: Find PROJ-789 (resolved, 3 weeks ago) about payment errors, but different line +3. Analyze: Related component but different specific error +4. Present: No duplicates, found related issue, recommend new ticket +5. Execute: User confirms, create new Bug with context +6. Confirm: PROJ-890 created + +**Output:** +``` +✅ New Issue Created + +PROJ-890 - Payment API: NullPointerException in refund processing +https://yoursite.atlassian.net/browse/PROJ-890 + +References related issue PROJ-789 for context. +``` + +### Example 3: Possible Regression + +**User Input:** +``` +Users can't upload files larger than 5MB, getting "Upload failed" error +``` + +**Process:** +1. Extract: "Upload failed", "5MB", "file upload" +2. Search: Find PROJ-234 (resolved 2 months ago) - exact same issue +3. Analyze: Was fixed but now happening again +4. Present: Possible regression, recommend new issue linked to old one +5. Execute: Create new issue, link to PROJ-234 as "may be caused by" +6. Confirm: PROJ-891 created with regression context + +**Output:** +``` +✅ New Issue Created (Possible Regression) + +PROJ-891 - File Upload: Upload failed for files >5MB (Regression?) +https://yoursite.atlassian.net/browse/PROJ-891 + +This may be a regression of PROJ-234, which was resolved 2 months ago. +Issue includes reference to original fix for investigation. +``` + +--- + +## When NOT to Use This Skill + +This skill is for **triaging bugs and errors only**. Do NOT use for: + +❌ Feature requests (use spec-to-backlog) +❌ General task creation (use capture-tasks-from-meeting-notes) +❌ Searching for information (use search-company-knowledge) +❌ Generating status reports (use generate-status-report) + +**Use this skill specifically for:** +✅ "Is this a duplicate bug?" +✅ "Triage this error message" +✅ "Has this been reported before?" +✅ "Create a bug ticket for this" + +--- + +## Quick Reference + +**Primary workflow:** Extract → Search → Analyze → Present → Execute → Confirm + +**Search tool:** `searchJiraIssuesUsingJql(cloudId, jql, fields, maxResults)` + +**Action tools:** +- `addCommentToJiraIssue(cloudId, issueIdOrKey, commentBody)` - Add to existing +- `createJiraIssue(cloudId, projectKey, issueTypeName, summary, description)` - Create new + +**Issue type:** Always prefer "Bug" for error reports, check with `getJiraProjectIssueTypesMetadata` + +**Remember:** +- Multiple searches catch more duplicates +- Present findings before acting +- Include error details and context +- Reference related issues +- Use "Bug" issue type when available diff --git a/plugins/atlassian-rovo/skills/triage-issue/agents/openai.yaml b/plugins/atlassian-rovo/skills/triage-issue/agents/openai.yaml new file mode 100644 index 00000000..101acc07 --- /dev/null +++ b/plugins/atlassian-rovo/skills/triage-issue/agents/openai.yaml @@ -0,0 +1,5 @@ +interface: + display_name: "Triage Issue" + short_description: "Find duplicates and prepare Jira bug reports" + icon_small: "./assets/app-icon.png" + icon_large: "./assets/app-icon.png" diff --git a/plugins/atlassian-rovo/skills/triage-issue/references/bug-report-templates.md b/plugins/atlassian-rovo/skills/triage-issue/references/bug-report-templates.md new file mode 100644 index 00000000..ff07c311 --- /dev/null +++ b/plugins/atlassian-rovo/skills/triage-issue/references/bug-report-templates.md @@ -0,0 +1,451 @@ +# Bug Report Templates + +High-quality bug report templates for different types of issues. + +--- + +## Template 1: Backend Error + +**Summary Format:** +``` +[Service/Component]: [Error Type] in [Functionality] +``` + +**Examples:** +- Payment API: NullPointerException in refund processing +- Auth Service: TimeoutError during token validation +- Database: Connection pool exhausted in user queries + +**Description Template:** +```markdown +## Issue Description +[Brief 1-2 sentence description] + +## Error Details +``` +[Error message or exception] +Stack trace: +[Stack trace if available] +``` + +## Environment +- **Service:** [e.g., Payment Service v2.3.4] +- **Environment:** [Production/Staging] +- **Server:** [e.g., us-east-1 pod-7] +- **Timestamp:** [When it occurred] + +## Steps to Reproduce +1. [Step 1] +2. [Step 2] +3. [Step 3] + +## Expected Behavior +[What should happen] + +## Actual Behavior +[What actually happens] + +## Impact +- **Frequency:** [e.g., Every time, 10% of requests] +- **Affected Requests:** [e.g., ~500 requests/hour] +- **User Impact:** [e.g., Refunds cannot be processed] + +## Logs +``` +[Relevant log excerpts] +``` + +## Related Issues +[Any similar past issues] + +--- +*Reported via automated triage* +``` + +--- + +## Template 2: Frontend/UI Issue + +**Summary Format:** +``` +[Platform] [Component]: [Symptom] +``` + +**Examples:** +- iOS App Login: Screen remains blank after successful auth +- Web Dashboard: Infinite loading spinner on reports +- Android App: Crash when uploading photos + +**Description Template:** +```markdown +## Issue Description +[Brief description of the visible problem] + +## Environment +- **Platform:** [iOS/Android/Web] +- **Version:** [App/Browser version] +- **OS:** [e.g., iOS 16.5, Windows 11, macOS 13] +- **Device:** [e.g., iPhone 14 Pro, Chrome on Desktop] + +## Steps to Reproduce +1. [Step 1] +2. [Step 2] +3. [Step 3] + +## Expected Behavior +[What should happen] + +## Actual Behavior +[What actually happens] + +## Visual Evidence +[Screenshots or screen recording if available] + +## User Impact +- **Frequency:** [e.g., Every time, Intermittent] +- **Affected Users:** [e.g., All iOS users, Only Safari users] +- **Severity:** [e.g., Cannot complete checkout, Minor visual glitch] + +## Console Errors +``` +[Browser console errors if applicable] +``` + +## Additional Context +[Network conditions, user permissions, etc.] + +## Related Issues +[Any similar past issues] + +--- +*Reported via automated triage* +``` + +--- + +## Template 3: Performance Issue + +**Summary Format:** +``` +[Component]: [Performance Problem] - [Context] +``` + +**Examples:** +- Dashboard: Slow page load (15+ seconds) on reports +- API: Response time degradation under load +- Database: Query timeout on user search + +**Description Template:** +```markdown +## Issue Description +[Brief description of the performance problem] + +## Performance Metrics +- **Current:** [e.g., 15 second load time] +- **Expected:** [e.g., < 2 seconds] +- **Baseline:** [e.g., Was 1.5s last week] + +## Environment +- **Platform:** [Where observed] +- **Environment:** [Production/Staging] +- **Time Observed:** [When it was slow] +- **Load:** [Concurrent users, request rate] + +## Steps to Reproduce +1. [Step 1] +2. [Step 2] +3. Observe slow response + +## Performance Data +``` +[Response times, profiling data, slow query logs] +``` + +## Impact +- **Affected Users:** [e.g., All users during peak hours] +- **Frequency:** [e.g., Consistently slow, Only during peak] +- **Business Impact:** [e.g., Increased bounce rate, User complaints] + +## Suspected Cause +[If you have a hypothesis] + +## Related Issues +[Any similar past performance issues] + +--- +*Reported via automated triage* +``` + +--- + +## Template 4: Data Issue + +**Summary Format:** +``` +[Component]: [Data Problem] - [Scope] +``` + +**Examples:** +- User Profile: Data not persisting after save +- Orders: Missing order items in history +- Reports: Incorrect calculations in revenue report + +**Description Template:** +```markdown +## Issue Description +[Brief description of the data problem] + +## Data Issue Details +- **What's Wrong:** [e.g., Orders missing from history] +- **Expected Data:** [What should be there] +- **Actual Data:** [What is actually there] +- **Data Loss/Corruption:** [Scope of issue] + +## Environment +- **Environment:** [Production/Staging] +- **Affected Records:** [e.g., All orders from Dec 1-5] +- **First Observed:** [When issue started] + +## Steps to Reproduce +1. [Step 1] +2. [Step 2] +3. Observe incorrect/missing data + +## Examples +**Affected Record:** Order #12345 +**Expected:** [Expected data state] +**Actual:** [Actual data state] + +## Impact +- **Affected Users:** [e.g., ~500 customers] +- **Data Integrity:** [e.g., Historical data lost] +- **Business Impact:** [e.g., Cannot fulfill orders] + +## Database Queries +```sql +[Queries showing the issue if applicable] +``` + +## Related Issues +[Any similar past data issues] + +--- +*Reported via automated triage* +``` + +--- + +## Template 5: Integration Issue + +**Summary Format:** +``` +[Integration]: [Error] - [External Service] +``` + +**Examples:** +- Stripe Integration: Payment processing fails +- Auth0: Token validation timeout +- Sendgrid: Email sending fails with 429 error + +**Description Template:** +```markdown +## Issue Description +[Brief description of the integration problem] + +## Integration Details +- **External Service:** [e.g., Stripe API] +- **Integration Point:** [e.g., Payment processing endpoint] +- **API Version:** [If known] + +## Error Response +``` +HTTP Status: [e.g., 429, 500] +Response Body: +[Error response from external service] +``` + +## Environment +- **Environment:** [Production/Staging] +- **Our Version:** [Our service version] +- **Time Observed:** [When it started failing] + +## Steps to Reproduce +1. [Step that triggers integration] +2. [Expected external service response] +3. Observe failure + +## Expected Behavior +[What should happen with external service] + +## Actual Behavior +[What is actually happening] + +## Impact +- **Frequency:** [e.g., 100% of payment attempts] +- **Affected Transactions:** [e.g., ~200 failed payments/hour] +- **User Impact:** [e.g., Cannot complete checkout] + +## External Service Status +[Check if external service has known issues] + +## Logs +``` +[Our logs showing the integration failure] +``` + +## Related Issues +[Any past integration issues with this service] + +--- +*Reported via automated triage* +``` + +--- + +## Template 6: Regression (Previously Fixed) + +**Summary Format:** +``` +[Component]: [Issue] - Regression of PROJ-XXX +``` + +**Examples:** +- Login: Session timeout after 15min - Regression of PROJ-234 +- Upload: File size limit error - Regression of PROJ-567 + +**Description Template:** +```markdown +## Issue Description +[Brief description - note this was previously fixed] + +⚠️ **This appears to be a regression of [PROJ-XXX]**, which was resolved on [date]. + +## Original Issue +**Original Ticket:** [PROJ-XXX](link) +**Originally Fixed By:** @username +**Fix Date:** [date] +**Original Fix:** [Brief description of what was fixed] + +## Current Issue +[Description of the current occurrence] + +## Environment +- **Environment:** [Production/Staging] +- **Version:** [Current version] +- **First Observed:** [When regression appeared] + +## Steps to Reproduce +1. [Step 1] +2. [Step 2] +3. Observe issue is back + +## Expected Behavior +[Should remain fixed as per PROJ-XXX] + +## Actual Behavior +[Issue has returned] + +## Impact +[Current impact of regression] + +## Possible Causes +[Speculation about what might have caused regression] +- Recent deployment on [date]? +- Configuration change? +- Dependency update? + +## Investigation Needed +- Review changes since original fix +- Check if original fix was rolled back +- Verify fix is still in codebase + +## Related Issues +- **Original Issue:** [PROJ-XXX](link) +[Any other related issues] + +--- +*Reported via automated triage - Possible Regression* +``` + +--- + +## Summary Writing Best Practices + +### Good Summaries + +✅ **Specific and actionable:** +- "Payment API: NullPointerException in refund processing" +- "iOS App: Crash when uploading photos >5MB" +- "Dashboard: 15s load time on revenue report" + +✅ **Includes component:** +- Start with the affected component/system +- Makes it easy to filter and assign + +✅ **Describes the problem:** +- Use clear, technical language +- Avoid vague terms + +### Bad Summaries + +❌ **Too vague:** +- "Error in production" +- "App crashes sometimes" +- "Something is slow" + +❌ **Too long:** +- "Users are reporting that when they try to login on the mobile app using their email and password, the app shows a connection timeout error and they cannot proceed" + +❌ **Missing component:** +- "NullPointerException in refund" (what component?) +- "Page won't load" (which page?) + +--- + +## Description Writing Best Practices + +### Good Practices + +✅ **Use structured format** with headers +✅ **Include complete error messages** in code blocks +✅ **Provide context** (environment, version, time) +✅ **List concrete steps** to reproduce +✅ **Quantify impact** (affected users, frequency) +✅ **Add relevant logs** in code blocks +✅ **Reference related issues** with links + +### What to Avoid + +❌ Pasting entire stack traces without context +❌ Vague descriptions like "it doesn't work" +❌ Missing environment information +❌ No reproduction steps +❌ Formatting errors/code without code blocks +❌ Forgetting to mention user impact + +--- + +## Field Guidelines + +### Priority Selection + +**Highest:** System down, data loss, security issue +**High:** Major functionality broken, large user impact +**Medium:** Feature partially broken, moderate impact +**Low:** Minor issue, cosmetic, workaround available + +### Component Selection + +Always specify the affected component if the project uses components: +- Makes routing to correct team easier +- Helps with duplicate detection +- Improves searchability + +### Labels (If Available) + +Consider adding labels: +- `regression` - Previously fixed issue +- `production` - Occurring in production +- `data-loss` - Involves data loss/corruption +- `performance` - Performance related +- `mobile-ios` / `mobile-android` - Platform specific diff --git a/plugins/atlassian-rovo/skills/triage-issue/references/search-patterns.md b/plugins/atlassian-rovo/skills/triage-issue/references/search-patterns.md new file mode 100644 index 00000000..8d70db65 --- /dev/null +++ b/plugins/atlassian-rovo/skills/triage-issue/references/search-patterns.md @@ -0,0 +1,261 @@ +# Search Patterns for Duplicate Detection + +Effective JQL patterns for finding duplicate bugs and similar issues. + +--- + +## Error-Based Search Patterns + +### Exception Searches + +**For Java/Backend exceptions:** +```jql +project = "PROJ" AND text ~ "NullPointerException" AND type = Bug ORDER BY created DESC +``` + +**For specific class/method:** +```jql +project = "PROJ" AND text ~ "PaymentProcessor processRefund" AND type = Bug ORDER BY created DESC +``` + +**For HTTP errors:** +```jql +project = "PROJ" AND (text ~ "500 error" OR summary ~ "500") AND type = Bug ORDER BY updated DESC +``` + +### Timeout Searches + +**General timeout:** +```jql +project = "PROJ" AND (text ~ "timeout" OR summary ~ "timeout") AND type = Bug ORDER BY priority DESC +``` + +**Specific timeout type:** +```jql +project = "PROJ" AND text ~ "connection timeout" AND component = "API" ORDER BY created DESC +``` + +--- + +## Component-Based Search Patterns + +### By System Component + +**Authentication:** +```jql +project = "PROJ" AND text ~ "authentication login" AND type = Bug AND status != Done +``` + +**Payment:** +```jql +project = "PROJ" AND (component = "Payment" OR text ~ "payment checkout") AND type = Bug +``` + +**Mobile:** +```jql +project = "PROJ" AND (text ~ "mobile iOS" OR text ~ "mobile Android") AND type = Bug ORDER BY updated DESC +``` + +### By Functionality + +**Upload/Download:** +```jql +project = "PROJ" AND (text ~ "upload" OR text ~ "download") AND type = Bug +``` + +**Database:** +```jql +project = "PROJ" AND text ~ "database query SQL" AND type = Bug ORDER BY created DESC +``` + +--- + +## Symptom-Based Search Patterns + +### User-Facing Symptoms + +**Page/Screen issues:** +```jql +project = "PROJ" AND (summary ~ "blank page" OR summary ~ "white screen") AND type = Bug +``` + +**Loading issues:** +```jql +project = "PROJ" AND (summary ~ "infinite loading" OR summary ~ "stuck loading") AND type = Bug +``` + +**Data issues:** +```jql +project = "PROJ" AND (summary ~ "data not saving" OR summary ~ "data lost") AND type = Bug +``` + +### Performance Symptoms + +**Slow performance:** +```jql +project = "PROJ" AND (text ~ "slow" OR summary ~ "performance") AND type = Bug ORDER BY priority DESC +``` + +**Crashes:** +```jql +project = "PROJ" AND (summary ~ "crash" OR text ~ "application crash") AND type = Bug ORDER BY created DESC +``` + +--- + +## Time-Based Search Patterns + +### Recent Issues (Last 30 Days) + +```jql +project = "PROJ" AND text ~ "error keywords" AND type = Bug AND created >= -30d ORDER BY created DESC +``` + +### Recently Updated + +```jql +project = "PROJ" AND text ~ "error keywords" AND type = Bug AND updated >= -7d ORDER BY updated DESC +``` + +### Recently Resolved + +```jql +project = "PROJ" AND text ~ "error keywords" AND type = Bug AND status = Done AND resolved >= -90d ORDER BY resolved DESC +``` + +--- + +## Combined Search Patterns + +### High-Priority Recent + +```jql +project = "PROJ" AND text ~ "error" AND type = Bug AND priority IN ("Highest", "High") AND created >= -60d ORDER BY priority DESC, created DESC +``` + +### Component + Error Type + +```jql +project = "PROJ" AND component = "API" AND text ~ "timeout" AND type = Bug ORDER BY updated DESC +``` + +### Environment-Specific + +```jql +project = "PROJ" AND text ~ "production" AND text ~ "error keywords" AND type = Bug ORDER BY created DESC +``` + +--- + +## Advanced Patterns for Regression Detection + +### Previously Resolved + +```jql +project = "PROJ" AND text ~ "error keywords" AND type = Bug AND status = Done AND resolution = Fixed ORDER BY resolved DESC +``` + +### Reopened Issues + +```jql +project = "PROJ" AND text ~ "error keywords" AND type = Bug AND status = Reopened ORDER BY updated DESC +``` + +### Similar Fix History + +```jql +project = "PROJ" AND text ~ "error keywords" AND type = Bug AND (status = Resolved OR status = Closed) AND resolved >= -180d ORDER BY resolved DESC +``` + +--- + +## Multi-Angle Search Strategy + +For thorough duplicate detection, run searches in this order: + +**1. Exact error signature (narrow):** +```jql +project = "PROJ" AND summary ~ "exact error text" AND type = Bug ORDER BY created DESC +``` + +**2. Error type + component (medium):** +```jql +project = "PROJ" AND text ~ "error type" AND component = "ComponentName" AND type = Bug ORDER BY updated DESC +``` + +**3. Symptom-based (broad):** +```jql +project = "PROJ" AND summary ~ "user symptom" AND type = Bug ORDER BY priority DESC +``` + +**4. Historical (regression check):** +```jql +project = "PROJ" AND text ~ "keywords" AND type = Bug AND status = Done ORDER BY resolved DESC +``` + +--- + +## Field Selection for Triage + +Always request these fields for effective analysis: + +``` +fields: ["summary", "description", "status", "resolution", "priority", "created", "updated", "resolved", "assignee", "reporter", "components"] +``` + +**Why each field matters:** +- `summary` - Quick identification of duplicate +- `description` - Detailed error matching +- `status` - Know if open/resolved +- `resolution` - How it was fixed (if resolved) +- `priority` - Severity assessment +- `created` - Age of issue +- `updated` - Recent activity +- `resolved` - When it was fixed +- `assignee` - Who fixed it or is working on it +- `reporter` - Original reporter +- `components` - Affected system parts + +--- + +## Tips for Better Search Results + +### Use Key Terms Only + +✅ Good: +- "timeout login" +- "NullPointerException PaymentProcessor" +- "500 error API" + +❌ Too Verbose: +- "users are experiencing a timeout when trying to login" +- "we got a NullPointerException in the PaymentProcessor class" + +### Combine Searches + +Don't rely on a single search. Run 2-3 searches with different angles: +1. Error-focused +2. Component-focused +3. Symptom-focused + +### Order Strategically + +- Recent first: `ORDER BY created DESC` +- Active first: `ORDER BY updated DESC` +- Important first: `ORDER BY priority DESC, updated DESC` + +### Limit Results + +- Use `maxResults=20` for initial searches +- Don't overwhelm with 100+ results +- Focus on top 10-15 most relevant + +--- + +## Common Pitfalls to Avoid + +❌ Searching with full stack traces (too specific, no matches) +❌ Using only exact text matching (miss paraphrased duplicates) +❌ Ignoring resolved issues (miss regressions) +❌ Not checking multiple projects (duplicate across teams) +❌ Only searching summaries (miss details in descriptions)