Fix critical field mapping and validation issues in jira:create plugin #163
Conversation
|
[APPROVALNOTIFIER] This PR is APPROVED This pull-request has been approved by: bryan-cox The full list of commands accepted by this bot can be found here. The pull request process is described here
Needs approval from an approver in each of these files:
Approvers can indicate their approval by writing |
WalkthroughAdds a new Phase 5.5 Summary Validation step, extends MCP error handling (epic-link and field-format fallbacks), clarifies summary vs description rules, and updates CNTRLPLANE skill conventions for epic linking, target version handling, field mappings and examples. Changes
Sequence Diagram(s)sequenceDiagram
autonumber
participant User
participant Summarizer as Summary Validator
participant Sec as Security Validator
participant MCP as MCP Tool
participant Skill as Project Skill (e.g., CNTRLPLANE)
User->>Summarizer: submit proposed summary
Summarizer-->>User: detect anti-patterns / too long
alt Auto-extract possible
Summarizer->>User: present concise alternative (accept/edit/keep)
User-->>Summarizer: choose action
else Manual edit
User-->>Summarizer: edit summary
end
Summarizer->>Sec: pass validated summary+description
Sec-->>MCP: request create issue
MCP->>MCP: attempt create (with Epic Link if provided)
alt Success
MCP-->>User: created
else Epic Link creation failure
MCP->>Skill: invoke project-specific fallback (create without epic / create epic then link / post-update)
Skill-->>MCP: fallback result (retry/update)
MCP-->>User: created (with fallback) or error
end
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes
Pre-merge checks and finishing touchesImportant Pre-merge checks failedPlease resolve all errors before merging. Addressing warnings is optional. ❌ Failed checks (1 inconclusive)
✅ Passed checks (6 passed)
✨ Finishing touches🧪 Generate unit tests (beta)
Comment |
openshift-merge-robot
added
the
needs-rebase
openshift-ci
bot
added
the
approved
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Nitpick comments (5)
plugins/jira/commands/create.md (1)
153-182: Add language identifiers to fenced code blocks (MD040).The Phase 5.5 Summary Validation section is well-structured and addresses a key issue. However, multiple code blocks lack language specifiers, which violates markdown linting standards.
Apply this diff to fix the linting violations:
**Check for anti-patterns:** 1. Summary starts with "As a" (user story format belongs in description) 2. Summary contains "I want" or "so that" (belongs in description) 3. Summary exceeds 100 characters (likely too long, may be full user story) **Action if anti-pattern detected:** 1. Detect that user put full user story in summary field 2. Extract the key action/feature from the summary 3. Generate a concise alternative (5-10 words) 4. Prompt user for confirmation: - ``` + ```text The summary looks like a full user story. Summaries should be concise titles. Current: "As a cluster admin, I want to configure ImageTagMirrorSet in HostedCluster CRs so that I can enable tag-based image proxying" Suggested: "Enable ImageTagMirrorSet configuration in HostedCluster CRs" Use the suggested summary? (yes/no/edit) - ``` + ```Additionally, review line 160 — it appears to be a standalone code block with no content. Consider consolidating or clarifying its purpose.
plugins/jira/skills/cntrlplane/SKILL.md (4)
33-70: Add language identifiers to code blocks and verify field IDs (MD040 + consistency check).The restructured Target Version section clearly communicates the optional nature of this field and provides helpful MCP API guidance. However, two Python code blocks lack language specifiers.
Apply this diff to fix the linting violations:
**If target version must be set:** 1. **First, fetch available versions:** - ```python + ```python versions = mcp__atlassian__jira_get_project_versions(project_key="CNTRLPLANE") - ``` + ``` 2. **Find the version ID** for the desired version (e.g., "openshift-4.21" has id "12448830") 3. **Use correct MCP format** (array of version objects with ID): - ```python + ```python "customfield_12319940": [{"id": "12448830"}] # openshift-4.21 - ``` + ```Additionally, verify that the field ID
customfield_12319940used here matches the reference increate.mdLine 464 (Field Format Error section) to ensure consistency across documentation.
71-177: Add language identifiers to all Python code blocks in Epic Link section (MD040).The Epic Link Requirements section is exceptional—it provides clear pre-validation logic, both preferred and fallback approaches, and actionable implementation guidance. However, 12 code blocks lack language specifiers.
Apply this diff to fix all violations in this section:
### MCP Format for Epic Link -```python +```python additional_fields={ "customfield_12311140": "CNTRLPLANE-123", # Epic Link (use actual epic key) "labels": ["ai-generated-jira"], "security": {"name": "Red Hat Employee"} } -``` +``` #### Pre-Validation (Do This First) Before attempting to create the issue: 1. Verify the parent epic exists using `mcp__atlassian__jira_get_issue` 2. If epic doesn't exist, prompt user: - ``` + ```text Epic {epic_key} not found. Options: 1. Proceed without epic link 2. Specify different epic 3. Cancel creation What would you like to do? - ``` + ``` #### Preferred Approach: Include Epic Link in Creation Attempt to create the issue with Epic Link included: -```python +```python mcp__atlassian__jira_create_issue( project_key="CNTRLPLANE", summary="<story title>", issue_type="Story", description="<description>", components="<component>", additional_fields={ "customfield_12311140": "<epic-key>", # Epic Link (e.g., "CNTRLPLANE-456") "labels": ["ai-generated-jira"], "security": {"name": "Red Hat Employee"} } ) -``` +``` #### Fallback Strategy (If Creation Fails) If creation fails with an error related to epic linking: 1. Detect error contains keywords: "epic", "parent", "customfield", or "link" 2. Inform user: "Epic link failed during creation, using fallback strategy..." 3. Create issue WITHOUT the epic link: - ```python + ```python story = mcp__atlassian__jira_create_issue( project_key="CNTRLPLANE", summary="<story title>", issue_type="Story", description="<description>", components="<component>", additional_fields={ "labels": ["ai-generated-jira"], "security": {"name": "Red Hat Employee"} } ) - ``` + ``` 4. If creation succeeds, link to epic via update: - ```python + ```python mcp__atlassian__jira_update_issue( issue_key=story["key"], fields={}, additional_fields={ "customfield_12311140": "<epic-key>" } ) - ``` + ``` 5. Inform user of success: - ``` + ```text Created: CNTRLPLANE-XXX Linked to epic: <epic-key> ✓ Title: <story title> URL: https://issues.redhat.com/browse/CNTRLPLANE-XXX - ``` + ``` #### If Fallback Also Fails If the update call to add Epic Link also fails: -``` +```text Story created: CNTRLPLANE-XXX ⚠️ Automatic epic linking failed. Please link manually in Jira. URL: https://issues.redhat.com/browse/CNTRLPLANE-XXX -``` +```This section directly addresses the CNTRLPLANE-1961 issue mentioned in the PR objectives.
215-321: Add language identifiers to all Python code blocks in MCP Tool Integration section (MD040).The MCP Tool Integration examples are comprehensive and well-commented, showing both primary and fallback approaches. However, 9 Python code blocks lack language specifiers.
Apply fixes for all violations—here are key examples:
### For CNTRLPLANE Stories **Basic story (no epic link):** -```python +```python mcp__atlassian__jira_create_issue( project_key="CNTRLPLANE", summary="<concise story title>", # NOT full user story format issue_type="Story", description="<formatted description with full user story and AC>", components="<component name>", # if required by team additional_fields={ "labels": ["ai-generated-jira"], "security": {"name": "Red Hat Employee"} } ) -``` +``` **Story linked to epic:** -```python +```python mcp__atlassian__jira_create_issue( project_key="CNTRLPLANE", summary="<concise story title>", # NOT full user story format issue_type="Story", description="<formatted description with full user story and AC>", components="<component name>", # if required by team additional_fields={ "customfield_12311140": "<epic-key>", # Epic Link (e.g., "CNTRLPLANE-456") "labels": ["ai-generated-jira"], "security": {"name": "Red Hat Employee"} } ) -``` +```Apply the same fix (add
pythonlanguage identifier) to remaining code blocks at lines 253, 263, 271, 273, and 295.
260-283: MD036 violation: Emphasis used instead of heading.Lines 260 and 271 use emphasis markers (
**) instead of proper heading syntax for section-like content:-**Basic epic (no parent feature):** +### Basic epic (no parent feature) -**Epic linked to parent feature:** +### Epic linked to parent featureAlternatively, if these should remain as subsection labels rather than headings, consider restructuring the content to make the table hierarchy clearer. This improves both linting compliance and document navigation.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
Plan: Pro
Cache: Disabled due to data retention organization setting
Knowledge base: Disabled due to Reviews -> Disable Knowledge Base setting
📒 Files selected for processing (3)
plugins/jira/commands/create.md(3 hunks)plugins/jira/skills/cntrlplane/SKILL.md(5 hunks)plugins/jira/skills/create-story/SKILL.md(4 hunks)
🧰 Additional context used
🪛 LanguageTool
plugins/jira/skills/create-story/SKILL.md
[style] ~37-~37: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...in description!) - ❌ "As a developer, I want to view metrics so that I can debug issues...
(REP_WANT_TO_VB)
🪛 markdownlint-cli2 (0.18.1)
plugins/jira/skills/cntrlplane/SKILL.md
46-46: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
86-86: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
103-103: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
107-107: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
111-111: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
143-143: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
148-148: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
155-155: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
160-160: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
167-167: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
172-172: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
221-221: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
227-227: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
233-233: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
238-238: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
253-253: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
260-260: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
263-263: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
271-271: Emphasis used instead of a heading
(MD036, no-emphasis-as-heading)
273-273: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
295-295: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
325-325: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
334-334: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
plugins/jira/commands/create.md
155-155: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
160-160: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
167-167: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
172-172: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
178-178: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
221-221: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
444-444: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
468-468: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
475-475: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
plugins/jira/skills/create-story/SKILL.md
46-46: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (10)
plugins/jira/skills/create-story/SKILL.md (6)
20-62: Excellent addition of critical Summary vs Description guidance.The new section directly addresses the stated #1 mistake and provides clear, actionable examples with visual indicators (✅/❌). The structure progresses logically from field definitions to good/bad examples to collection workflow, making it immediately useful for story creation.
356-357: Field Validation now reinforces the critical distinction.The updated validation criteria (lines 356–357) properly emphasize the 5–10 word limit for Summary and correctly reference the new Summary vs Description section. This creates a cohesive, self-reinforcing guidance structure.
376-436: MCP examples correctly updated with concise summaries and project-specific handling.The examples now demonstrate proper summary conciseness (line 406 example: ~7 words), clarify that target version is optional, and delegate epic linking to project-specific skills (line 436). These changes align with the PR objective to separate project-specific logic and provide accurate field documentation.
694-704: Verify Example 3 consistency with project-specific skill delegation.Example 3 demonstrates parent linking via
--parent CNTRLPLANE-100, but the updated guidance (line 436) now delegates epic linking to project-specific skills. Clarify whether this example should be retained as-is (with a note directing to project skills), revised to remove the --parent flag, or replaced with a different scenario.
46-46: Add language specifications to code blocks for consistent rendering.Code blocks lack language identifiers (Markdown linting issue MD040). At minimum, specify languages for the Python MCP examples:
- Line 376: Add
pythonlanguage identifier- Line 404: Add
pythonlanguage identifierApply this diff:
-```python +``` mcp__atlassian__jira_create_issue(Actually, the blocks do have
pythonspecified. Verify the linter is correctly parsing the markdown, as line 46's code block should also specify a language (currently plain ``` without identifier).Also applies to: 376-399, 404-434
35-38: Skip: Intentional repetition in "bad examples" section.LanguageTool flags repetitive "I want to" phrasing on lines 36–37, but this repetition is pedagogically justified—it demonstrates a consistent pattern of the primary mistake (using full user story format in the summary field). Retaining the repetition strengthens the instructional value.
Summary
This documentation update effectively addresses the PR objectives by establishing clear guidance on the critical Summary vs Description distinction, the #1 mistake when creating Jira stories. The new section (lines 20–62) provides excellent pedagogical support with clear examples, good/bad patterns, and actionable collection guidance.
Strengths:
- ✅ Comprehensive Summary vs Description section with visual indicators (✅/❌)
- ✅ Field Validation reinforces the distinction with explicit 5–10 word requirement
- ✅ MCP examples now demonstrate proper concise summaries
- ✅ Epic linking strategy properly delegated to project-specific skills (line 436)
Items to verify:
- Example 3 (lines 694–704) still references
--parentflag—confirm this aligns with the new project-specific skills delegation strategy- Code block formatting: markdownlint flags missing language identifiers; consider adding
pythonto Python code blocks for clarityplugins/jira/commands/create.md (2)
442-482: Add language identifiers to fenced code blocks in Error Handling sections (MD040).The new "Epic Link Creation Failure" and "Field Format Error" sections provide valuable guidance on handling creation failures and field formatting issues. However, several code blocks lack language specifiers.
Apply this diff to fix the linting violations:
### Epic Link Creation Failure **Scenario:** Story/task creation fails when including epic link field. **Action:** Refer to project-specific skills for epic linking fallback strategies: - **CNTRLPLANE:** See CNTRLPLANE skill "Epic Linking Implementation Strategy" section - **Other projects:** Consult project-specific skill documentation **General pattern:** -1. Detect error related to linking (error contains "epic", "parent", "link", or "customfield") +```text +1. Detect error related to linking (error contains "epic", "parent", "link", or "customfield") 2. Check project-specific skill for recommended fallback approach 3. Typically: Create without link, then link via update 4. Inform user of outcome +``` ### Field Format Error **Scenario:** Field provided in wrong format (e.g., Target Version as string instead of array). **Common field format errors:** 1. **Target Version format** - - ❌ Wrong: `"customfield_12319940": "openshift-4.21"` - - ✅ Correct: `"customfield_12319940": [{"id": "12448830"}]` + - ❌ Wrong: `"customfield_12319940": "openshift-4.21"` + - ✅ Correct: `"customfield_12319940": [{"id": "12448830"}]`Actually, reviewing this more carefully—lines 444, 468, and 475 appear to be part of a structured list rather than fenced code blocks. The MD040 violations may be false positives if these lines don't contain actual code blocks. Could you verify the actual linting output to confirm these are true violations?
483-491: Best Practices section is clear and comprehensive.The expanded best practices list effectively captures key concerns: efficiency (flags/version), hierarchy (parent links), quality (templates), and security (sanitize content). This aligns well with the PR's focus on improved validation and error handling.
plugins/jira/skills/cntrlplane/SKILL.md (2)
322-336: Field Mapping Reference table is well-structured and clear.The addition of the "Required?" column provides essential clarity on field requirements. The table effectively communicates the shift from required target version to optional, and emphasizes critical fields like Epic Link for stories. Field IDs and MCP parameters are clearly documented and match the implementation guidance above.
357-395: Examples section may be inconsistent with revised Target Version guidance.The Examples section (lines 357, 369, 381, 392) shows "Target Version: openshift-4.21" as a default in examples. However, the Target Version section (line 37) now states "Recommendation: Omit this field unless specifically required."
These statements conflict. Consider updating the example outputs to either:
- Remove the "Target Version: openshift-4.21" line from defaults shown, or
- Add a note: "Target Version: openshift-4.21 (optional—omit if not required by team)"
This ensures consistency with the revised optional-field guidance introduced in this PR.
…e plugin Fix documentation gaps discovered during CNTRLPLANE-1961 creation that caused multiple failures: epic linking, target version format, and summary validation. Changes: - Add Epic Link field (customfield_12311140) documentation to CNTRLPLANE skill - Fix Target Version to show correct MCP format (array with ID) or recommend omitting - Add prominent "Summary vs Description" warning to create-story skill - Add summary validation and epic linking fallback to create.md command - Consolidate duplicate content in create-story skill - Move CNTRLPLANE-specific logic from create.md to CNTRLPLANE skill - Replace real issue keys with generic placeholders in examples The changes ensure correct Epic Link usage, proper field formats, and clearer guidance on summary vs description to prevent common mistakes. Related: CNTRLPLANE-1961
bryan-cox
force-pushed
the
update-jira-create
branch
from
cdc5d4d to
16995a5
Compare
openshift-merge-robot
removed
the
needs-rebase
There was a problem hiding this comment.
Actionable comments posted: 3
🧹 Nitpick comments (1)
plugins/jira/commands/create.md (1)
463-476: Cross-file alignment excellent; error detection specificity could be improved.This section appropriately delegates epic linking fallback strategies to project-specific skills. The integration with CNTRLPLANE skill documentation (lines 96-177 in cntrlplane/SKILL.md) is well-aligned.
Suggestion for enhancement: Be more specific about error patterns. Line 473 says "error contains 'epic', 'parent', 'link', or 'customfield'" — this pattern could be referenced consistently in both the create.md error handling and the project-specific skills to improve error detection reliability.
📜 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 (3)
plugins/jira/commands/create.md(3 hunks)plugins/jira/skills/cntrlplane/SKILL.md(5 hunks)plugins/jira/skills/create-story/SKILL.md(4 hunks)
🧰 Additional context used
🪛 LanguageTool
plugins/jira/skills/create-story/SKILL.md
[style] ~37-~37: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...in description!) - ❌ "As a developer, I want to view metrics so that I can debug issues...
(REP_WANT_TO_VB)
🪛 markdownlint-cli2 (0.18.1)
plugins/jira/skills/create-story/SKILL.md
46-46: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
plugins/jira/skills/cntrlplane/SKILL.md
105-105: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
163-163: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
173-173: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
plugins/jira/commands/create.md
173-173: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🔇 Additional comments (5)
plugins/jira/commands/create.md (1)
478-502: Excellent error handling guidance aligned with field mapping updates.This new section directly addresses the PR's core objectives by documenting common field format mistakes and corrections:
- Target Version: Clarifies array-with-ID format
[{"id": "12448830"}]vs string (aligns with CNTRLPLANE skill documentation)- Epic Link: Distinguishes custom field
customfield_12311140(string) fromparentobject (aligns with summary vs description principle)- Component: Shows array format expectations
The detection strategy (parse error message → check skill documentation → auto-convert and retry) is practical and reduces manual intervention.
plugins/jira/skills/create-story/SKILL.md (1)
356-436: MCP examples well-aligned with summary vs description principle.Updates to field validation (line 356), MCP parameters (line 379), and project-specific example comments (lines 430-431) cleanly integrate the summary vs description distinction. The notes about Target Version being optional and Epic Link being project-specific are helpful and reduce confusion.
plugins/jira/skills/cntrlplane/SKILL.md (3)
33-69: Target Version documentation clearly marks as optional and corrects MCP format.This section directly addresses the PR objective to correct Target Version documentation:
Strengths:
- Clear status change: OPTIONAL, with recommendation to omit (line 37) — practical and reduces errors
- MCP format is explicit:
[{"id": "12448830"}]not"openshift-4.21"(line 50)- Common version ID reference (lines 53-56) useful for quick lookup
- Version Override Handling (lines 65-69) describes proper flow with fetch/convert pattern
- Integrates well with Field Format Error section in create.md
Minor note: Code block at line 42 lacks language identifier (MD040):
- ```python + ```python(This one is actually fine since it has
pythonidentifier)Actually, the code blocks here are properly formatted. This section is approved.
322-336: Field Mapping Reference table is valuable and correctly documents field requirements.This new table directly addresses the PR objective to add a "Required?" column and provides a comprehensive field reference:
Strengths:
- Clear at a glance: Required vs optional fields are obvious
- Accurate values: Shows correct MCP formats (array for Target Version, string for Epic Link)
- Field IDs included:
customfield_12311140,customfield_epicname,customfield_12319940with corresponding descriptions- Project-specific: CNTRLPLANE-focused reference
- Aligns with documentation: All values match examples and guidance throughout the document
Accuracy check: Field IDs and formats appear correct based on usage throughout the document.
216-319: MCP examples effectively demonstrate updated conventions with clear variant coverage.The examples section demonstrates:
- Variant coverage: Basic (no link), linked to epic, with parent, with various issue types
- Updated conventions: Epic Link field
customfield_12311140used correctly for story→epic relationships- Target Version handling: Omitted or noted as optional, consistent with updated documentation
- Comments clarify intent: Lines noting "NOT full user story format", "if required", "Epic Link", "optional"
The distinction between Epic Link (custom field for story→epic) and parent field (for feature relationships) is demonstrated correctly across scenarios.
| ### ✅ Phase 5.5: Summary Validation | ||
|
|
||
| Before security validation, validate the summary format to catch common mistakes: | ||
|
|
||
| **Check for anti-patterns:** | ||
| 1. Summary starts with "As a" (user story format belongs in description) | ||
| 2. Summary contains "I want" or "so that" (belongs in description) | ||
| 3. Summary exceeds 100 characters (likely too long, may be full user story) | ||
|
|
||
| **Action if anti-pattern detected:** | ||
| 1. Detect that user put full user story in summary field | ||
| 2. Extract the key action/feature from the summary | ||
| 3. Generate a concise alternative (5-10 words) | ||
| 4. Prompt user for confirmation: | ||
| ``` | ||
| The summary looks like a full user story. Summaries should be concise titles. | ||
| Current: "As a cluster admin, I want to configure ImageTagMirrorSet in HostedCluster CRs so that I can enable tag-based image proxying" | ||
| Suggested: "Enable ImageTagMirrorSet configuration in HostedCluster CRs" | ||
| Use the suggested summary? (yes/no/edit) | ||
| ``` | ||
|
|
||
| 5. If user says yes, use suggested summary | ||
| 6. If user says edit, prompt for their preferred summary | ||
| 7. If user says no, use their original summary (but warn it may be truncated in Jira) | ||
|
|
||
| **Note:** This validation should happen BEFORE creating the issue, to avoid having to update the summary afterward. |
There was a problem hiding this comment.
Fix markdown linting: Add language identifier to example output block.
The code block at lines 181-189 lacks a language specification. Per MD040, fenced code blocks should declare their language.
Apply this diff:
- ```
+ ```text
The summary looks like a full user story. Summaries should be concise titles.
Current: "As a cluster admin, I want to configure ImageTagMirrorSet in HostedCluster CRs so that I can enable tag-based image proxying"
Suggested: "Enable ImageTagMirrorSet configuration in HostedCluster CRs"
Use the suggested summary? (yes/no/edit)
- ```
+ ```Content-wise: Phase 5.5 is well-designed. The anti-pattern heuristics (checking for "As a", "I want", "so that", and 100-char limit) effectively catch the common mistake of putting full user stories in the summary field. The user workflow (detect → suggest → prompt) is intuitive.
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
173-173: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In plugins/jira/commands/create.md around lines 167 to 195, the fenced code
block example (lines ~181-189) is missing a language identifier which violates
MD040; update the opening triple backticks to include a language (use "text")
and ensure the closing triple backticks remain; no other content changes
required.
| ## Epic Link Requirements | ||
|
|
||
| **⚠️ CRITICAL:** To link a story to an epic in CNTRLPLANE, you **MUST** use the Epic Link custom field, NOT the `parent` field. | ||
|
|
||
| ### Epic Link Field (customfield_12311140) | ||
|
|
||
| **Field Details:** | ||
| - **Field Name:** Epic Link | ||
| - **Custom Field ID:** `customfield_12311140` | ||
| - **MCP Parameter:** `additional_fields.customfield_12311140` | ||
| - **Value Format:** Epic key as string (e.g., `"CNTRLPLANE-123"`) | ||
| - **Used For:** Linking stories to epics | ||
|
|
||
| **IMPORTANT:** Do NOT use `additional_fields.parent` for epic-story relationships. The `parent` field has different semantics and will cause creation to fail. | ||
|
|
||
| ### MCP Format for Epic Link | ||
|
|
||
| ```python | ||
| additional_fields={ | ||
| "customfield_12311140": "CNTRLPLANE-123", # Epic Link (use actual epic key) | ||
| "labels": ["ai-generated-jira"], | ||
| "security": {"name": "Red Hat Employee"} | ||
| } | ||
| ``` | ||
|
|
||
| ### Epic Linking Implementation Strategy | ||
|
|
||
| When the `--parent` flag is provided for a story/task, use this implementation strategy: | ||
|
|
||
| #### Pre-Validation (Do This First) | ||
|
|
||
| Before attempting to create the issue: | ||
| 1. Verify the parent epic exists using `mcp__atlassian__jira_get_issue` | ||
| 2. If epic doesn't exist, prompt user: | ||
| ``` | ||
| Epic {epic_key} not found. Options: | ||
| 1. Proceed without epic link | ||
| 2. Specify different epic | ||
| 3. Cancel creation | ||
| What would you like to do? | ||
| ``` | ||
| 3. Only proceed if epic is valid or user chooses to proceed without link | ||
|
|
||
| #### Preferred Approach: Include Epic Link in Creation | ||
|
|
||
| Attempt to create the issue with Epic Link included: | ||
| ```python | ||
| mcp__atlassian__jira_create_issue( | ||
| project_key="CNTRLPLANE", | ||
| summary="<story title>", | ||
| issue_type="Story", | ||
| description="<description>", | ||
| components="<component>", | ||
| additional_fields={ | ||
| "customfield_12311140": "<epic-key>", # Epic Link (e.g., "CNTRLPLANE-456") | ||
| "labels": ["ai-generated-jira"], | ||
| "security": {"name": "Red Hat Employee"} | ||
| } | ||
| ) | ||
| ``` | ||
|
|
||
| #### Fallback Strategy (If Creation Fails) | ||
|
|
||
| If creation fails with an error related to epic linking: | ||
| 1. Detect error contains keywords: "epic", "parent", "customfield", or "link" | ||
| 2. Inform user: "Epic link failed during creation, using fallback strategy..." | ||
| 3. Create issue WITHOUT the epic link: | ||
| ```python | ||
| story = mcp__atlassian__jira_create_issue( | ||
| project_key="CNTRLPLANE", | ||
| summary="<story title>", | ||
| issue_type="Story", | ||
| description="<description>", | ||
| components="<component>", | ||
| additional_fields={ | ||
| "labels": ["ai-generated-jira"], | ||
| "security": {"name": "Red Hat Employee"} | ||
| } | ||
| ) | ||
| ``` | ||
| 4. If creation succeeds, link to epic via update: | ||
| ```python | ||
| mcp__atlassian__jira_update_issue( | ||
| issue_key=story["key"], | ||
| fields={}, | ||
| additional_fields={ | ||
| "customfield_12311140": "<epic-key>" | ||
| } | ||
| ) | ||
| ``` | ||
| 5. Inform user of success: | ||
| ``` | ||
| Created: CNTRLPLANE-XXX | ||
| Linked to epic: <epic-key> ✓ | ||
| Title: <story title> | ||
| URL: https://issues.redhat.com/browse/CNTRLPLANE-XXX | ||
| ``` | ||
|
|
||
| #### If Fallback Also Fails | ||
|
|
||
| If the update call to add Epic Link also fails: | ||
| ``` | ||
| Story created: CNTRLPLANE-XXX | ||
| ⚠️ Automatic epic linking failed. Please link manually in Jira. | ||
| URL: https://issues.redhat.com/browse/CNTRLPLANE-XXX | ||
| ``` |
There was a problem hiding this comment.
Epic Linking Implementation Strategy is comprehensive and addresses PR objective well.
This section provides excellent, practical guidance on Epic Link handling:
Strengths:
- Clear distinction: Custom field
customfield_12311140(string) vsparentfield (object) — eliminates common mistake - Pre-validation: Defensive check that epic exists before attempting creation (lines 100-114)
- Three-tier approach: Try with Epic Link → Fallback without link then update → Manual linking if needed
- Concrete code examples: Shows the exact MCP calls for each path
- Error messaging: User-friendly fallback notifications (lines 162-177)
Alignment: Integrates well with Phase 5.5 and Epic Link Creation Failure guidance in create.md
Minor markdown linting: Code blocks at lines 88, 118, 139, 153 should have language identifiers per MD040:
- ```python
+ ```python
mcp__atlassian__jira_create_issue((Verify these blocks have language identifiers added if not already present)
Content quality is high and directly addresses the PR objective to document Epic Link implementation strategy.
🧰 Tools
🪛 markdownlint-cli2 (0.18.1)
105-105: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
163-163: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
173-173: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In plugins/jira/skills/cntrlplane/SKILL.md around lines 71 to 177, several
fenced code blocks (notably at lines ~88, ~118, ~139, ~153) are missing language
identifiers which triggers MD040; update each triple-backtick fence to include
the "python" language tag (e.g., change ``` to ```python) so the blocks are
correctly marked and linting passes, then run the markdown linter to confirm no
MD040 warnings remain.
| ## ⚠️ Summary vs Description: CRITICAL DISTINCTION | ||
|
|
||
| **This is the #1 mistake when creating stories. The summary field and description field serve different purposes:** | ||
|
|
||
| ### Summary Field (Issue Title) | ||
| - **SHORT, concise title** (5-10 words maximum) | ||
| - Action-oriented, describes WHAT will be done | ||
| - **Does NOT contain the full "As a... I want... So that..." format** | ||
| - Think of it as a newspaper headline | ||
|
|
||
| **Good summary examples:** | ||
| - ✅ "Enable ImageTagMirrorSet configuration in HostedCluster CRs" | ||
| - ✅ "Add automatic node pool scaling for ROSA HCP" | ||
| - ✅ "Implement webhook validation for HostedCluster resources" | ||
|
|
||
| **Bad summary examples:** | ||
| - ❌ "As a cluster admin, I want to configure ImageTagMirrorSet in HostedCluster CRs so that I can enable tag-based image proxying" (Full user story - belongs in description!) | ||
| - ❌ "As a developer, I want to view metrics so that I can debug issues" (User story format - belongs in description!) | ||
|
|
||
| ### Description Field (Issue Body) | ||
| - Contains the **FULL user story format**: "As a... I want... So that..." | ||
| - Includes **acceptance criteria** | ||
| - Includes **additional context** | ||
| - Can be lengthy and detailed | ||
|
|
||
| **Correct usage:** | ||
| ``` | ||
| Summary: "Enable ImageTagMirrorSet configuration in HostedCluster CRs" | ||
| Description: | ||
| As a cluster admin, I want to configure ImageTagMirrorSet in HostedCluster CRs, | ||
| so that I can enable tag-based image proxying for my workloads. | ||
| Acceptance Criteria: | ||
| - Test that ImageTagMirrorSet can be specified... | ||
| ``` | ||
|
|
||
| ### When Collecting Story Information | ||
| 1. First collect the full user story (As a... I want... So that...) | ||
| 2. Then extract/generate a concise summary title from that story | ||
| 3. Present both to user for confirmation | ||
| 4. Summary goes in `summary` parameter, full story goes in `description` | ||
|
|
There was a problem hiding this comment.
Critical distinction section is excellent; minor markdown linting issue.
The "
Strengths:
- Clear framing: This is the chore: sets the initial config for a market place and a hello world plugin #1 mistake, requiring immediate attention
- Concrete guidance: Summary = 5-10 word headline; Description = full story + AC
- Realistic examples: Good/bad summaries are recognizable and instructive
- Workflow clarity: Collect full story first, extract summary second (integrates perfectly with Phase 5.5 validation)
- Cross-file alignment: Aligns with Phase 5.5 Summary Validation in create.md
Minor issue: Code block at lines 45-55 lacks language identifier (MD040). Fix:
- ```
+ ```jira
Summary: "Enable ImageTagMirrorSet configuration in HostedCluster CRs"🧰 Tools
🪛 LanguageTool
[style] ~37-~37: You have already used this phrasing in nearby sentences. Consider replacing it to add variety to your writing.
Context: ...in description!) - ❌ "As a developer, I want to view metrics so that I can debug issues...
(REP_WANT_TO_VB)
🪛 markdownlint-cli2 (0.18.1)
46-46: Fenced code blocks should have a language specified
(MD040, fenced-code-language)
🤖 Prompt for AI Agents
In plugins/jira/skills/create-story/SKILL.md around lines 20 to 62, the fenced
code block at lines ~45-55 is missing a language identifier (MD040); update the
opening backticks to include the "jira" language tag (i.e., change ``` to
```jira) so the block is properly labeled for markdown linting.
2 participants
Summary
Fix critical documentation gaps in the jira:create plugin for Epic Link field mapping, Target Version format, and summary validation.
Changes
create-story skill
CNTRLPLANE skill
customfield_12311140[{"id": "VERSION_ID"}]create.md command
Impact
These changes prevent common mistakes when creating Jira stories:
Summary by CodeRabbit
Release Notes