| name | story-writing-standards |
| description | Evaluates user stories against the project's story writing standards rubric, providing structured assessments with scores and actionable feedback. Use when reviewing stories before implementation, validating acceptance criteria quality, or asking Scribe (Story Writer agent) to grade story drafts. |
Story Writing Standards Grading
Purpose
Systematically evaluate user stories against the 5 criteria defined in /docs/standards/story-writing-standards-rubric.md:
- Acceptance Criteria Quality (25%): Can an implementer verify completion?
- Testability (20%): Can automated tests be written directly?
- Scope Clarity (20%): Is it unambiguous what IS and IS NOT included?
- Technical Detail Sufficiency (20%): Does an AI agent have enough context?
- Project Pattern Alignment (15%): Does it follow project conventions?
MCP-First: Query Current Best Practices
Before evaluating, query MCP tools for agile and story writing standards:
Microsoft Learn MCP
1. microsoft_docs_search: query="Azure DevOps user stories best practices"
2. microsoft_docs_search: query="agile acceptance criteria definition of done"
Recommended queries:
- "Azure DevOps work item best practices"
- "User story INVEST principles"
- "Acceptance criteria Given When Then"
- "Definition of done checklist"
Context7 MCP
1. resolve-library-id: libraryName="agile", query="user stories"
2. query-docs: libraryId from step 1, query="acceptance criteria"
How to Use This Skill
Input
Provide one of the following:
- Story file path:
@workspace/stories/story-001.md
- Story content: Pasted or selected story text
- Work item reference: Azure DevOps work item ID
Invocation Examples
Evaluate this story against our writing standards: @workspace/stories/US-001-student-search.md
Grade this user story for implementation readiness.
Review my acceptance criteria for completeness and testability.
Evaluation Process
Step 1: Load the Rubric
Read and apply /docs/standards/story-writing-standards-rubric.md as the evaluation standard.
Step 2: Check Prerequisites
Verify story has:
Step 3: Evaluate Each Criterion
For each of the 5 criteria:
- Apply the rubric's scoring indicators (1-10 scale)
- Note specific examples supporting the score
- Identify concrete improvements with suggested rewrites
Step 4: Generate Assessment
Use the evaluation template with actionable recommendations.
Output Template
## Story Evaluation: [Story ID - Title]
**Evaluator**: GitHub Copilot
**Date**: [YYYY-MM-DD]
### Scores
| Criterion | Weight | Score | Weighted |
|-----------|--------|-------|----------|
| Acceptance Criteria Quality | 25% | /10 | |
| Testability | 20% | /10 | |
| Scope Clarity | 20% | /10 | |
| Technical Detail Sufficiency | 20% | /10 | |
| Project Pattern Alignment | 15% | /10 | |
| **Overall** | 100% | | /10 |
### Criterion Details
#### Acceptance Criteria Quality: [X]/10
**Strengths**: [what's well-defined]
**Gaps**: [what's missing or vague]
**Suggested rewrites**:
- Original: "[vague AC]"
- Improved: "[specific, testable AC]"
#### Testability: [X]/10
**Can derive these tests**:
- [test case 1]
- [test case 2]
**Cannot test without clarification**:
- [unclear scenario]
#### Scope Clarity: [X]/10
**Clear boundaries**: [what's well-scoped]
**Ambiguous areas**: [what could cause scope creep]
**Suggested additions**:
- Out of scope: [items to explicitly exclude]
#### Technical Detail Sufficiency: [X]/10
**Decisions made**: [architectural choices documented]
**Decisions needed**: [what implementer would have to guess]
**Suggested additions**:
- [specific technical detail to add]
#### Project Pattern Alignment: [X]/10
**Follows patterns**: [alignment with conventions]
**Deviations**: [inconsistencies or concerns]
### Recommendations
**Must address before implementation**:
- [ ] [blocking issue with specific fix]
**Should clarify**:
- [ ] [important clarification]
**Consider adding**:
- [ ] [enhancement]
### Verdict
[READY FOR DEV / NEEDS REFINEMENT / NEEDS REWRITE]
Criteria:
- READY FOR DEV: Overall >= 7, no criterion below 6
- NEEDS REFINEMENT: Overall 5-6.9, or one criterion below 6
- NEEDS REWRITE: Overall < 5, or multiple criteria below 4
Quick Reference
| Criterion | Core Question | Red Flags |
|---|
| AC Quality | Can I verify this is done? | "Works correctly", "fast", "user-friendly" |
| Testability | Can I write tests from this? | No expected outputs, no error cases |
| Scope Clarity | What's in and out? | "And maybe also...", no boundaries |
| Technical Detail | Do I know how to build this? | "Figure out best approach", no file references |
| Pattern Alignment | Does this fit the project? | New patterns without justification, format inconsistencies |
INVEST Principles Checklist
Quick validation for story structure:
| Principle | Question | Pass/Fail |
|---|
| Independent | Can be completed without other stories? | |
| Negotiable | Details can be discussed during implementation? | |
| Valuable | Delivers user or business value? | |
| Estimable | Team can estimate the work? | |
| Small | Completable in one sprint/session? | |
| Testable | Has clear acceptance criteria? | |
Common Anti-Patterns to Flag
| Anti-Pattern | Example | Suggested Fix |
|---|
| Vague AC | "Search works well" | "Search returns results in <2s for up to 10k records" |
| Hidden Epic | "Implement student management" | Break into 5-10 independent stories |
| Tech-only | "Refactor database layer" | Add user value: "...so searches are faster" |
| Gold-plating | "Add search with AI and export and saved queries" | One feature per story |
| Missing Error Cases | Only happy path ACs | Add: "When X fails, then Y message appears" |
| Assumed Context | "Update the form" | "Update StudentCreate.cshtml form" |
Actionable Improvement Examples
Vague to Specific AC
Before (Score 3):
- [ ] User can search for students
- [ ] Search should be fast
- [ ] Results are displayed nicely
After (Score 9):
- [ ] AC1: Search input accepts 1-100 characters; displays validation error for empty or >100
- [ ] AC2: Search returns results within 2 seconds for up to 10,000 records
- [ ] AC3: Results display student name, ID, and enrollment date in a sortable table
- [ ] AC4: Empty results display "No students match your search" message
- [ ] AC5: Search is case-insensitive and matches partial strings in first or last name
Missing to Complete Scope
Before (Score 4):
Add search functionality with filters and export.
After (Score 9):
## Scope
**In scope:**
- Search by last name only
- Display results in table format
- Basic pagination (10 per page)
**Out of scope (future stories):**
- Search by other fields (first name, ID, email)
- Advanced filters
- Export functionality
- Saved searches
## Dependencies
- Story-01 (Student list page) must be complete
Reference
