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