القائمة
Implementation guide for creating well-formed Jira user stories with acceptance criteria in SRVKP project
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
Implementation guide for creating well-formed Jira bug reports in SRVKP project
Implementation guide for creating Jira epics with proper scope and parent linking in SRVKP project
Implementation guide for creating Jira features that organize multiple epics into strategic initiatives for SRVKP project
Implementation guide for creating Jira tasks for technical and operational work in SRVKP project
Create and manage Jira issues (bugs, epics, stories, tasks) for SRVKP project with intelligent routing and project-specific conventions
| name | Create Jira Story |
| description | Implementation guide for creating well-formed Jira user stories with acceptance criteria in SRVKP project |
This skill provides implementation guidance for creating well-structured Jira user stories following agile best practices, including proper user story format and comprehensive acceptance criteria for the SRVKP project.
This skill is automatically invoked by the /jira:create story command to guide the story creation process.
acli installed and authenticatedShared conventions (safety rules, component table, confirmation flow, MCP→CLI fallback):
→ Read and follow ../_common.md before proceeding.
CLI reference: ../reference/cli-fallback.md
This skill is exclusively for SRVKP (OpenShift Pipelines project).
Component auto-suggestion keywords and the full component list are in ../_common.md.
Before collecting story details, search for similar existing stories to prevent duplicates.
Extract significant keywords from story summary (ignores common words like "the", "and", "in", "for", "to", "add", "create", "enable").
Example:
Input: "Sign all Image Manifests in Image Index recursively"
Keywords: ["sign", "image", "manifest", "index", "recursive"]
Use JQL to search for stories containing keywords:
acli jira workitem search \
--jql 'project = SRVKP AND issuetype = Story AND (summary ~ keyword1 OR ...)' \
--fields "key,summary,status"
Flag as potential duplicate if 3 or more keywords match.
Found similar stories in SRVKP:
1. SRVKP-11302: Avoid signing PipelineRun/TaskRun running in Spoke
Matched: signing, chains (2/5 keywords)
Status: To Do
2. SRVKP-9408: Chains - Improve code coverage for storage package
Matched: chains, storage (2/5 keywords)
Status: Closed
Options:
- Type '1' or '2': View that story and stop creation
- Type 'none': Proceed with creating new story
If user views existing story, do NOT create new one.
Search for appropriate parent Epic using keywords.
acli jira workitem search \
--jql 'project = SRVKP AND issuetype = Epic AND (summary ~ chains OR ...)' \
--fields "key,summary,status"
Searching for parent Epics for this story...
Found potential parent Epics:
1. SRVKP-11633: Recursive Image Manifest signing in Tekton Chains
Status: New
2. SRVKP-11142: Promote SLSAv1.0 offering of Chains format to beta
Status: New
Link this story to a parent Epic?
- Type '1' or '2': Select this Epic as parent
- Type 'none': Create standalone story (no parent)
Important: Stories can be created without a parent Epic. The 'none' option is always valid.
This is the #1 mistake when creating stories. The summary field and description field serve different purposes:
Good summary examples:
Bad summary examples:
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...
summary parameter, full story goes in descriptionA user story:
Every user story should have three components:
As a <User/Who>, I want to <Action/What>, so that <Purpose/Why>.
Components:
Who (User/Role): The person, device, or system that will benefit from or use the output
What (Action): What they can do with the system
Why (Purpose): Why they want to do the activity, the value they gain
As a cluster admin, I want to configure automatic node pool scaling based on CPU utilization, so that I can handle traffic spikes without manual intervention.
As a developer, I want to view real-time cluster metrics in the web console, so that I can quickly identify performance issues before they impact users.
As an SRE, I want to set up alerting rules for control plane health, so that I can be notified immediately when issues occur.
❌ "Add scaling feature"
❌ "As a user, I want better performance"
❌ "Implement autoscaling API"
✅ Convert to: "As a cluster admin, I want to configure autoscaling policies via the API, so that I can automate cluster capacity management"
Acceptance criteria:
Choose the format that best fits the story:
- Test that <criteria>
Example:
- Test that node pools scale up when CPU exceeds 80%
- Test that node pools scale down when CPU drops below 30%
- Test that scaling respects configured min/max node limits
- Demonstrate that <this happens>
Example:
- Demonstrate that scaling policies can be configured via CLI
- Demonstrate that scaling events appear in the audit log
- Demonstrate that users receive notifications when scaling occurs
- Verify that when <a role> does <some action> they get <this result>
Example:
- Verify that when a cluster admin sets max nodes to 10, the node pool never exceeds 10 nodes
- Verify that when scaling is disabled, node count remains constant regardless of load
- Given <a context> when <this event occurs> then <this happens>
Example:
- Given CPU utilization is at 85%, when the scaling policy is active, then a new node is provisioned within 2 minutes
- Given the node pool is at maximum capacity, when scaling is triggered, then an alert is raised and no nodes are added
You have enough AC when:
If you need more AC:
If AC is too detailed:
When creating a story, guide the user through the process:
Prompt: "Let's create the user story. I can help you format it properly."
Ask three questions:
Who benefits?
Who is the user or role that will benefit from this feature?
Examples: cluster admin, developer, SRE, end user, system administrator
What action?
What do they want to be able to do?
Examples: configure autoscaling, view metrics, set up alerts
What value/why?
Why do they want this? What value does it provide?
Examples: to handle traffic spikes, to improve visibility, to reduce downtime
Construct the story:
As a <answer1>, I want to <answer2>, so that <answer3>.
Present to user and ask for confirmation:
Here's the user story:
As a cluster admin, I want to configure automatic node pool scaling, so that I can handle traffic spikes without manual intervention.
Does this look correct? (yes/no/modify)
Prompt: "Now let's define the acceptance criteria. These help the team know when the story is complete."
Approach 1: Guided Questions
Ask probing questions:
1. What are the key behaviors that must work?
2. What are the edge cases or boundaries?
3. How will this be tested?
4. What shouldn't happen?
Approach 2: Template Assistance
Offer format templates:
Which format would you like to use for acceptance criteria?
1. Test that... (test-based)
2. Verify that when... they get... (verification-based)
3. Given... when... then... (BDD)
4. I'll write them in my own format
Approach 3: Free-Form
Please provide the acceptance criteria (one per line, or I can help you structure them):
Validate AC:
Prompt: "Any additional context for the team? (Optional)"
Helpful additions:
Example:
Additional Context:
- This builds on the existing monitoring infrastructure introduced in PROJ-100
- Must integrate with Prometheus metrics
- Out of scope: Custom metrics (will be separate story)
- Design doc: https://docs.example.com/autoscaling-design
A well-sized story:
Split a story if:
By workflow steps:
Original: As a user, I want to manage my account settings
Split:
- As a user, I want to view my account settings
- As a user, I want to update my account settings
- As a user, I want to delete my account
By acceptance criteria:
Original: Complex story with 10 AC
Split:
- Story 1: AC 1-4 (core functionality)
- Story 2: AC 5-7 (edge cases)
- Story 3: AC 8-10 (advanced features)
By platform/component:
Original: Add feature to all platforms
Split:
- Add feature to web interface
- Add feature to CLI
- Add feature to API
Before submitting the story, validate:
Follow the MCP → CLI Fallback Decision Tree in ../_common.md.
Basic story creation:
acli jira workitem create \
--project "SRVKP" \
--type "Story" \
--summary "Enable task result caching" \
--description "$(cat <<'EOF'
As a pipeline developer, I want to cache task results, so that I can reduce build time.
h2. Acceptance Criteria
* Test that tasks can opt-in to caching
* Test that cache key is computed correctly
* Verify that cached results are restored
EOF
)" \
--label "ai-generated-jira" \
--json
Story with parent epic:
acli jira workitem create \
--project "SRVKP" \
--type "Story" \
--summary "Enable task result caching" \
--description "$(cat <<'EOF'
As a pipeline developer, I want to cache task results, so that I can reduce build time.
h2. Acceptance Criteria
* Test that tasks can opt-in to caching
* Test that cache key is computed correctly
EOF
)" \
--parent "SRVKP-11633" \
--label "ai-generated-jira" \
--json
Note: Use $(cat <<'EOF' ... EOF) for inline multi-line descriptions. No temp files needed.
Full example:
acli jira workitem create \
--project "SRVKP" \
--type "Story" \
--summary "Enable task result caching for faster pipeline execution" \
--description "$(cat <<'EOF'
As a pipeline developer, I want to cache task results based on input parameters and source code changes, so that I can skip re-executing tasks when inputs haven't changed, reducing build time and costs.
h2. Acceptance Criteria
* Tasks can opt-in to caching by adding cache annotations
* Cache key is computed from task inputs, parameters, and workspace content hashes
* Cached results are restored when cache key matches
* Cache hit shows "Skipped (cache hit)" in TaskRun status
* Users can configure cache retention policy (default 7 days)
* Cache works across different PipelineRuns
* Cache misses fall back to normal task execution
h2. Additional Context
This builds on the Tekton Cache component. Must integrate with existing workspace mechanisms. Target: Pipelines 1.16
Out of scope: Workspace content caching (will be separate story)
EOF
)" \
--parent "SRVKP-9000" \
--label "ai-generated-jira" \
--json
When linking a story to a parent epic, use the --parent flag:
# Create story with parent epic
acli jira workitem create \
--project "SRVKP" \
--type "Story" \
--summary "Add cache metrics to pipeline results API" \
--description "$(cat <<'EOF'
As a DevOps engineer, I want to view cache hit/miss metrics in the pipeline results, so that I can optimize caching strategies.
h2. Acceptance Criteria
* Cache metrics appear in TaskRun status
* Metrics show hit rate percentage
* Historical cache data is queryable
EOF
)" \
--parent "SRVKP-11633" \
--label "ai-generated-jira" \
--json
Important:
--parent flag with the parent Epic key (e.g., "SRVKP-11633")customfield_12311140 for epic linking--parent flag)$(cat <<'EOF' ... EOF) for inline descriptions (no temp files)Use Jira's native formatting (Wiki markup):
As a <user>, I want to <action>, so that <value>.
h2. Acceptance Criteria
* Test that <criteria 1>
* Verify that <criteria 2>
* Given <context> when <event> then <outcome>
h2. Additional Context
<optional context>
h3. Dependencies
* [PROJ-123] - Parent epic or related story
h3. Out of Scope
* Feature X (will be separate story)
* Platform Y support (future release)
Use Jira wiki markup in descriptions (for example h2. headings and * lists) as needed.
Scenario: User provides a story that doesn't follow the template.
Action:
Example:
The story "Add autoscaling" doesn't follow the user story format.
Let me help you structure it:
- Who will use this feature? (e.g., cluster admin, developer)
- What do they want to do? (e.g., configure autoscaling)
- Why do they want it? (e.g., to handle traffic spikes)
Scenario: User doesn't provide acceptance criteria.
Action:
Example:
Acceptance criteria help define when this story is complete. Let's add some.
What are the key behaviors that must work for this story?
For example:
- What actions should users be able to perform?
- What should happen in edge cases?
- How will you know the feature works correctly?
Scenario: Story has too many acceptance criteria or sounds too complex.
Action:
Example:
This story has 12 acceptance criteria, which suggests it might be too large for one sprint.
I can help split this into smaller stories:
1. Core functionality (AC 1-4)
2. Advanced features (AC 5-8)
3. Edge cases and validation (AC 9-12)
Would you like me to create these as separate stories under an epic?
Scenario: AC is too vague or not testable.
Action:
Example:
This acceptance criteria is a bit vague: "Test that it works well"
Can you be more specific? For example:
- What does "works well" mean? (fast response time? handles errors?)
- How would you test this? (what specific behavior would you verify?)
Suggested revision: "Verify that API response time is under 100ms for 95% of requests"
Scenario: Sensitive data detected in story content.
Action:
Example:
I detected what appears to be API credentials in the acceptance criteria.
Please use placeholder values like "YOUR_API_KEY" instead of real credentials.
Scenario: MCP tool returns an error when creating the story.
Action:
Common errors:
Input:
/jira:create story "Add pipeline execution dashboard to Tekton UI"
Conversation:
Let's create the user story. I'll ask a few questions:
Who is the user or role that will benefit from this feature?
> Pipeline operators and developers
What do they want to be able to do?
> View a dashboard showing active pipeline executions with real-time status updates
Why do they want this? What value does it provide?
> To quickly monitor running pipelines and identify failures without checking individual PipelineRun resources
Great! Here's the user story:
As a pipeline operator, I want to view a dashboard showing active pipeline executions with real-time status updates, so that I can quickly monitor running pipelines and identify failures without checking individual PipelineRun resources.
Does this look correct?
> Yes
Now let's define acceptance criteria. What are the key behaviors that must work?
> 1. Dashboard shows all running PipelineRuns
> 2. Real-time updates when status changes
> 3. Color-coded status indicators (running, succeeded, failed)
> 4. Users can filter by namespace and pipeline name
Excellent. I'll format these as test-based criteria:
* Test that dashboard displays all running PipelineRuns across namespaces
* Test that dashboard updates in real-time when PipelineRun status changes
* Verify that status is shown with color-coded indicators (green/yellow/red)
* Verify that users can filter PipelineRuns by namespace and pipeline name
Any additional context?
> This builds on the existing Tekton UI. Must integrate with Results API for historical data.
Perfect! Creating the story now...
Result:
Created: SRVKP-12345
Title: Add pipeline execution dashboard to Tekton UI
Component: UI
URL: https://issues.redhat.com/browse/SRVKP-12345
Input:
/jira:create story "Enable webhook retry logic for failed trigger events"
Auto-applied:
Interactive prompts:
Result:
Input:
/jira:create story "Add cache metrics to Results API" --parent SRVKP-9000
Implementation:
additional_fields={
"customfield_12311140": "SRVKP-9000", # Epic Link (NOT parent field!)
"labels": ["ai-generated-jira"]
}
Result:
See: /jira:create command documentation for complete parent linking implementation strategy
Input:
/jira:create story "Enable task result caching for faster pipeline execution"
Interactive prompts:
Who is the user or role that will benefit from this feature?
> Pipeline developers and CI/CD engineers
What do they want to be able to do?
> Cache task results to avoid re-executing unchanged tasks in subsequent pipeline runs
Why do they want this? What value does it provide?
> To significantly reduce pipeline execution time and resource consumption for incremental builds
Here's the user story:
As a pipeline developer, I want to cache task results based on input parameters and source code changes, so that I can skip re-executing tasks when inputs haven't changed, reducing build time and costs.
Does this look correct?
> Yes
Now let's define acceptance criteria:
> - Tasks can opt-in to caching by adding cache annotations
> - Cache key is computed from task inputs, parameters, and workspace content hashes
> - Cached results are restored when cache key matches
> - Cache hit shows "Skipped (cache hit)" in TaskRun status
> - Users can configure cache retention policy (default 7 days)
> - Cache works across different PipelineRuns and clusters
> - Cache misses fall back to normal task execution
Any additional context?
> This builds on the new Tekton Cache component. Must integrate with existing workspace mechanisms. Target: OpenShift Pipelines 1.15 / Tekton v0.60.
Component Suggestion:
Result:
❌ Technical tasks disguised as stories
As a developer, I want to refactor the database layer
✅ Use a Task instead, or reframe with user value
❌ Too many stories in one
As a user, I want to create, edit, delete, and share documents
✅ Split into 4 separate stories
❌ Vague acceptance criteria
- Test that it works correctly
- Verify good performance
✅ Be specific: "Response time under 200ms", "Handles 1000 concurrent users"
❌ Implementation details in AC
- Test that the function uses Redis cache
- Verify that the API calls the UserService.get() method
✅ Focus on user-observable behavior, not implementation
Follow the Mandatory Confirmation Flow and MCP → CLI Fallback Decision Tree defined
in ../_common.md. The preview label for this type is PREVIEW: SRVKP User Story.
acli on fallback (use --parent when linking to an epic)/jira:create - Main command that invokes this skill (includes Issue Hierarchy and Parent Linking documentation)create-epic skill - For creating parent epics