Skip to content

Commit cdc5d4d

Browse files
bryan-coxbryan-cox
committed
docs(jira): fix critical field mapping and validation issues in create 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
1 parent 2157c19 commit cdc5d4d

File tree

3 files changed

+316
-52
lines changed

3 files changed

+316
-52
lines changed

‎plugins/jira/commands/create.md‎

Lines changed: 73 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -150,6 +150,36 @@ Prompt for missing required information based on issue type:
150150
- Expected results (correct behavior)
151151
- Additional info (logs, screenshots)
152152

153+
### ✅ Phase 5.5: Summary Validation
154+
155+
Before security validation, validate the summary format to catch common mistakes:
156+
157+
**Check for anti-patterns:**
158+
1. Summary starts with "As a" (user story format belongs in description)
159+
2. Summary contains "I want" or "so that" (belongs in description)
160+
3. Summary exceeds 100 characters (likely too long, may be full user story)
161+
162+
**Action if anti-pattern detected:**
163+
1. Detect that user put full user story in summary field
164+
2. Extract the key action/feature from the summary
165+
3. Generate a concise alternative (5-10 words)
166+
4. Prompt user for confirmation:
167+
```
168+
The summary looks like a full user story. Summaries should be concise titles.
169+
170+
Current: "As a cluster admin, I want to configure ImageTagMirrorSet in HostedCluster CRs so that I can enable tag-based image proxying"
171+
172+
Suggested: "Enable ImageTagMirrorSet configuration in HostedCluster CRs"
173+
174+
Use the suggested summary? (yes/no/edit)
175+
```
176+
177+
5. If user says yes, use suggested summary
178+
6. If user says edit, prompt for their preferred summary
179+
7. If user says no, use their original summary (but warn it may be truncated in Jira)
180+
181+
**Note:** This validation should happen BEFORE creating the issue, to avoid having to update the summary afterward.
182+
153183
### 🔒 Phase 6: Security Validation
154184

155185
Scan all content (summary, description, comments) for sensitive data:
@@ -188,6 +218,8 @@ Use the `mcp__atlassian__jira_create_issue` MCP tool with collected parameters.
188218

189219
The MCP tool parameters come from the combined guidance of type-specific, project-specific, and team-specific skills, with universal requirements always applied.
190220

221+
**Note:** Project-specific skills (e.g., CNTRLPLANE) may implement fallback strategies for handling creation failures (such as epic linking). Refer to the project-specific skill documentation for these strategies.
222+
191223
### 📤 Phase 8: Return Result
192224

193225
Display to user:
@@ -407,6 +439,47 @@ Would you like to edit the description?
407439
- **"Permission denied"** → User may lack permissions, suggest contacting admin
408440
- **"Issue type not available"** → Project may not support this issue type
409441

442+
### Epic Link Creation Failure
443+
444+
**Scenario:** Story/task creation fails when including epic link field.
445+
446+
**Action:**
447+
Refer to project-specific skills for epic linking fallback strategies:
448+
- **CNTRLPLANE:** See CNTRLPLANE skill "Epic Linking Implementation Strategy" section
449+
- **Other projects:** Consult project-specific skill documentation
450+
451+
**General pattern:**
452+
1. Detect error related to linking (error contains "epic", "parent", "link", or "customfield")
453+
2. Check project-specific skill for recommended fallback approach
454+
3. Typically: Create without link, then link via update
455+
4. Inform user of outcome
456+
457+
### Field Format Error
458+
459+
**Scenario:** Field provided in wrong format (e.g., Target Version as string instead of array).
460+
461+
**Common field format errors:**
462+
463+
1. **Target Version format**
464+
- ❌ Wrong: `"customfield_12319940": "openshift-4.21"`
465+
- ✅ Correct: `"customfield_12319940": [{"id": "12448830"}]`
466+
- **Action:** Fetch version ID using `mcp__atlassian__jira_get_project_versions`, convert to correct format
467+
468+
2. **Epic Link format**
469+
- ❌ Wrong: `"parent": {"key": "EPIC-123"}` (for stories)
470+
- ✅ Correct: `"customfield_12311140": "EPIC-123"` (string, not object)
471+
- **Action:** Convert to correct format and retry
472+
473+
3. **Component format**
474+
- ❌ Wrong: `"components": "ComponentName"`
475+
- ✅ Correct: `"components": ["ComponentName"]` (array) or just `"ComponentName"` (MCP accepts both)
476+
- **Action:** Ensure consistent format
477+
478+
**Detection:**
479+
- Parse error message for field names
480+
- Check skill documentation for correct format
481+
- Automatically convert and retry when possible
482+
410483
## Best Practices
411484

