# Create Jira Task

> Implementation guide for creating Jira tasks for technical and operational work Use when this capability is needed.

- Skill: `tomevault-io/create-jira-task` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add tomevault-io/create-jira-task`
- Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/create-jira-task/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Productivity
- Author: tomevault-io (https://skillmd.com/u/tomevault-io)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/tomevault-io/create-jira-task

---


# Create Jira Task

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.

## When to Use This Skill

This skill is automatically invoked by the `/jira:create task` command to guide the task creation process.

## Prerequisites

- MCP Jira server configured and accessible
- User has permissions to create issues in the target project
- Understanding of the technical work to be performed

**Reference Documentation:**
- [Markdown for Jira Reference](../../reference/markdown-for-jira.md) - Markdown formatting for Jira descriptions
- [MCP Tools Reference](../../reference/mcp-tools.md) - MCP tool signatures and custom fields
- [CLI Fallback Reference](../../reference/cli-fallback.md) - jira-cli commands (only if MCP unavailable)

## Tasks vs Stories

### When to Use a Task

Use a **Task** when the work is:
- **Technical/operational** - Infrastructure, refactoring, configuration
- **Not user-facing** - No direct end-user functionality
- **Internal improvement** - Code quality, performance, maintenance
- **Enabler work** - Supports future stories but isn't user-visible

**Examples of tasks:**
- "Update scaling documentation"
- "Refactor authentication utility package"
- "Configure CI pipeline for integration tests"
- "Upgrade dependency X to version Y"
- "Investigate performance regression in component Z"

### When to Use a Story Instead

Use a **Story** when the work:
- Delivers user-facing functionality
- Can be expressed as "As a... I want... so that..."
- Has business value to end users
- Is part of a user workflow

**If in doubt:** Ask "Would an end user notice or care about this change?"
- **Yes** → Story
- **No** → Task

## Task Best Practices

### Clear Summary

The summary should:
- Be concise (one sentence)
- Use action verbs (Update, Refactor, Configure, Investigate, Fix)
- Identify what is being changed
- Optionally include "why" if not obvious

**Good examples:**
- "Update autoscaling documentation for 4.21 release"
- "Refactor scaling controller to reduce code duplication"
- "Configure Prometheus alerts for control plane memory usage"
- "Investigate intermittent timeout in etcd health checks"

**Bad examples:**
- "Do some work on docs" (too vague)
- "Technical debt" (not specific)
- "Various improvements" (not actionable)

### Detailed Description

The description should include:

1. **What needs to be done** - Clear statement of the work
2. **Why it's needed** - Context or motivation
3. **Acceptance criteria** (optional but recommended) - How to know it's done
4. **Technical details** (if helpful) - Specific files, commands, approaches

**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
```

## Task Description Template

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>
```

## Interactive Task Collection Workflow

When creating a task, collect necessary information:

### 1. Task Description

**Prompt:** "What work needs to be done? Be specific about what you'll change or update."

**Helpful questions:**
- What component or area is being worked on?
- What specific changes will be made?
- What's the end state after this task is complete?

**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.
```

### 2. Motivation/Context

**Prompt:** "Why is this task needed? What problem does it solve?"

**Helpful questions:**
- What prompted this work?
- What will improve after this is done?
- Is this addressing a specific issue or enabling future work?

**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.
```

### 3. Acceptance Criteria (Optional but Recommended)

**Prompt:** "How will you know this task is complete? (Optional: skip if obvious)"

**For technical tasks, AC might include:**
- Tests passing
- Documentation updated
- Code review completed
- Specific functionality working

**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
```

### 4. Parent Link (Optional)

**Prompt:** "Is this task part of a larger story or epic? (Optional)"

**If yes:**
- Collect parent issue key
- Verify parent exists
- Link task to parent

### 5. Additional Technical Details (Optional)

