Implementation guide for creating Jira tasks for technical and operational work
This skill provides implementation guidance for creating Jira tasks, which are used for technical or operational work that doesn't necessarily deliver direct user-facing value.
This skill is automatically invoked by the /jira:create task command to guide the task creation process.
Reference Documentation:
Use a Task when the work is:
Examples of tasks:
Use a Story when the work:
If in doubt: Ask "Would an end user notice or care about this change?"
The summary should:
Good examples:
Bad examples:
The description should include:
Example:
Update the autoscaling documentation to reflect changes in the 4.21 release.
Why: The autoscaling API changed in 4.21 with new fields and behavior. Documentation currently reflects 4.20 and will confuse users.
Acceptance Criteria:
- All autoscaling examples updated to use 4.21 API
- New fields documented with descriptions and examples
- Deprecated fields marked as deprecated
- Documentation builds without warnings
Files to update:
- docs/content/how-to/autoscaling.md
- docs/content/reference/api.md
Use this structure for consistency:
<What needs to be done>
## Why
<Context, motivation, or reason this is needed>
## Acceptance Criteria
- <Criterion 1>
- <Criterion 2>
- <Criterion 3>
## Technical Details (optional)
- Files to modify: <list>
- Dependencies: <related issues or work>
- Approach: <suggested implementation approach>
When creating a task, collect necessary information:
Prompt: "What work needs to be done? Be specific about what you'll change or update."
Helpful questions:
Example response:
Refactor the scaling controller to extract common validation logic into a shared utility package. Currently, validation code is duplicated across three controller files.
Prompt: "Why is this task needed? What problem does it solve?"
Helpful questions:
Example response:
Code duplication makes maintenance difficult. When validation logic changes, we have to update it in three places, which is error-prone. Consolidating into a shared utility will make the code easier to maintain and reduce bugs.
Prompt: "How will you know this task is complete? (Optional: skip if obvious)"
For technical tasks, AC might include:
Example response:
- Validation logic extracted to support/validation package
- All three controllers updated to use shared validation
- Existing tests pass
- New unit tests added for validation utility
- Code review approved
Prompt: "Is this task part of a larger story or epic? (Optional)"
If yes:
Prompt: "Any technical details to include? (files to change, dependencies, approach)"
Example response:
Files to modify:
- hypershift/operator/controllers/nodepool/autoscaling.go
- hypershift/operator/controllers/hostedcluster/autoscaling.go
- hypershift/operator/controllers/manifests/autoscaling.go
- hypershift/support/validation/autoscaling.go (new)
Dependencies:
- Must complete after PROJ-100 (validation refactor epic)
Approach:
- Extract common validation functions to support/validation
- Add comprehensive unit tests for new package
- Update controllers to import and use new package
- Remove duplicated code
Before submitting the task, validate:
mcp__atlassian__jira_create_issue(
project_key="<PROJECT_KEY>",
summary="<task summary>",
issue_type="Task",
description="""
<What needs to be done>
## Why
<Context and motivation>
## Acceptance Criteria
- <Criterion 1>
- <Criterion 2>
## Technical Details
<Optional technical details>
""",
components="<component name>", # if required
additional_fields={
# Add project-specific fields
}
)
mcp__atlassian__jira_create_issue(
project_key="CNTRLPLANE",
summary="Update autoscaling documentation for 4.21 release",
issue_type="Task",
description="""
Update the autoscaling documentation to reflect API changes in the 4.21 release.
## Why
The autoscaling API changed in 4.21 with new fields (maxNodeGracePeriod, scaleDownDelay) and modified behavior. Current documentation reflects 4.20 API and will confuse users upgrading to 4.21.
## Acceptance Criteria
- All autoscaling examples updated to use 4.21 API syntax
- New fields (maxNodeGracePeriod, scaleDownDelay) documented with descriptions and examples
- Deprecated fields marked as deprecated with migration guidance
- Documentation builds successfully without warnings or broken links
- Changes reviewed by docs team
## Technical Details
Files to update:
- docs/content/how-to/cluster-autoscaling.md
- docs/content/reference/api/nodepool.md
- docs/content/tutorials/autoscaling-rosa.md
Reference: API changes introduced in PR #1234
""",
components="HyperShift",
additional_fields={
"customfield_10855": "openshift-4.21", # target version
"labels": ["ai-generated-jira", "documentation"],
"security": {"name": "Red Hat Employee"}
}
)
mcp__atlassian__jira_create_issue(
project_key="MYPROJECT",
summary="Add unit tests for scaling validation",
issue_type="Task",
description="<task content>",
additional_fields={
"parent": {"key": "MYPROJECT-100"} # link to story or epic
}
)
Use Markdown formatting (the MCP tool converts it to Jira wiki markup automatically):
<Brief description of what needs to be done>
## Why
<Context, motivation, or problem this solves>
## Acceptance Criteria
- <Criterion 1>
- <Criterion 2>
- <Criterion 3>
## Technical Details
### Files to Modify
- `path/to/file1.go`
- `path/to/file2.go`
### Dependencies
- Must complete after PROJ-100
- Requires library X version Y
### Approach
<Suggested implementation approach or technical notes>
## Additional Context
<Optional: Links to designs, related issues, background>
For complete Markdown formatting reference, see Markdown for Jira Reference.
Scenario: User tries to create a task for user-facing functionality.
Action:
Example:
This sounds like it might deliver user-facing functionality. The summary mentions "users can configure autoscaling".
Should this be a Story instead of a Task?
- Story: For user-facing features (visible to end users)
- Task: For internal/technical work (not visible to end users)
Would you like me to create this as a Story? (yes/no)
Scenario: User provides minimal description without context.
Action:
Example:
The description "Update docs" is a bit brief. Can you provide more detail?
- Which documentation needs updating?
- Why does it need updating? (new features, corrections, clarifications?)
- What specific changes should be made?
Scenario: User specifies --parent but issue doesn't exist.
Action:
Example:
Parent issue PROJ-999 not found.
Options:
1. Proceed without parent link
2. Specify different parent
3. Cancel task creation
What would you like to do?
Scenario: Sensitive data detected in task content.
Action:
Example:
I detected what appears to be an API key in the technical details section.
Please use placeholder values like "YOUR_API_KEY" instead of real credentials.
Scenario: MCP tool returns an error when creating the task.
Action:
Common errors:
Input:
/jira:create task CNTRLPLANE "Update autoscaling documentation for 4.21 release"
Interactive prompts:
What work needs to be done?
> Update the autoscaling documentation to include new fields added in 4.21
Why is this task needed?
> API changed in 4.21, docs need updating to match
How will you know this is complete?
> All examples work with 4.21, new fields documented, no build warnings
Any technical details?
> Files: docs/content/how-to/autoscaling.md, docs/content/reference/api.md
Result:
Input:
/jira:create task MYPROJECT "Refactor validation logic to reduce duplication"
Interactive prompts:
What work needs to be done?
> Extract common validation code from three controller files into shared utility
Why is this needed?
> Code duplication makes maintenance difficult and error-prone
Acceptance criteria?
> - Validation extracted to support/validation package
> - All controllers use shared validation
> - Tests pass
> - New unit tests for validation utility
Any technical details?
> Files to modify:
> - controllers/nodepool/autoscaling.go
> - controllers/hostedcluster/autoscaling.go
> - controllers/manifests/autoscaling.go
> New file: support/validation/autoscaling.go
Result:
Input:
/jira:create task CNTRLPLANE "Add integration tests for node autoscaling" --parent CNTRLPLANE-100
Auto-applied:
Result:
Input:
/jira:create task CNTRLPLANE "Investigate intermittent timeouts in etcd health checks"
Description pattern for investigation tasks:
Investigate intermittent timeout errors occurring in etcd health checks on ROSA HCP clusters.
## Why
Users report clusters occasionally showing unhealthy status despite normal operation. Logs show intermittent timeout errors from etcd health checks.
## Acceptance Criteria
- Root cause identified and documented
- Recommendation provided (fix, workaround, or "no action needed")
- Findings shared with team in investigation summary
## Technical Details
Error pattern:
etcd health check failed: context deadline exceeded (timeout: 2s)
Frequency: ~5% of health checks
Affected clusters: ROSA HCP in us-east-1
Logs to review: control-plane-operator, etcd-operator
Related issues: OCPBUGS-1234 (similar symptoms)
Result:
❌ Vague summaries
"Update stuff"
"Fix things"
✅ Be specific: "Update autoscaling documentation for 4.21 API changes"
❌ User-facing work as tasks
"Add user dashboard feature"
✅ Should be a Story if it delivers user value
❌ Too large
"Refactor entire codebase"
"Update all documentation"
✅ Break into smaller, focused tasks
❌ No context
Summary: "Update docs"
Description: <empty>
✅ Always explain why and what specifically
/jira:create - Main command that invokes this skillcreate-story skill - For user-facing functionalitycntrlplane skill - CNTRLPLANE specific conventions
