Initial commit
This commit is contained in:
Zhongwei Li
486
skills/story-refiner/SKILL.md
Normal file
486
skills/story-refiner/SKILL.md
Normal file
@@ -0,0 +1,486 @@
|
||||
---
|
||||
name: story-refiner
|
||||
description: Analyzes Jira stories and proposes improvements for quality, clarity, acceptance criteria, and completeness
|
||||
allowed-tools: mcp__atlassian__*
|
||||
mcpServers:
|
||||
- atlassian
|
||||
---
|
||||
|
||||
# Story Refiner Skill
|
||||
|
||||
This skill analyzes Jira stories and proposes specific, actionable improvements to enhance story quality, clarity, and completeness.
|
||||
|
||||
## When This Skill is Invoked
|
||||
|
||||
Claude will automatically use this skill when you mention:
|
||||
- "refine story"
|
||||
- "improve story quality"
|
||||
- "enhance acceptance criteria"
|
||||
- "fix story description"
|
||||
- "story improvement suggestions"
|
||||
|
||||
## Capabilities
|
||||
|
||||
### 1. Story Analysis
|
||||
Fetch and analyze a Jira story to identify improvement opportunities.
|
||||
|
||||
**Quality Dimensions Analyzed:**
|
||||
- **Acceptance Criteria:** Completeness, testability, clarity
|
||||
- **Description:** User value, context, technical details
|
||||
- **Story Format:** User story structure (As a... I want... So that...)
|
||||
- **Refinement:** Story points, labels, components
|
||||
- **Documentation:** Supporting links, attachments, examples
|
||||
|
||||
### 2. Improvement Proposal Generation
|
||||
Generate specific, actionable proposals for enhancing the story.
|
||||
|
||||
**Proposal Structure:**
|
||||
```markdown
|
||||
## Proposed Changes for [STORY-KEY]
|
||||
|
||||
### Current State Assessment
|
||||
- **Quality Score:** 65/100 (Good)
|
||||
- **Main Issues:** Missing acceptance criteria, unclear scope
|
||||
- **Strengths:** Clear user value, good description length
|
||||
|
||||
### Recommended Changes
|
||||
|
||||
#### 1. Add Acceptance Criteria (High Priority)
|
||||
**Current:** No acceptance criteria defined
|
||||
**Proposed:**
|
||||
```
|
||||
Acceptance Criteria:
|
||||
- Given a logged-in user
|
||||
When they click "Export Report"
|
||||
Then a PDF report downloads within 5 seconds
|
||||
- Report includes all data from selected date range
|
||||
- Error message shown if date range exceeds 1 year
|
||||
```
|
||||
**Impact:** Improves testability and clarity
|
||||
|
||||
#### 2. Enhance Description (Medium Priority)
|
||||
**Current:** "Add export feature"
|
||||
**Proposed:** Add technical context:
|
||||
```
|
||||
Technical Notes:
|
||||
- Use existing PDF library (pdfkit)
|
||||
- Add export button to dashboard header
|
||||
- Store exports in /tmp (auto-cleanup after 1 hour)
|
||||
- Max file size: 10MB
|
||||
```
|
||||
**Impact:** Reduces ambiguity, speeds development
|
||||
|
||||
#### 3. Add Story Points (Medium Priority)
|
||||
**Recommendation:** Estimate as 5 points based on similar stories
|
||||
**Rationale:** Comparable to PROJ-123 (PDF export feature)
|
||||
```
|
||||
|
||||
### 3. Diff Generation
|
||||
Show exact before/after for proposed changes to fields.
|
||||
|
||||
**Example:**
|
||||
```diff
|
||||
=== Description ===
|
||||
- As a user, I want to export reports
|
||||
+ As a user, I want to export dashboard reports to PDF format
|
||||
+ So that I can share insights with stakeholders offline
|
||||
+
|
||||
+ Technical Implementation:
|
||||
+ - Add "Export to PDF" button in dashboard header
|
||||
+ - Use pdfkit library for PDF generation
|
||||
+ - Include all visible widgets and date range
|
||||
+ - Max export size: 10MB
|
||||
|
||||
=== Acceptance Criteria ===
|
||||
+ Acceptance Criteria:
|
||||
+ - Given a logged-in user viewing the dashboard
|
||||
+ When they click "Export to PDF"
|
||||
+ Then a PDF file downloads within 5 seconds
|
||||
+ - Report includes dashboard title and selected date range
|
||||
+ - Report includes all visible widgets with current data
|
||||
+ - Error message displays if export exceeds size limit
|
||||
```
|
||||
|
||||
### 4. Impact Assessment
|
||||
Estimate the impact of proposed changes on story quality.
|
||||
|
||||
**Metrics:**
|
||||
- **Quality Score Improvement:** Before vs. After
|
||||
- **Confidence Level:** High/Medium/Low that changes will help
|
||||
- **Effort to Implement:** Time to apply changes (Low/Medium/High)
|
||||
|
||||
## How to Use This Skill
|
||||
|
||||
### Step 1: Fetch Story from Jira
|
||||
|
||||
**Use Atlassian MCP to get story details:**
|
||||
```
|
||||
mcp__atlassian__jira_get_issue(
|
||||
issueKey="PROJ-123",
|
||||
fields=["summary", "description", "acceptanceCriteria", "storyPoints", "labels", "components", "status", "priority", "assignee"]
|
||||
)
|
||||
```
|
||||
|
||||
### Step 2: Analyze Story Quality
|
||||
|
||||
**Assess each quality dimension:**
|
||||
|
||||
1. **Acceptance Criteria Check:**
|
||||
- Look for AC in custom fields (acceptanceCriteria, AC, acceptance_criteria, DoD)
|
||||
- Check description for "Acceptance Criteria:" section
|
||||
- Evaluate completeness: Are all paths covered?
|
||||
- Evaluate testability: Are criteria measurable?
|
||||
|
||||
2. **Description Quality:**
|
||||
- Check for user story format (As a... I want... So that...)
|
||||
- Assess length and detail level (>100 words ideal)
|
||||
- Verify context explains WHY (user value/problem)
|
||||
- Check for technical details where appropriate
|
||||
|
||||
3. **Refinement Indicators:**
|
||||
- Story points assigned?
|
||||
- Labels/components tagged?
|
||||
- Supporting documentation linked?
|
||||
- Sprint assigned?
|
||||
|
||||
4. **Clarity & Completeness:**
|
||||
- Is scope clear (what's included/excluded)?
|
||||
- Are edge cases mentioned?
|
||||
- Is technical approach defined (if needed)?
|
||||
- Are dependencies noted?
|
||||
|
||||
### Step 3: Generate Improvement Proposals
|
||||
|
||||
**For each identified gap, create a specific proposal:**
|
||||
|
||||
```markdown
|
||||
### [Priority Level] Improvement: [What to Fix]
|
||||
|
||||
**Current State:**
|
||||
[What's currently in the story]
|
||||
|
||||
**Proposed Change:**
|
||||
[Specific text/content to add or modify]
|
||||
|
||||
**Rationale:**
|
||||
[Why this change improves the story]
|
||||
|
||||
**Impact:**
|
||||
- Quality Score: +X points
|
||||
- Development Clarity: High/Medium/Low
|
||||
- Testing Clarity: High/Medium/Low
|
||||
```
|
||||
|
||||
### Step 4: Calculate Quality Impact
|
||||
|
||||
**Before Refinement Score:**
|
||||
```
|
||||
Acceptance Criteria: 0/30 (missing)
|
||||
Description: 15/30 (minimal)
|
||||
Refinement: 8/15 (partial)
|
||||
Estimation: 0/15 (no points)
|
||||
Documentation: 2/10 (minimal)
|
||||
Total: 25/100 (Poor)
|
||||
```
|
||||
|
||||
**After Refinement Score (Estimated):**
|
||||
```
|
||||
Acceptance Criteria: 28/30 (comprehensive)
|
||||
Description: 26/30 (detailed with context)
|
||||
Refinement: 14/15 (well-refined)
|
||||
Estimation: 12/15 (points assigned)
|
||||
Documentation: 8/10 (examples added)
|
||||
Total: 88/100 (Excellent)
|
||||
```
|
||||
|
||||
**Improvement: +63 points**
|
||||
|
||||
### Step 5: Format Output for User Review
|
||||
|
||||
**Structure the response:**
|
||||
```markdown
|
||||
# Story Refinement Proposal: [STORY-KEY]
|
||||
|
||||
## Executive Summary
|
||||
- **Current Quality:** 25/100 (Poor)
|
||||
- **Projected Quality:** 88/100 (Excellent)
|
||||
- **Improvement:** +63 points
|
||||
- **Confidence:** High
|
||||
- **Effort:** 15 minutes to apply changes
|
||||
|
||||
## Priority Improvements
|
||||
|
||||
### 🔴 Critical: Add Acceptance Criteria
|
||||
[Details...]
|
||||
|
||||
### 🟡 Important: Enhance Description
|
||||
[Details...]
|
||||
|
||||
### 🟢 Optional: Add Technical Context
|
||||
[Details...]
|
||||
|
||||
## Full Diff Preview
|
||||
[Show complete before/after...]
|
||||
|
||||
## Next Steps
|
||||
1. Review proposed changes
|
||||
2. Confirm or modify suggestions
|
||||
3. Apply changes to Jira story
|
||||
```
|
||||
|
||||
## Refinement Templates
|
||||
|
||||
### Template 1: User Story Format
|
||||
```
|
||||
As a [user type]
|
||||
I want [capability]
|
||||
So that [business value]
|
||||
|
||||
Context:
|
||||
[Why this matters, background information]
|
||||
|
||||
Technical Approach:
|
||||
[High-level implementation notes if needed]
|
||||
|
||||
Acceptance Criteria:
|
||||
- Given [precondition]
|
||||
When [action]
|
||||
Then [expected outcome]
|
||||
- [Additional criteria...]
|
||||
|
||||
Definition of Done:
|
||||
- [ ] Code complete and reviewed
|
||||
- [ ] Unit tests pass
|
||||
- [ ] Integration tested
|
||||
- [ ] Documentation updated
|
||||
```
|
||||
|
||||
### Template 2: Technical Story Format
|
||||
```
|
||||
Story: [Concise technical summary]
|
||||
|
||||
Problem:
|
||||
[What technical issue or gap exists]
|
||||
|
||||
Proposed Solution:
|
||||
[How to address it]
|
||||
|
||||
Technical Details:
|
||||
- [Specific implementation notes]
|
||||
- [Dependencies, libraries, approaches]
|
||||
|
||||
Acceptance Criteria:
|
||||
- [Measurable technical outcomes]
|
||||
- [Performance criteria if applicable]
|
||||
|
||||
Risks/Considerations:
|
||||
- [Potential issues or dependencies]
|
||||
```
|
||||
|
||||
### Template 3: Bug Fix Story Format
|
||||
```
|
||||
Bug: [Clear summary of the issue]
|
||||
|
||||
Current Behavior:
|
||||
[What's happening now]
|
||||
|
||||
Expected Behavior:
|
||||
[What should happen]
|
||||
|
||||
Steps to Reproduce:
|
||||
1. [Step 1]
|
||||
2. [Step 2]
|
||||
3. [Observe issue]
|
||||
|
||||
Root Cause (if known):
|
||||
[Technical explanation]
|
||||
|
||||
Fix Approach:
|
||||
[How to resolve]
|
||||
|
||||
Acceptance Criteria:
|
||||
- Bug no longer reproducible with original steps
|
||||
- [Additional validation criteria]
|
||||
- [Regression tests added]
|
||||
```
|
||||
|
||||
## Common Improvement Patterns
|
||||
|
||||
### Pattern 1: Missing Acceptance Criteria
|
||||
**Detection:** No AC field populated, no "Acceptance Criteria:" in description
|
||||
|
||||
**Proposal:**
|
||||
```
|
||||
Add specific, testable acceptance criteria:
|
||||
- Define happy path scenario
|
||||
- Cover edge cases (empty state, max limits, errors)
|
||||
- Include non-functional requirements (performance, accessibility)
|
||||
```
|
||||
|
||||
### Pattern 2: Vague Description
|
||||
**Detection:** Description <50 words, no context on WHY
|
||||
|
||||
**Proposal:**
|
||||
```
|
||||
Enhance description with:
|
||||
- User value statement (So that...)
|
||||
- Background context (current state, pain point)
|
||||
- Success criteria (what does "done" look like?)
|
||||
```
|
||||
|
||||
### Pattern 3: Missing Technical Context
|
||||
**Detection:** Complex story without implementation notes
|
||||
|
||||
**Proposal:**
|
||||
```
|
||||
Add technical section:
|
||||
- Libraries/frameworks to use
|
||||
- Integration points (APIs, services)
|
||||
- Data models affected
|
||||
- Security/performance considerations
|
||||
```
|
||||
|
||||
### Pattern 4: No Estimation
|
||||
**Detection:** Story points field empty
|
||||
|
||||
**Proposal:**
|
||||
```
|
||||
Suggest story points based on:
|
||||
- Similar completed stories
|
||||
- Complexity assessment
|
||||
- Team velocity patterns
|
||||
Recommend: [X] points
|
||||
```
|
||||
|
||||
### Pattern 5: Poor Story Format
|
||||
**Detection:** Doesn't follow "As a... I want... So that..." format
|
||||
|
||||
**Proposal:**
|
||||
```
|
||||
Rewrite in user story format:
|
||||
- Identify user persona
|
||||
- State desired capability
|
||||
- Explain business value
|
||||
```
|
||||
|
||||
## Integration with Agent
|
||||
|
||||
**The story-refiner agent will:**
|
||||
1. Invoke this skill with a story key
|
||||
2. Receive improvement proposals
|
||||
3. Format for user review
|
||||
4. Confirm with user before applying changes
|
||||
5. Update Jira story with approved changes
|
||||
|
||||
**This skill:**
|
||||
- Fetches story data via Atlassian MCP
|
||||
- Analyzes quality dimensions
|
||||
- Generates specific improvement proposals
|
||||
- Returns structured recommendations
|
||||
- Does NOT update Jira (agent handles that after confirmation)
|
||||
|
||||
## Best Practices
|
||||
|
||||
1. **Be Specific:** Don't just say "improve description" - provide exact text
|
||||
2. **Prioritize Changes:** Mark critical vs. optional improvements
|
||||
3. **Explain Rationale:** Help user understand WHY each change helps
|
||||
4. **Show Before/After:** Make it easy to see the difference
|
||||
5. **Estimate Impact:** Quantify quality improvement
|
||||
6. **Respect Existing Content:** Build on what's there, don't replace unnecessarily
|
||||
7. **Use Templates:** Suggest story formats appropriate to type (feature/bug/tech)
|
||||
|
||||
## Output Format
|
||||
|
||||
Always structure skill output as:
|
||||
|
||||
1. **Story Analysis Summary:**
|
||||
- Current quality score
|
||||
- Key strengths
|
||||
- Main weaknesses
|
||||
|
||||
2. **Prioritized Improvements:**
|
||||
- Critical (must-have)
|
||||
- Important (should-have)
|
||||
- Optional (nice-to-have)
|
||||
|
||||
3. **Detailed Proposals:**
|
||||
- For each improvement: current state, proposed change, rationale, impact
|
||||
|
||||
4. **Full Diff:**
|
||||
- Complete before/after view of all proposed changes
|
||||
|
||||
5. **Quality Projection:**
|
||||
- Estimated quality score after changes
|
||||
- Confidence level
|
||||
|
||||
6. **Next Steps:**
|
||||
- Clear actions for user
|
||||
|
||||
## Error Handling
|
||||
|
||||
### Story Not Found
|
||||
```markdown
|
||||
**Error:** Story [STORY-KEY] not found in Jira
|
||||
|
||||
**Possible Causes:**
|
||||
- Story key is incorrect (case-sensitive)
|
||||
- Story doesn't exist
|
||||
- No permission to access story
|
||||
|
||||
**Solution:** Verify story key and access permissions
|
||||
```
|
||||
|
||||
### Insufficient Permissions
|
||||
```markdown
|
||||
**Error:** Cannot read story [STORY-KEY] - permission denied
|
||||
|
||||
**Solution:** Ensure ATLASSIAN_API_KEY has read access to this project
|
||||
```
|
||||
|
||||
### Story Already High Quality
|
||||
```markdown
|
||||
**Analysis:** Story [STORY-KEY] has excellent quality (92/100)
|
||||
|
||||
**Assessment:**
|
||||
- ✓ Comprehensive acceptance criteria
|
||||
- ✓ Detailed description with context
|
||||
- ✓ Well-refined with story points
|
||||
- ✓ Supporting documentation attached
|
||||
|
||||
**Recommendation:** No changes needed. Story is ready for development.
|
||||
```
|
||||
|
||||
### Incomplete Story Data
|
||||
```markdown
|
||||
**Warning:** Story [STORY-KEY] has limited data available
|
||||
|
||||
**Missing Fields:**
|
||||
- Story points (not tracked in this project)
|
||||
- Custom AC field (project doesn't use this field)
|
||||
|
||||
**Analysis:** Proceeding with available data
|
||||
[Continue with analysis based on description field only...]
|
||||
```
|
||||
|
||||
## Data Quality Tracking
|
||||
|
||||
**Always report:**
|
||||
```python
|
||||
{
|
||||
"story_key": "PROJ-123",
|
||||
"quality_score_before": 25,
|
||||
"quality_score_after": 88,
|
||||
"improvement": 63,
|
||||
"confidence": "high", # high/medium/low
|
||||
"fields_analyzed": ["summary", "description", "acceptanceCriteria", "storyPoints"],
|
||||
"fields_missing": ["components"],
|
||||
"proposals_generated": 5,
|
||||
"critical_proposals": 2,
|
||||
"important_proposals": 2,
|
||||
"optional_proposals": 1
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
When invoked, this skill will analyze the specified Jira story and return detailed, actionable improvement proposals that the story-refiner agent can present for user review and confirmation.
|
||||
Reference in New Issue
Block a user