**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
```

## Field Validation

Before submitting the task, validate:

### Required Fields
- ✅ Summary is clear and specific
- ✅ Description explains what needs to be done
- ✅ Description includes why (motivation)
- ✅ Component is specified (if required by project)
- ✅ Target version is set (if required by project)

### Task Quality
- ✅ Summary uses action verb (Update, Refactor, Configure, etc.)
- ✅ Work is technical/operational (not user-facing functionality)
- ✅ Description is detailed enough for someone else to understand
- ✅ Acceptance criteria present (if work is non-trivial)
- ✅ Task is sized appropriately (can complete in reasonable time)

### Security
- ✅ No credentials, API keys, or secrets in any field
- ✅ No sensitive technical details that shouldn't be public

## MCP Tool Parameters

### Basic Task Creation

```python
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
    }
)
```

### With Project-Specific Fields (e.g., CNTRLPLANE)

```python
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"}
    }
)
```

### With Parent Link

```python
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
    }
)
```

## Jira Description Formatting

Use Markdown formatting (the MCP tool converts it to Jira wiki markup automatically):

### Task Template Format

```markdown
<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](../../reference/markdown-for-jira.md).

## Error Handling

### Task vs Story Confusion

**Scenario:** User tries to create a task for user-facing functionality.

**Action:**
1. Detect user-facing language in summary/description
2. Ask if this should be a story instead
3. Explain the difference
4. Offer to create as story if appropriate

**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)
```

### Missing Context

**Scenario:** User provides minimal description without context.

**Action:**
1. Ask for more details
2. Prompt for "why" if missing
3. Suggest adding acceptance criteria if non-trivial

**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?
```

### Parent Not Found

**Scenario:** User specifies `--parent` but issue doesn't exist.

**Action:**
1. Attempt to fetch parent issue
2. If not found, inform user
3. Offer options: proceed without parent, specify different parent, cancel

**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?
```

### Security Validation Failure

**Scenario:** Sensitive data detected in task content.

**Action:**
1. STOP submission
2. Inform user what type of data was detected
3. Ask for redaction

**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.
```

### MCP Tool Error

**Scenario:** MCP tool returns an error when creating the task.

**Action:**
1. Parse error message
2. Provide user-friendly explanation
3. Suggest corrective action

**Common errors:**
- **"Field 'component' is required"** → Prompt for component
- **"Invalid parent"** → Verify parent issue exists and is correct type
- **"Permission denied"** → User may lack project permissions

## Examples

### Example 1: Documentation Task

**Input:**
```bash
/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:**
- Task created with complete description
- Target version: 4.21
- Component: HyperShift (or auto-detected)

### Example 2: Refactoring Task

**Input:**
```bash
/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:**
- Task with detailed technical plan
- Clear acceptance criteria
- Ready for implementation

### Example 3: Task with Parent

**Input:**
```bash
/jira:create task CNTRLPLANE "Add integration tests for node autoscaling" --parent CNTRLPLANE-100
```

**Auto-applied:**
- Linked to parent story CNTRLPLANE-100
- Inherits component from parent (if applicable)
- CNTRLPLANE conventions applied

**Result:**
- Task created under parent story
- All fields properly set

### Example 4: Investigation Task

**Input:**
```bash
/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:**
- Investigation task with clear scope
- Defined outcome (root cause + recommendation)
- Context for debugging

## Best Practices Summary

1. **Specific summaries:** Use action verbs, identify what's changing
2. **Explain why:** Always include motivation/context
3. **Add AC:** Even for tasks, AC helps define "done"
4. **Technical details:** Include file paths, commands, approaches when helpful
5. **Right size:** Task should be completable in reasonable time (days, not weeks)
6. **Link to parent:** If task supports a story/epic, link it
7. **Not a story:** If it's user-facing, create a story instead

## Anti-Patterns to Avoid

❌ **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

## Workflow Summary

1. ✅ Parse command arguments (project, summary, flags)
2. 🔍 Auto-detect component from summary keywords
3. ⚙️ Apply project-specific defaults
4. 💬 Interactively collect task description and context
5. 💬 Interactively collect acceptance criteria (optional)
6. 💬 Optionally collect technical details
7. 🔒 Scan for sensitive data
8. ✅ Validate task is appropriate (not a story)
9. 📝 Format description with Markdown
10. ✅ Create task via MCP tool
11. 📤 Return issue key and URL

## See Also

- `/jira:create` - Main command that invokes this skill
- `create-story` skill - For user-facing functionality
- `cntrlplane` skill - CNTRLPLANE specific conventions
- Agile task management best practices

---
> Converted and distributed by [TomeVault](https://tomevault.io/claim/openshift-eng) — claim your Tome and manage your conversions.
<!-- tomevault:4.0:skill_md:2026-04-11 -->