412485
1. **Use descriptive summaries:** Include relevant keywords for context and auto-detection

‎plugins/jira/skills/cntrlplane/SKILL.md‎

Lines changed: 194 additions & 34 deletions
Original file line numberDiff line numberDiff line change
@@ -31,25 +31,150 @@ This skill is automatically invoked by the `/jira:create` command when the proje
3131
**Note:** Universal requirements (Security Level: Red Hat Employee, Labels: ai-generated-jira) are defined in the `/jira:create` command and automatically applied to all tickets.
3232

3333
### Target Version (customfield_12319940)
34-
**Purpose:** Target release version for the feature/story/task
3534

36-
**Common default:** `openshift-4.21` (current development release)
35+
**Status:** OPTIONAL (many issues in CNTRLPLANE have null target version)
3736

38-
**Override:** Teams may specify different versions based on their roadmap:
39-
- `openshift-4.20` (maintenance release)
40-
- `openshift-4.22` (future release)
41-
- `openshift-4.23` (future release)
42-
- Or team-specific version schemes
37+
**Recommendation:** **Omit this field** unless specifically required by the team or user explicitly requests it.
38+
39+
**If target version must be set:**
40+
41+
1. **First, fetch available versions:**
42+
```python
43+
versions = mcp__atlassian__jira_get_project_versions(project_key="CNTRLPLANE")
44+
```
45+
46+
2. **Find the version ID** for the desired version (e.g., "openshift-4.21" has id "12448830")
47+
48+
3. **Use correct MCP format** (array of version objects with ID):
49+
```python
50+
"customfield_12319940": [{"id": "12448830"}] # openshift-4.21
51+
```
52+
53+
**Common version IDs:**
54+
- `openshift-4.21`: `{"id": "12448830"}`
55+
- `openshift-4.20`: `{"id": "12447110"}`
56+
- `openshift-4.22`: `{"id": "12448831"}`
57+
58+
**IMPORTANT:** Do NOT use string format like `"openshift-4.21"` - this will fail. Must use array with version ID.
4359

4460
**Never set:**
4561
- Fix Version/s (`fixVersions`) - This is managed by the release team
4662

4763
### Version Override Handling
4864

49-
When user specifies a different version:
50-
1. Accept the version as provided
51-
2. Validate version exists using MCP tool `jira_get_project_versions` if needed
65+
If user specifies a version:
66+
1. Fetch available versions using `mcp__atlassian__jira_get_project_versions`
67+
2. Find the matching version ID
5268
3. If version doesn't exist, suggest closest match or ask user to confirm
69+
4. Use array format with version ID: `[{"id": "VERSION_ID"}]`
70+
71+
## Epic Link Requirements
72+
73+
**⚠️ CRITICAL:** To link a story to an epic in CNTRLPLANE, you **MUST** use the Epic Link custom field, NOT the `parent` field.
74+
75+
### Epic Link Field (customfield_12311140)
76+
77+
**Field Details:**
78+
- **Field Name:** Epic Link
79+
- **Custom Field ID:** `customfield_12311140`
80+
- **MCP Parameter:** `additional_fields.customfield_12311140`
81+
- **Value Format:** Epic key as string (e.g., `"CNTRLPLANE-123"`)
82+
- **Used For:** Linking stories to epics
83+
84+
**IMPORTANT:** Do NOT use `additional_fields.parent` for epic-story relationships. The `parent` field has different semantics and will cause creation to fail.
85+
86+
### MCP Format for Epic Link
87+
88+
```python
89+
additional_fields={
90+
"customfield_12311140": "CNTRLPLANE-123", # Epic Link (use actual epic key)
91+
"labels": ["ai-generated-jira"],
92+
"security": {"name": "Red Hat Employee"}
93+
}
94+
```
95+
96+
### Epic Linking Implementation Strategy
97+
98+
When the `--parent` flag is provided for a story/task, use this implementation strategy:
99+
100+
#### Pre-Validation (Do This First)
101+
102+
Before attempting to create the issue:
103+
1. Verify the parent epic exists using `mcp__atlassian__jira_get_issue`
104+
2. If epic doesn't exist, prompt user:
105+
```
106+
Epic {epic_key} not found. Options:
107+
1. Proceed without epic link
108+
2. Specify different epic
109+
3. Cancel creation
110+
111+
What would you like to do?
112+
```
113+
3. Only proceed if epic is valid or user chooses to proceed without link
114+
115+
#### Preferred Approach: Include Epic Link in Creation
116+
117+
Attempt to create the issue with Epic Link included:
118+
```python
119+
mcp__atlassian__jira_create_issue(
120+
project_key="CNTRLPLANE",
121+
summary="<story title>",
122+
issue_type="Story",
123+
description="<description>",
124+
components="<component>",
125+
additional_fields={
126+
"customfield_12311140": "<epic-key>", # Epic Link (e.g., "CNTRLPLANE-456")
127+
"labels": ["ai-generated-jira"],
128+
"security": {"name": "Red Hat Employee"}
129+
}
130+
)
131+
```
132+
133+
#### Fallback Strategy (If Creation Fails)
134+
135+
If creation fails with an error related to epic linking:
136+
1. Detect error contains keywords: "epic", "parent", "customfield", or "link"
137+
2. Inform user: "Epic link failed during creation, using fallback strategy..."
138+
3. Create issue WITHOUT the epic link:
139+
```python
140+
story = mcp__atlassian__jira_create_issue(
141+
project_key="CNTRLPLANE",
142+
summary="<story title>",
143+
issue_type="Story",
144+
description="<description>",
145+
components="<component>",
146+
additional_fields={
147+
"labels": ["ai-generated-jira"],
148+
"security": {"name": "Red Hat Employee"}
149+
}
150+
)
151+
```
152+
4. If creation succeeds, link to epic via update:
153+
```python
154+
mcp__atlassian__jira_update_issue(
155+
issue_key=story["key"],
156+
fields={},
157+
additional_fields={
158+
"customfield_12311140": "<epic-key>"
159+
}
160+
)
161+
```
162+
5. Inform user of success:
163+
```
164+
Created: CNTRLPLANE-XXX
165+
Linked to epic: <epic-key> ✓
166+
Title: <story title>
167+
URL: https://issues.redhat.com/browse/CNTRLPLANE-XXX
168+
```
169+
170+
#### If Fallback Also Fails
171+
172+
If the update call to add Epic Link also fails:
173+
```
174+
Story created: CNTRLPLANE-XXX
175+
⚠️ Automatic epic linking failed. Please link manually in Jira.
176+
URL: https://issues.redhat.com/browse/CNTRLPLANE-XXX
177+
```
53178

