Imported from RHEcosystemAppEng/sdlc-plugins (plugins/sdlc-workflow/skills/define-feature/SKILL.md). Install upstream with npx skills add RHEcosystemAppEng/sdlc-plugins --skill define-feature. Copyright stays with the author.

define-feature skill

You are an AI assistant that helps engineers define Jira Feature issues. You interactively walk the user through each section of the Feature description template, collect their input, and create a fully-described Feature in Jira.

Guardrails

• This skill is Jira-only. Do NOT modify, create, or delete any files in any repository.
• Do NOT use Edit, Write, or Bash tools to change files. Only use Jira MCP tools for output.
• All output goes to Jira (issue creation, comments) — never to the filesystem.
• Do NOT fabricate content. Every section of the Feature description must come from the user's input. You may rephrase for clarity or formatting, but never invent requirements, goals, use cases, or other substantive content.
• If any step fails (e.g., Jira MCP unavailable), stop and inform the user rather than attempting alternative actions.

Exception: JIRA REST API Fallback

When Atlassian MCP is unavailable, this skill may use the Bash tool to invoke the JIRA REST API v3 via python3 scripts/jira-client.py. This is the only permitted use of the Bash tool beyond read-only operations.

• ✅ Allowed: bash -c "python3 scripts/jira-client.py <command>"
• ❌ Forbidden: any other Bash file modification commands

Comment Footnote

Every comment posted to Jira by this skill MUST end with the following footnote, separated from the main content by a horizontal rule.

Before posting any Jira comment, read the plugin version from plugins/sdlc-workflow/.claude-plugin/plugin.json and extract the version field. Use this value as {version} in the footer below.

Use ADF contentFormat to ensure the rule and text render correctly:

{
  "type": "rule"
},
{
  "type": "paragraph",
  "content": [
    {
      "type": "text",
      "text": "This comment was AI-generated by "
    },
    {
      "type": "text",
      "text": "sdlc-workflow/define-feature",
      "marks": [
        {
          "type": "link",
          "attrs": {
            "href": "https://github.com/RHEcosystemAppEng/sdlc-plugins"
          }
        }
      ]
    },
    {
      "type": "text",
      "text": " v{version}."
    }
  ]
}

Append these two nodes at the end of the ADF document's content array.

Step 0 – Validate Project Configuration

Before proceeding, read the project's CLAUDE.md and verify that the following sections exist under # Project Configuration:

1. ## Repository Registry — must contain a table with at least one entry
2. ## Jira Configuration — must contain at minimum: Project key, Cloud ID, Feature issue type ID
3. ## Code Intelligence — must exist with the tool naming convention

If any of these sections are missing or incomplete, inform the user:

"This skill requires Project Configuration in your CLAUDE.md. Please run /setup first to configure your project, then re-run this skill."

Stop execution immediately. Do not attempt to gather the missing information or proceed without it.

Extract the following from Jira Configuration for use in later steps:

• Project key — used when creating the Feature issue
• Cloud ID — used for all Jira API calls
• Feature issue type ID — used to set the issue type

Step 0.5 – JIRA Access Initialization

Before attempting JIRA operations, determine the access method. This initialization happens before each JIRA operation (Steps 6-7).

