Add jira:refine command for enhancing partially defined issues#281
Add jira:refine command for enhancing partially defined issues#281rvanderp3 wants to merge 1 commit intoopenshift-eng:mainfrom
Conversation
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: rvanderp3 The full list of commands accepted by this bot can be found here. The pull request process is described here DetailsNeeds approval from an approver in each of these files:
Approvers can indicate their approval by writing |
openshift-ci
bot
added
the
approved
WalkthroughAdds a new Jira plugin command Changes
Sequence Diagram(s)sequenceDiagram
participant User
participant Assistant
participant MCP
participant JiraAPI
participant SecurityService
User->>Assistant: /jira:refine ISSUE-123 [ISSUE-456]
Assistant->>MCP: request issue details (ISSUE-123, ISSUE-456)
MCP->>JiraAPI: GET /issues
JiraAPI-->>MCP: issue payloads
MCP-->>Assistant: aggregated issue data
Assistant->>Assistant: analyze, generate refinement plan
Assistant->>SecurityService: validate proposed changes
SecurityService-->>Assistant: validation result
Assistant->>User: present plan / request clarifications
User->>Assistant: approve / provide info
Assistant->>MCP: apply updates (PATCH issues)
MCP->>JiraAPI: update issues
JiraAPI-->>MCP: update confirmations
MCP-->>Assistant: result summary
Assistant->>User: final refinement summary
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes 🚥 Pre-merge checks | ✅ 8✅ Passed checks (8 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. Comment |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 8
🤖 Fix all issues with AI agents
In @docs/data.json:
- Around line 135-140: The registry entry for the "refine" command should list
bugs and support batch keys: update the "description" value to say "Refine
partially defined JIRA stories, tasks, and bugs with complete descriptions and
acceptance criteria", change "argument_hint" to indicate multiple keys (for
example "<issue-key> [<issue-key>...]" or "<issue-key>..."), and update
"synopsis" to "/jira:refine <issue-key> [<issue-key>...]" so the documented
fields (argument_hint, synopsis, and description) match the actual
multi-issue/batch capability of the refine handler.
- Around line 135-140: Update the "refine" command synopsis in docs/data.json to
show batch-mode support by changing "synopsis": "/jira:refine <issue-key>" to
include optional additional keys (e.g., "/jira:refine <issue-key>
[additional-keys...]"); ensure you edit the JSON object with name "refine" (the
same entry that references the refine-issue skill) so docs reflect the
documented batch capability.
In @PLUGINS.md:
- Around line 167-168: Update the `/jira:refine` scope text to consistently
reflect that it covers bugs as well as stories and tasks; change the description
for **`/jira:refine` `<issue-key>`** to mention "issues (stories, tasks, and
bugs)" or simply "issues" so it matches other references in the PR.
In @plugins/jira/commands/refine.md:
- Around line 9-12: The fenced code blocks in plugins/jira/commands/refine.md
(e.g., the Synopsis block containing ```/jira:refine <issue-key>``` and other
blocks in the listed ranges) are missing language identifiers and trigger
markdownlint MD040; update each fenced block by adding an appropriate language
tag (for example `text`, `bash`, or `console`) after the opening ``` so they
become ```text or ```bash as applicable, ensuring all occurrences in the ranges
110-131, 252-266, 271-293, 345-350, 357-369, 375-380, 387-396, 403-415, and
429-452 are fixed.
- Around line 66-69: There is an inconsistency between the skill identifier
strings: the doc refers to `jira:refine-issue` in some places but the registry
and other references use `refine-issue`; update all occurrences to use the
canonical skill id `refine-issue` (replace `jira:refine-issue` with
`refine-issue` in the Phase 1 description and the later block around lines
471-476) so the skill name/id is consistent throughout the document and matches
the registry.
- Around line 1-4: The documentation claims batch refinement but the
argument-hint is single-argument; either make the command and registry
explicitly support multiple keys by changing argument-hint to "<issue-key>
[issue-key ...]" and update PLUGINS.md examples and any registry/handler code to
accept and iterate multiple keys, or remove the batch refinement example and the
"$2, $3, ..." references from PLUGINS.md and the refine command docs so they
consistently document single-key behavior; ensure argument-hint and
registry/documentation text match the implemented mode.
In @plugins/jira/skills/refine-issue/SKILL.md:
- Around line 268-272: Several fenced code blocks in SKILL.md are missing
language identifiers (e.g., the block starting with "Summary: Add metrics
endpoint"); update those fences to include an appropriate language tag to
satisfy markdownlint MD040. For the key: value metadata blocks (like "Summary:
..." / "Description: ...") use ```yaml, for command examples use ```bash/sh, for
JSON payloads use ```json and for diffs use ```diff; apply these changes to the
other missing fences flagged in the review so every triple-backtick fence has a
matching language identifier.
🧹 Nitpick comments (1)
plugins/jira/commands/refine.md (1)
74-94: Doc examples: avoid implying hard-coded customfield IDs / nulling fields in update payload.
- The
customfield_123…IDs are instance/project-specific; consider a note that these vary and should be discovered/configured.- In the update example,
components: ... if component else Nonemay be rejected by many APIs; better to omit the field entirely when not setting it.Proposed doc tweak (illustrative)
- fields={ - "description": "<refined description with proper format>", - "priority": {"name": "<priority>"}, - "components": [{"name": "<component>"}] if component else None - }, + fields={ + "description": "<refined description with proper format>", + "priority": {"name": "<priority>"}, + # Only include components when setting/updating them; omit otherwise. + **({"components": [{"name": "<component>"}]} if component else {}), + }, additional_fields={ - "customfield_12310243": <story-points> if applicable, - "customfield_12311140": "<epic-key>" if epic link needed, + # NOTE: customfield_* IDs vary by Jira instance/project; discover/configure these per environment. + "customfield_12310243": <story-points> if applicable, + "customfield_12311140": "<epic-key>" if epic link needed, "labels": <existing-labels> + ["refined-by-ai"] if not present } )Also applies to: 225-240
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Cache: Disabled due to data retention organization setting
Knowledge base: Disabled due to data retention organization setting
📒 Files selected for processing (4)
PLUGINS.mddocs/data.jsonplugins/jira/commands/refine.mdplugins/jira/skills/refine-issue/SKILL.md
🧰 Additional context used
🪛 markdownlint-cli2 (0.18.1)
plugins/jira/skills/refine-issue/SKILL.md
268-268: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
274-274: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
510-510: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
548-548: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
566-566: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
642-642: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
688-688: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
709-709: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
727-727: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
744-744: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
782-782: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
787-787: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
793-793: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
798-798: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
plugins/jira/commands/refine.md
10-10: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
110-110: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
252-252: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
271-271: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
277-277: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
283-283: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
289-289: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
345-345: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
357-357: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
375-375: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
387-387: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
403-403: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
429-429: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
435-435: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
441-441: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
447-447: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (3)
docs/data.json (1)
235-239: Skill registration LGTM (id/name/path are coherent).
id: "refine-issue"matches the directory naming and the command docs’ “Skills Reference” intent.plugins/jira/skills/refine-issue/SKILL.md (2)
20-35: “Enhancement, not replacement” guidance is strong and clear.This is exactly the constraint needed to keep refinement safe for human-authored tickets.
12-19: No issues identified. The claim that this skill is automatically invoked by the/jira:refinecommand is accurate. The command documentation atplugins/jira/commands/refine.mdexplicitly describes Phase 1 as: "Invoke thejira:refine-issueskill using the Skill tool to load refinement best practices and workflows."
PLUGINS.md
Outdated
| - **`/jira:refine` `<issue-key>`** - Refine partially defined JIRA stories and tasks with complete descriptions and acceptance criteria | ||
| - **`/jira:solve`** - Analyze a JIRA issue and create a pull request to solve it. |
There was a problem hiding this comment.
Nice addition; consider aligning scope wording (stories/tasks vs bugs).
Elsewhere in this PR, the refinement capability is described as covering bugs too; here it’s “stories and tasks” only. If /jira:refine supports bugs, consider updating this line to avoid mixed messaging.
🤖 Prompt for AI Agents
In @PLUGINS.md around lines 167 - 168, Update the `/jira:refine` scope text to
consistently reflect that it covers bugs as well as stories and tasks; change
the description for **`/jira:refine` `<issue-key>`** to mention "issues
(stories, tasks, and bugs)" or simply "issues" so it matches other references in
the PR.
rvanderp3
force-pushed
the
refine-skill
branch
from
0477c6d to
c996e69
Compare
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Fix all issues with AI agents
In @docs/data.json:
- Around line 135-140: Update the JSON entry for the refine command so the
"synopsis" field matches the real CLI usage instead of "bash": set "synopsis" to
the actual command form shown by the command docs (e.g., "jira refine
<issue-key> [<issue-key>...]") so it aligns with the "argument_hint" and the
documentation in plugins/jira/commands/refine.md for the "refine" command.
In @plugins/jira/commands/refine.md:
- Around line 9-12: Update the Synopsis section in the
plugins/jira/commands/refine.md to indicate multi-issue support by changing the
example command in the code block from a single issue key to allow multiple keys
(replace "/jira:refine <issue-key>" with "/jira:refine <issue-key>
[<issue-key>...]"); edit the code block under the "Synopsis" heading so it
matches the argument-hint and the batch refinement example elsewhere in the
file.
In @plugins/jira/skills/refine-issue/SKILL.md:
- Around line 71-79: The summary handling currently calls summary.split() and
summary.lower() without checking for None; update the logic around the
summary_issues branch to first guard when summary is None (or falsy) — e.g., if
summary is None: add a "Missing summary" (or treat as empty string) to
summary_issues and skip the split()/lower() checks; otherwise perform the
existing length and startswith checks using summary.split() and summary.lower();
ensure you reference and update the same summary_issues list and the variable
summary used in this block.
🧹 Nitpick comments (1)
plugins/jira/skills/refine-issue/SKILL.md (1)
268-289: Consider adding language specifiers to fenced code blocks.The example blocks would benefit from language hints for better rendering and accessibility. While they contain example Jira content rather than code, specifying
textas the language improves tooling support.Based on static analysis hints.
♻️ Proposed enhancement
**Before:** -``` +```text Summary: Add metrics endpoint Description: Need to expose cluster health metricsAfter:
-+text
Summary: Add metrics endpoint for cluster health
Description:
As a cluster administrator, I want to query cluster health metrics via an API endpoint, so that I can monitor cluster status programmatically.</details> </blockquote></details> </blockquote></details> <details> <summary>📜 Review details</summary> **Configuration used**: Path: .coderabbit.yaml **Review profile**: CHILL **Plan**: Pro **Cache: Disabled due to data retention organization setting** **Knowledge base: Disabled due to data retention organization setting** <details> <summary>📥 Commits</summary> Reviewing files that changed from the base of the PR and between 0477c6d0ee2aaf182e8e19ab2a1f3f0bd1266a09 and c996e6913cd9a79ef6b0a7e82add6e085fc3306f. </details> <details> <summary>📒 Files selected for processing (4)</summary> * `PLUGINS.md` * `docs/data.json` * `plugins/jira/commands/refine.md` * `plugins/jira/skills/refine-issue/SKILL.md` </details> <details> <summary>🚧 Files skipped from review as they are similar to previous changes (1)</summary> * PLUGINS.md </details> <details> <summary>🧰 Additional context used</summary> <details> <summary>🪛 markdownlint-cli2 (0.18.1)</summary> <details> <summary>plugins/jira/skills/refine-issue/SKILL.md</summary> 268-268: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- 274-274: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- 510-510: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- 548-548: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- 566-566: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- 642-642: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- 688-688: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- 709-709: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- 727-727: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- 744-744: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- 782-782: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- 787-787: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- 793-793: Fenced code blocks should have a language specified (MD040, fenced-code-language) --- 798-798: Fenced code blocks should have a language specified (MD040, fenced-code-language) </details> </details> </details> <details> <summary>🔇 Additional comments (9)</summary><blockquote> <details> <summary>docs/data.json (1)</summary><blockquote> `235-239`: **LGTM!** The skill metadata entry is correctly structured and aligns with the skill documentation at `plugins/jira/skills/refine-issue/SKILL.md`. </blockquote></details> <details> <summary>plugins/jira/skills/refine-issue/SKILL.md (4)</summary><blockquote> `1-35`: **Excellent foundational principles.** The core principle section clearly establishes enhancement over replacement, which is critical for a refinement tool. The explicit do's and don'ts provide clear guidance. --- `506-657`: **Excellent interactive workflow examples.** The step-by-step workflow with concrete examples effectively demonstrates the refinement process. The preview-before-apply pattern is a great user experience choice. --- `682-812`: **Comprehensive error handling and anti-patterns guidance.** The error scenarios cover the common edge cases well, and the anti-patterns section provides concrete examples of what to avoid with clear alternatives. --- `813-828`: **LGTM!** Clear workflow summary and helpful cross-references to related documentation. </blockquote></details> <details> <summary>plugins/jira/commands/refine.md (4)</summary><blockquote> `1-24`: **Clear and user-focused introduction.** The command description effectively communicates the purpose and practical use cases for the refine command. --- `268-337`: **Excellent usage examples and quality indicators.** The examples cover single and batch refinement scenarios effectively, and the quality indicators provide clear success criteria for different issue types. --- `338-416`: **Comprehensive and user-friendly error handling.** The error scenarios are well-covered with clear, actionable guidance. The security validation scenario is particularly important for preventing accidental credential exposure. --- `417-480`: **LGTM!** Best practices, anti-patterns, and workflow summary provide excellent guidance. The skills reference helps users understand the implementation details if needed. </blockquote></details> </blockquote></details> </details> <!-- This is an auto-generated comment by CodeRabbit for review status -->
Introduce new /jira:refine subcommand that intelligently enhances incomplete or under-specified JIRA stories, tasks, and bugs by adding missing critical information while preserving existing good content. Key capabilities: - Analyzes issue quality (description, acceptance criteria, fields) - Adds user story format for stories (As a... I want... So that...) - Generates testable acceptance criteria based on context - Sets missing fields (priority, component, story points, epic links) - Provides interactive refinement workflow with preview - Preserves existing content - enhancement, not replacement This complements the jira:create command by helping teams improve backlog quality during grooming sessions and convert stub tickets from automation into actionable work items. Files added: - plugins/jira/commands/refine.md - plugins/jira/skills/refine-issue/SKILL.md 🤖 Generated with [Claude Code](https://claude.com/claude-code)
rvanderp3
force-pushed
the
refine-skill
branch
from
c996e69 to
c08e523
Compare
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (2)
plugins/jira/skills/refine-issue/SKILL.md (1)
271-277: Add language specifiers to all code blocks for syntax highlighting.Multiple code blocks are missing language identifiers, which affects readability and markdown compliance. Apply language tags consistently throughout:
pythonfor Python code,bashfor shell commands, andtextfor interactive prompts/output examples.♻️ Proposed fixes for all code block language specifiers
Lines 271-277 (Before/After example blocks):
-**Before:** -``` +**Before:** +```textAnd correspondingly for the After: block at line 277.
Lines 513-545 (Interactive workflow example):
-``` +```text Analyzing PROJ-123...Lines 551-565 (Information collection prompt):
-``` +```text I need a bit more information to complete the refinement:Lines 569-601 (Preview example):
-``` +```text Preview of changes to PROJ-123:Lines 645-659 (Results/status output):
-``` +```text ✅ Successfully refined PROJ-123Lines 691-705 (Error handling prompt):
-``` +```text I need help understanding this story better to add the user story format:Lines 712-723 (Component selection prompt):
-``` +```text I couldn't automatically detect the component for this issue.Lines 730-740 (Issue type mismatch prompt):
-``` +```text This issue is currently a Task, but the description suggests user-facing functionalityLines 747-760 (Already well-defined scenario):
-``` +```text PROJ-123 analysis:Lines 785-814 (Anti-pattern examples):
-```python +```python description = auto_generated_template # Overwrites everything!And for the "Generic acceptance criteria" anti-pattern:
-``` +```text * Test that it worksAnd the "good" acceptance criteria example:
-``` +```text * Test that API response time is < 200ms for 95% of requestsAnd for scope change examples:
-``` +```text Original: "Add metrics endpoint"And the existing structure example:
-```python +```python description = new_template # Loses existing h2 sections and formattingAlso applies to: 513-545, 551-565, 569-601, 645-659, 691-705, 712-723, 730-740, 747-760, 785-814
plugins/jira/commands/refine.md (1)
345-350: Add language specifiers to error handling and example text blocks.Text blocks in error handling and anti-pattern sections lack language identifiers. Apply
texttag to all interactive prompt and output examples for consistency with markdown best practices.♻️ Proposed fixes for code block language specifiers
Lines 345-350 (Issue not found error):
-**Action:** -```text +**Action:** +```text Issue MYPROJECT-999 not found.Lines 357-368 (Already well-defined scenario):
-**Action:** -```text +**Action:** +```text MYPROJECT-123 appears to be well-defined already:Lines 375-380 (Conflicting information):
-**Action:** -```text +**Action:** +```text The summary "Enable user dashboard" suggests user-facing functionality,Lines 387-396 (Missing permissions):
-**Action:** -```text +**Action:** +```text You don't have permission to edit MYPROJECT-123.Lines 403-415 (Security validation failure):
-**Action:** -```text +**Action:** +```text I detected what appears to be an API token in the generated content.Lines 429-432 and 435-438 (Anti-patterns – over-refinement):
-```text +```text Adding 20 acceptance criteria and pages of contextAnd the "Keep it right-sized" example:
-✅ Keep it right-sized for a sprint (3-7 AC typically sufficient) +✅ Keep it right-sized for a sprint (3-7 AC typically sufficient)Lines 441-444 (Anti-pattern – removing user content):
-```text +```text Deleting comments or attachments added by teamLines 448-451 (Generic acceptance criteria anti-pattern):
-```text +```text - Test that it worksAlso applies to: 357-368, 375-380, 387-396, 403-415, 429-432, 435-438, 441-444, 448-451
📜 Review details
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Cache: Disabled due to data retention organization setting
Knowledge base: Disabled due to data retention organization setting
📒 Files selected for processing (4)
PLUGINS.mddocs/data.jsonplugins/jira/commands/refine.mdplugins/jira/skills/refine-issue/SKILL.md
🚧 Files skipped from review as they are similar to previous changes (2)
- PLUGINS.md
- docs/data.json
🧰 Additional context used
🪛 markdownlint-cli2 (0.18.1)
plugins/jira/skills/refine-issue/SKILL.md
271-271: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
277-277: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
513-513: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
551-551: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
569-569: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
645-645: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
691-691: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
712-712: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
730-730: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
747-747: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
785-785: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
790-790: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
796-796: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
801-801: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (2)
plugins/jira/skills/refine-issue/SKILL.md (1)
1-100: Comprehensive and well-structured skill documentation.The implementation guide provides clear phases (fetch, analyze, plan, execute), concrete code examples for assessment logic, and explicit preservation guidelines emphasizing enhancement over replacement. The "Core Principle: Enhancement, Not Replacement" section (lines 20–35) is appropriately prominent, and error handling scenarios are practical.
plugins/jira/commands/refine.md (1)
1-100: Clear, user-focused command documentation with practical workflows.The command guide effectively presents the multi-phase refinement process in accessible language, with concrete quality indicators (lines 309–337) and usage examples covering all issue types. The integration with the refine-issue skill and consistent error handling make this documentation ready for users.
1 participant
Add jira:refine command for enhancing partially defined issues
Introduce new /jira:refine subcommand that intelligently enhances
incomplete or under-specified JIRA stories, tasks, and bugs by adding
missing critical information while preserving existing good content.
Key capabilities:
This complements the jira:create command by helping teams improve
backlog quality during grooming sessions and convert stub tickets
from automation into actionable work items.
Files added:
🤖 Generated with Claude Code
Checklist:
Summary by CodeRabbit
New Features
Documentation
✏️ Tip: You can customize this high-level summary in your review settings.