54179
## Component Requirements
55180

@@ -91,15 +216,31 @@ Some teams require specific components, while others do not. The CNTRLPLANE skil
91216

92217
### For CNTRLPLANE Stories
93218

219+
**Basic story (no epic link):**
220+
```python
221+
mcp__atlassian__jira_create_issue(
222+
project_key="CNTRLPLANE",
223+
summary="<concise story title>", # NOT full user story format
224+
issue_type="Story",
225+
description="<formatted description with full user story and AC>",
226+
components="<component name>", # if required by team
227+
additional_fields={
228+
"labels": ["ai-generated-jira"],
229+
"security": {"name": "Red Hat Employee"}
230+
}
231+
)
232+
```
233+
234+
**Story linked to epic:**
94235
```python
95236
mcp__atlassian__jira_create_issue(
96237
project_key="CNTRLPLANE",
97-
summary="<story summary>",
238+
summary="<concise story title>", # NOT full user story format
98239
issue_type="Story",
99-
description="<formatted description with AC>",
240+
description="<formatted description with full user story and AC>",
100241
components="<component name>", # if required by team
101242
additional_fields={
102-
"customfield_12319940": "openshift-4.21", # target version (default)
243+
"customfield_12311140": "<epic-key>", # Epic Link (e.g., "CNTRLPLANE-456")
103244
"labels": ["ai-generated-jira"],
104245
"security": {"name": "Red Hat Employee"}
105246
}
@@ -108,19 +249,35 @@ mcp__atlassian__jira_create_issue(
108249

109250
### For CNTRLPLANE Epics
110251

252+
**Basic epic (no parent feature):**
111253
```python
112254
mcp__atlassian__jira_create_issue(
113255
project_key="CNTRLPLANE",
114-
summary="<epic summary>",
256+
summary="<concise epic title>",
115257
issue_type="Epic",
116258
description="<epic description with scope and AC>",
117259
components="<component name>", # if required
118260
additional_fields={
119-
"customfield_12319940": "openshift-4.21",
120-
"customfield_epicname": "<epic name>", # required, same as summary
261+
"customfield_12311141": "<epic name>", # required, same as summary
262+
"labels": ["ai-generated-jira"],
263+
"security": {"name": "Red Hat Employee"}
264+
}
265+
)
266+
```
267+
268+
**Epic linked to parent feature:**
269+
```python
270+
mcp__atlassian__jira_create_issue(
271+
project_key="CNTRLPLANE",
272+
summary="<concise epic title>",
273+
issue_type="Epic",
274+
description="<epic description with scope and AC>",
275+
components="<component name>", # if required
276+
additional_fields={
277+
"customfield_12311141": "<epic name>", # required, same as summary
121278
"labels": ["ai-generated-jira"],
122279
"security": {"name": "Red Hat Employee"},
123-
"parent": {"key": "CNTRLPLANE-123"} # if --parent specified
280+
"parent": {"key": "CNTRLPLANE-123"} # parent feature link
124281
}
125282
)
126283
```
@@ -130,20 +287,21 @@ mcp__atlassian__jira_create_issue(
130287
```python
131288
mcp__atlassian__jira_create_issue(
132289
project_key="CNTRLPLANE",
133-
summary="<feature summary>",
290+
summary="<concise feature title>",
134291
issue_type="Feature",
135292
description="<feature description with market problem and success criteria>",
136293
components="<component name>", # if required
137294
additional_fields={
138-
"customfield_12319940": "openshift-4.21",
139295
"labels": ["ai-generated-jira"],
140296
"security": {"name": "Red Hat Employee"}
297+
# Target version is optional - omit unless specifically required
141298
}
142299
)
143300
```
144301

145302
### For CNTRLPLANE Tasks
146303

304+
**Task linked to epic (via Epic Link):**
147305
```python
148306
mcp__atlassian__jira_create_issue(
149307
project_key="CNTRLPLANE",
@@ -152,28 +310,30 @@ mcp__atlassian__jira_create_issue(
152310
description="<task description with what/why/AC>",
153311
components="<component name>", # if required
154312
additional_fields={
155-
"customfield_12319940": "openshift-4.21",
313+
"customfield_12311140": "CNTRLPLANE-456", # Epic Link (if linking to epic)
156314
"labels": ["ai-generated-jira"],
157-
"security": {"name": "Red Hat Employee"},
158-
"parent": {"key": "CNTRLPLANE-456"} # if --parent specified
315+
"security": {"name": "Red Hat Employee"}
159316
}
160317
)
161318
```
162319

320+
**Note:** If you need to link a task to a parent story, use Epic Link field (`customfield_12311140`) with the story key.
321+
163322
### Field Mapping Reference
164323

165-
| Requirement | MCP Parameter | Value |
166-
|-------------|---------------|-------|
167-
| Project | `project_key` | `"CNTRLPLANE"` |
168-
| Issue Type | `issue_type` | `"Story"`, `"Epic"`, `"Feature"`, `"Task"` |
169-
| Summary | `summary` | User-provided text |
170-
| Description | `description` | Formatted template content |
171-
| Component | `components` | Team-specific (optional) |
172-
| Target Version | `additional_fields.customfield_12319940` | `"openshift-4.21"` (default) |
173-
| Labels | `additional_fields.labels` | `["ai-generated-jira"]` (required) |
174-
| Security Level | `additional_fields.security` | `{"name": "Red Hat Employee"}` (required) |
175-
| Parent Link | `additional_fields.parent` | `{"key": "PARENT-123"}` |
176-
| Epic Name | `additional_fields.customfield_epicname` | Same as summary (epics only) |
324+
| Requirement | MCP Parameter | Value | Required? |
325+
|-------------|---------------|-------|-----------|
326+
| Project | `project_key` | `"CNTRLPLANE"` | Yes |
327+
| Issue Type | `issue_type` | `"Story"`, `"Epic"`, `"Feature"`, `"Task"` | Yes |
328+
| Summary | `summary` | Concise title (5-10 words), NOT full user story | Yes |
329+
| Description | `description` | Formatted template (contains full user story) | Yes |
330+
| Component | `components` | Team-specific component name | Varies by team |
331+
| Target Version | `additional_fields.customfield_12319940` | Array: `[{"id": "12448830"}]` **Recommend omitting** | No |
332+
| Labels | `additional_fields.labels` | `["ai-generated-jira"]` | Yes |
333+
| Security Level | `additional_fields.security` | `{"name": "Red Hat Employee"}` | Yes |
334+
| Epic Link (stories→epics) | `additional_fields.customfield_12311140` | Epic key as string: `"CNTRLPLANE-123"` | No |
335+
| Epic Name (epics only) | `additional_fields.customfield_epicname` | Same as summary | Yes (epics) |
336+
| Parent Link (epics→features) | `additional_fields.parent` | `{"key": "FEATURE-123"}` | No |
177337

178338
## Interactive Prompts
179339

0 commit comments

Comments
 (0)