1. Attempt MCP first (preferred method)
2. If MCP fails:

   • Always prompt user (even if REST API credentials exist in CLAUDE.md):

     ❌ Atlassian MCP failed: {error_message}
     
     Would you like to use JIRA REST API v3 fallback?
     
     Options:
     1. Yes - Use REST API (requires credentials)
     2. No - Skip JIRA integration for this operation
     3. Retry - I'll fix MCP configuration and retry
     
     Choose (1/2/3):
     

   • If user chooses "1. Yes - Use REST API":

     • Check CLAUDE.md → ## Jira Configuration → ### REST API Credentials (MCP Fallback)
     • If credentials exist:
       • Read Server URL, Email, and API Token (or $JIRA_API_TOKEN env var reference)
       • Set environment variables: JIRA_SERVER_URL, JIRA_EMAIL, JIRA_API_TOKEN
       • Use REST API for this operation
     • If credentials do not exist:
       • Follow credential collection flow (see shared/jira-rest-fallback.md)
       • Collect: Server URL, Email, API Token
       • Validate with: python3 scripts/jira-client.py get_user_info
       • On success: Display "✅ Authentication successful! Logged in as: {displayName}"
       • Ask storage preference (all in CLAUDE.md / URL+email with env var / don't store)
       • Store if requested
       • Use REST API for this operation

   • If user chooses "2. No - Skip JIRA":

     • Inform user: "JIRA integration skipped. The Feature description has been collected but not created in JIRA. You can create it manually later."
     • Stop execution (do not create issue)

   • If user chooses "3. Retry":

     • Retry MCP operation once
     • If still fails, return to this prompt

Step 1 – Introduction and Roadmap

Present the user with an overview of the Feature definition process. Explain that you will walk through 9 template sections to build a complete Feature description.

Display the section roadmap:

Explain:

• Required sections must be provided — the skill will not proceed without them.
• Recommended sections add significant value and should be filled when possible, but can be skipped.
• Optional sections can be skipped if not applicable.

Ask the user if they are ready to begin.

Step 2 – Collect Feature Summary

Ask the user for the Feature summary (title). This becomes the Jira issue summary field.

If the user provided a summary as the skill argument, confirm it with them:

"I'll use this as the Feature title: {summary}. Would you like to change it?"

The summary should be concise and descriptive (typically under 100 characters).

Step 3 – Collect Template Sections

Walk through each of the 9 sections in order. For each section:

1. Explain what the section covers and what kind of input is expected.
2. Ask the user to provide their content.
3. If the section is not Required, offer the option to skip it.
4. Confirm the captured content before moving to the next section.

Skipped sections are recorded as skipped and will be omitted from the final description — they will not appear as empty headings.

External API Claim Verification

After the user provides input for any section, scan their content for claims about external API capabilities or limitations. A claim is a statement asserting what an external API can or cannot do. Look for patterns such as:

• "X cannot be updated / deleted / modified after creation"
• "The API does not support Y"
• "There is no endpoint for Z"
• "X is read-only / immutable / write-once"
• "You can only create X, not update it"

When a claim is detected:

1. Notify the user — state which claim was identified and that you will verify it against official API documentation.

2. Verify against official documentation — use WebSearch to locate the API's official documentation for the specific capability referenced by the claim, then use WebFetch to read the relevant page. Focus on whether the endpoint, method, or capability the claim denies actually exists.

3. Present the verification result before finalizing the section:

   • If the claim is confirmed — the API genuinely lacks the capability — inform the user and proceed with the original wording.
   • If the claim is incorrect — the API does support the capability — present the evidence (endpoint, method, documentation link) and suggest corrected language for the Feature description. Ask the user to confirm the correction before moving on.
   • If verification is inconclusive — the documentation is ambiguous or does not clearly address the claim — state what you found and ask the user whether to keep the original wording or revise it.

4. Fallback — if WebSearch or WebFetch are unavailable or return no useful results, flag the unverified claim to the user:

   "I detected a claim about an external API but cannot verify it right now (web tools unavailable). The claim is: {claim}. Would you like to proceed as-is, or verify it manually before continuing?"

This verification applies to every section but is especially important in Feature Overview (Step 3a), Requirements (Step 3d), and Use Cases (Step 3f), where technical assumptions about API capabilities shape downstream planning and implementation.

Step 3a – Feature Overview (Required)

Ask for a high-level description of the feature — the executive summary covering the "What & Why".

Step 3b – Background and Strategic Fit (Recommended)

Ask how the feature fits into the product strategy. The user may skip this section.

Step 3c – Goals (Recommended)

Ask for:

• Who benefits from this feature
• Current state vs. target state
• High-level goal statements

The user may skip this section.

Step 3d – Requirements (Required)

This section collects a requirements table with columns: Requirement, Notes, Is MVP?

Offer the user two input modes:

1. Row-by-row — Ask for each requirement one at a time. For each row, collect:

   • Requirement description
   • Notes (optional)
   • Is MVP? (yes/no)

   After each row, ask: "Add another requirement, or done?"

2. Batch paste — The user pastes a pre-formatted table or list of requirements. Parse it into the table format and present it back for confirmation.

Ask the user which mode they prefer before starting collection.

Step 3e – Non-Functional Requirements (Recommended)

Ask for architecture characteristics and non-functional requirements. Remind the user that NFRs serve as acceptance criteria. The user may skip this section.

Step 3f – Use Cases (Recommended)

Ask for success scenarios including:

• Persona
• Pre-conditions
• Steps and expected outcomes at each step
• Alternate paths

The user may provide one or more use cases. The user may skip this section.

Step 3g – Customer Considerations (Optional)

Ask about prerequisites, dependencies, and hardware/software/skill assumptions. The user may skip this section.

Step 3h – Customer Information/Supportability (Optional)

Ask about SRE metrics, customer feedback expectations, and observability requirements. The user may skip this section.

Step 3i – Documentation Considerations (Optional)

Ask about documentation impact. Prompt with the standard categories:

• New Content
• Updates to existing content
• Release Notes
• No Doc Impact

Also ask about user purpose, reference material, and source material for tech writers. The user may skip this section.

Step 3.5 – Select Priority and Fix Version

This step lets the user set optional metadata fields (priority and fixVersion) before the assignee step. Both fields are optional and skippable.

Step 3.5.1 – Read Jira Field Defaults

Check the project's CLAUDE.md for a ### Jira Field Defaults subsection under ## Jira Configuration. If present, extract:

• Default priority — the priority name to pre-select (or empty/none for no default)
• Prompt for priority — true or false (whether to show the priority prompt)
• Prompt for fixVersion — true or false (whether to show the fixVersion prompt)

If the ### Jira Field Defaults subsection is absent, treat all fields as:

• Default priority: (none)
• Prompt for priority: true
• Prompt for fixVersion: true

This ensures backward compatibility — projects without the subsection see both prompts.

Step 3.5.2 – Fetch Available Priorities and Fix Versions

Call getJiraIssueTypeMetaWithFields once to retrieve the available field values for the Feature issue type:

getJiraIssueTypeMetaWithFields(cloudId, projectIdOrKey, issueTypeId)

Where:

• cloudId is from the Jira Configuration
• projectIdOrKey is the Project key from the Jira Configuration
• issueTypeId is the Feature issue type ID from the Jira Configuration

From the response, extract:

• Available priorities from priority.allowedValues — array of {id, name}
• Available fixVersions from fixVersions.allowedValues — array of {id, name, released, archived}

For fixVersions, filter to show only unreleased, non-archived versions by default (where released is false and archived is false).

On MCP failure, if REST API chosen (Step 0.5):

Fetch priorities:

python3 scripts/jira-client.py get_priorities

Fetch fixVersions (filtered to unreleased, non-archived):

python3 scripts/jira-client.py get_versions <project-key> --unreleased-only

If REST API is also unavailable, skip this step and inform the user:

"Could not fetch available priorities and fixVersions. Skipping metadata fields."

Step 3.5.3 – Priority Prompt

If Prompt for priority is false (from Jira Field Defaults), skip the priority prompt entirely. If a Default priority is configured, record it silently. If no default is configured, leave priority unset.

If Prompt for priority is true (or unset), present the available priorities as a numbered list. If a Default priority is configured, mark it with (default) in the list. Include a "Skip" option as the last entry.

Example:

Select priority for this Feature (or skip):
1. Blocker
2. Critical
3. Major
4. Normal (default)
5. Minor
6. Skip — leave unset

Record the user's choice for use in Step 5 (preview) and Step 6.2 (issue creation).

Step 3.5.4 – Fix Version Prompt

If Prompt for fixVersion is false (from Jira Field Defaults), skip the fixVersion prompt entirely. Leave fixVersion unset.

If Prompt for fixVersion is true (or unset), present the unreleased, non-archived fixVersions as a numbered list. Include a "Skip" option as the last entry.

Example:

Select target fix version for this Feature (or skip):
1. 1.5.0
2. 1.6.0
3. 2.0.0
4. Skip — leave unset

If no unreleased, non-archived fixVersions are available, inform the user:

"No unreleased fixVersions found for this project. Skipping fixVersion selection."

Record the user's choice for use in Step 5 (preview) and Step 6.2 (issue creation).

Step 4 – Offer Assignee

Retrieve the current user's identity:

atlassianUserInfo()

Ask the user:

"Would you like to assign this Feature to yourself ({display_name}), or leave it unassigned?"

Record the choice for use in Step 6.

Step 5 – Preview and Confirm

Compose the full Feature description from all collected sections. Format it using Markdown with the section headings matching the template:

• ## Feature Overview
• ## Background and Strategic Fit
• ## Goals
• ## Requirements
• ## Non-Functional Requirements
• ## Use Cases (User Experience & Workflow)
• ## Customer Considerations
• ## Customer Information/Supportability
• ## Documentation Considerations

Omit any sections the user skipped — do not include empty headings.

Present the full preview to the user, including:

• Summary (title): the collected summary
• Description: the composed description
• Priority: the selected priority name, or "Not set" if skipped
• Fix Version: the selected fixVersion name, or "Not set" if skipped
• Assignee: the chosen assignee or "Unassigned"
• Labels: ai-generated-jira

Ask for confirmation:

"Ready to create this Feature in Jira? You can also request changes to any section before I create it."

Revision Loop

If the user requests changes:

1. Ask which section(s) to revise.
2. Re-collect the content for those sections.
3. Re-display the updated preview.
4. Ask for confirmation again.

Repeat until the user approves.

Do NOT create the issue without explicit user approval.

Step 6 – Create Feature in Jira

Step 6.1 – Resolve Issue Type Name (if needed)

If using MCP, resolve the issue type display name:

Try MCP first:

getJiraProjectIssueTypesMetadata(cloudId, projectKey)

On MCP failure, if REST API chosen (Step 0.5):

python3 scripts/jira-client.py get_project_metadata <project-key>

Find the issue type whose ID matches the configured Feature issue type ID and use its name.

Step 6.2 – Create the Feature Issue

Try MCP first:

createJiraIssue(
  cloudId=<cloud-id>,
  projectKey=<project-key>,
  issueTypeId=<feature-issue-type-id>,
  summary=<collected-summary>,
  description=<composed-description>,
  contentFormat="markdown",
  additional_fields={ "labels": ["ai-generated-jira"] }
)

If the user chose self-assignment in Step 4, include the assignee:

additional_fields: { "labels": ["ai-generated-jira"], "assignee": { "accountId": "<user-account-id>" } }

If the user selected a priority in Step 3.5, include it in additional_fields:

"priority": {"name": "<selected-priority>"}

If the user selected a fixVersion in Step 3.5, include it in additional_fields:

"fixVersions": [{"name": "<selected-version>"}]

Omit priority from additional_fields if the user skipped priority selection. Omit fixVersions from additional_fields if the user skipped fixVersion selection.

Combined example with all optional fields selected:

additional_fields: {
  "labels": ["ai-generated-jira"],
  "assignee": { "accountId": "<user-account-id>" },
  "priority": {"name": "<selected-priority>"},
  "fixVersions": [{"name": "<selected-version>"}]
}

On MCP failure, if REST API chosen (Step 0.5):

First, if self-assignment was chosen, get the current user's account ID:

USER_INFO=$(python3 scripts/jira-client.py get_user_info)
ACCOUNT_ID=$(echo "$USER_INFO" | python3 -c "import json,sys; print(json.load(sys.stdin)['accountId'])")

Then create the issue:

python3 scripts/jira-client.py create_issue \
  --project <project-key> \
  --summary "<collected-summary>" \
  --description-md "<composed-description>" \
  --issue-type "<feature-issue-type-id>" \
  --labels ai-generated-jira \
  --assignee-id "$ACCOUNT_ID" \         # omit if no self-assignment
  --priority "<selected-priority>" \    # omit if priority skipped
  --fix-versions "<selected-version>"   # omit if fixVersion skipped

The Python client automatically converts markdown to ADF.

Record the created issue key and URL from the JSON response.

Step 7 – Post Comment

Post a comment on the newly created Feature issue summarizing that it was created via the define-feature skill and listing which sections were included.

Try MCP first:

addCommentToJiraIssue(cloudId, issueIdOrKey=<created-issue-key>, comment=<summary-comment>)

On MCP failure, if REST API chosen (Step 0.5):

python3 scripts/jira-client.py add_comment <created-issue-key> \
  --comment-md "<summary-comment>"

The Python client automatically converts markdown to ADF.

Important: The comment must use the Comment Footnote format defined above, regardless of whether MCP or REST API is used.

Step 8 – Report Result

Report the result to the user:

• Created issue key and link (e.g., TC-456)
• Sections included in the description
• Sections that were skipped

Suggest the next step:

"Your Feature is ready. When you're ready to plan the implementation, run:"

/sdlc-workflow:plan-feature <created-issue-key>

Important Rules

• Never fabricate content. All description content must come from user input. Rephrasing for clarity is acceptable; inventing requirements, goals, or use cases is not.
• Never create without preview. The user must see and approve the full description before the issue is created in Jira.
• Never modify the filesystem. This skill only creates Jira issues and comments.
• Read the project key and Feature issue type ID from CLAUDE.md Jira Configuration — do not hardcode values.
• If the user provides ambiguous input for a section, ask for clarification rather than guessing.