| name | requirements-reviewer |
| description | Review software requirements against the 8 Key Characteristics of Good Requirements (Clear, Complete, Consistent, Verifiable, Feasible, Traceable, Atomic, Positive) and produce a structured report with issues, clarifying questions, a per-requirement grading table, aggregate scores, and top recommendations. Use this skill whenever the user asks to "review requirements", "check my requirements", "analyze user stories", "review acceptance criteria", "validate my specs", "grade my requirements", "give feedback on requirements", or pastes/attaches a list of requirements or user stories and asks for feedback — even if they just say "are these good?" or attach a requirements document. |
| argument-hint | file path or paste requirements text |
Requirements Reviewer
Review requirements against the 8 Key Characteristics of Good Requirements and produce a structured report with issues, clarifying questions, a per-requirement grading table, and aggregate scoring.
Scope note: This review evaluates the textual quality of requirements based on well-established characteristics. It cannot validate domain correctness or deep technical feasibility without additional project context — when those aspects matter, prompt the user for constraints.
When to Use This Skill
Use for requests like:
- "review my requirements"
- "check if these requirements are well-written"
- "give feedback on my user stories / acceptance criteria"
- "grade my specs"
- "are my requirements clear and testable?"
- user pastes or attaches a requirements document and asks what you think
Do not use it for:
- generating requirements from scratch (the user has no existing requirements to review)
- writing test cases from requirements (use
api-test-scenario-generator or ut-analyst)
- creating Jira issues from requirements (use
jira-mcp-assistant)
The 8 Key Characteristics Rubric
Evaluate every requirement against each characteristic below. These definitions are your grading rubric — keep them in mind throughout.
| # | Characteristic | Definition |
|---|
| 1 | Clear | Unambiguous — only one valid interpretation. No vague words (e.g., "fast", "user-friendly", "as needed", "appropriate"). |
| 2 | Complete | Covers all necessary aspects of the described functionality. No missing pre/postconditions, actors, or edge cases that are obviously implied. |
| 3 | Consistent | Does not contradict other requirements. Uses consistent terminology; no synonym confusion between related requirements. |
| 4 | Verifiable | Can be tested or confirmed via inspection, demonstration, analysis, or a pass/fail test. Avoids unmeasurable claims. |
| 5 | Feasible | Achievable within realistic project constraints (time, budget, technology). Flag when a constraint assumption is needed. |
| 6 | Traceable | Can be linked to a higher-level requirement, business goal, or stakeholder need. Standalone requirements with no stated justification should prompt a question. |
| 7 | Atomic | Focuses on exactly one capability or constraint. Requirements that contain "and" connecting distinct behaviors are candidates for splitting. |
| 8 | Positive | States what the system shall do, not what it shall not do. Negative phrasing is acceptable only for explicit exclusion/constraint requirements. |
Workflow
Step 1: Locate the Requirements Input
Check for requirements in this order:
-
Attached file — if the user attached or referenced a file, read it now.
-
Inline text — if requirements were pasted directly into the conversation, use that text.
-
Neither present — respond with:
Please provide the requirements to review. You can either:
- Attach or reference a requirements document
- Paste the requirements text directly into the chat
Do not proceed without a concrete requirements source.
Supported Input Formats
| Format | How to use | Notes |
|---|
| Inline text | Paste directly into chat | Quickest option — no file needed |
.txt | Attach or reference file | Plain text; works perfectly |
.md / .markdown | Attach or reference file | Ideal for user stories, Gherkin, and spec docs |
.csv | Attach or reference file | Look for ID, title/description columns; one row per requirement |
.json / .yaml | Attach or reference file | Extract requirement text from relevant fields |
.html | Attach or reference file | Best export format for Confluence pages; preserves tables and structure |
.docx | Attach or reference file | Works when Word file-reading support is available |
.pdf | Attach or reference file | Text-based PDFs only — scanned/image PDFs cannot be read |
Unsupported / unreliable: scanned image PDFs (no OCR), .xlsx without spreadsheet tooling, screenshots.
Confluence Pages
If your requirements live in Confluence, use one of these approaches (in order of preference):
- Export as HTML (single page) — best option. Go to the page →
··· menu → Export → HTML. Attach the .html file. Tables, headings, and formatting are fully preserved.
- Copy-paste content into chat — quick and reliable for shorter pages. Select all text on the Confluence page (Ctrl+A), paste into the chat message.
- Export as PDF — acceptable fallback, but multi-column tables may lose their structure during extraction.
Step 2: Extract Individual Requirements
Parse the input and extract each distinct requirement as a numbered list. Apply these rules:
- A requirement is any statement describing what the system shall do, a constraint, or an acceptance criterion.
- If the input uses user-story format ("As a … I want … so that …"), treat each story as one requirement.
- If a single sentence contains multiple independent behaviors joined by "and" or ";", note this as a potential atomicity issue but treat it as one unit for grading.
- Strip bullets, identifiers (e.g., "REQ-001"), or story numbers — restate each requirement cleanly.
If fewer than 2 requirements are found, ask the user to confirm they have provided the full input.
Step 3: Context Check (Optional but Recommended)
Before grading, determine whether any of the following would improve accuracy of Feasible and Traceable scores:
- Project constraints (timeline, tech stack, budget)
- Business goals or higher-level objectives the requirements trace to
- A project glossary for Consistent terminology checks
If the user did not provide this context and the requirement set has more than 5 items, ask in a single message:
To give you the most accurate Feasible and Traceable scores, it would help to know:
- Are there any known technical or budget constraints?
- What business goal or objective do these requirements serve?
You can skip this and I'll note where assumptions were made.
If the user skips or the set is small (≤ 5 items), proceed and note assumptions inline.
Step 4: Grade Each Requirement
For each extracted requirement, score every characteristic as one of:
- ✅ Pass — characteristic is clearly satisfied
- ⚠️ Partial — characteristic is partially met; improvement possible
- ❌ Fail — characteristic is not met or cannot be determined
Apply the rubric definitions strictly. When in doubt between Pass and Partial, choose Partial and note why.
Step 5: Identify Issues and Questions
For every ⚠️ Partial or ❌ Fail grade, produce a concrete issue statement and/or a clarifying question. Be specific — quote the problematic phrase when relevant.
Good issue: "'fast response time' is not measurable — specify a threshold (e.g., ≤ 200 ms under normal load)."
Poor issue: "This requirement is not clear."
Step 6: Compute Aggregate Scores
For each of the 8 characteristics, compute an aggregate score (0–10) across all requirements using this formula:
score = ((Pass × 1.0 + Partial × 0.5 + Fail × 0.0) / total_requirements) × 10
Round to one decimal place.
Step 7: Produce the Report
Output the full report using the template in the Output Format section below.
Output Format
Use this exact structure. Do not add extra top-level sections; you may add sub-bullets inside sections.
# Requirements Review Report
> **Input**: [filename or "inline text"] · **Requirements found**: N · **Reviewed**: [date]
---
## 1. Extracted Requirements
| # | Requirement |
| --- | ----------------------- |
| 1 | [full requirement text] |
| 2 | [full requirement text] |
| … | … |
---
## 2. Issues & Clarifying Questions
### Req 1 — [3–6 word label]
- 🔴 **[Characteristic]**: [Concrete issue statement. Quote the problem phrase if helpful.]
- ⚠️ **[Characteristic]**: [Improvement suggestion or clarifying question.]
- ❓ **Question**: [Specific question to ask the stakeholder.]
### Req 2 — [3–6 word label]
_(No issues — all characteristics pass.)_
… (one subsection per requirement; omit requirements with no issues only if ≥ 80% pass — otherwise include a "No issues" note to confirm they were reviewed)
---
## 3. Characteristics Grading Table
| # | Requirement (short) | Clear | Complete | Consistent | Verifiable | Feasible | Traceable | Atomic | Positive |
| --- | ------------------- | ----- | -------- | ---------- | ---------- | -------- | --------- | ------ | -------- |
| 1 | [short label] | ✅ | ⚠️ | ✅ | ❌ | ✅ | ⚠️ | ✅ | ✅ |
| 2 | [short label] | … | … | … | … | … | … | … | … |
---
## 4. Aggregate Scores
| Characteristic | Score (0–10) | Assessment |
| -------------- | :----------: | ---------------------------------------------------------------------- |
| Clear | 8.0 | Most requirements are unambiguous; Req 3 needs a measurable threshold. |
| Complete | 5.0 | Several requirements omit error/edge-case handling. |
| Consistent | 9.0 | Terminology is consistent throughout. |
| Verifiable | 6.5 | Three requirements lack measurable acceptance criteria. |
| Feasible | 7.0 | Assumed standard web-app constraints; no major red flags. |
| Traceable | 3.0 | No business goals or parent requirements referenced anywhere. |
| Atomic | 8.5 | One requirement should be split. |
| Positive | 10.0 | All requirements state intended behavior positively. |
| **Overall** | **7.1** | **Weighted average across all characteristics.** |
---
## 5. Top Recommendations
1. **[Most impactful improvement]** — [1–2 sentence explanation and suggested fix.]
2. **[Second improvement]** — [explanation.]
3. **[Third improvement]** — [explanation.]
_(List up to 5 recommendations, ordered by impact.)_
Grading Guidelines
Clear
Flag: vague adjectives ("efficient", "seamless", "intuitive", "robust", "easy"), undefined acronyms, pronouns with ambiguous referents ("it", "they"), or passive voice that hides the actor ("shall be validated" — by whom?).
Complete
Flag: requirements that describe a happy path only (no mention of error states, boundary conditions, or what happens when preconditions are not met), missing actor or system boundary, or unexplained inputs/outputs.
Consistent
Compare terminology across the full requirement set. Flag: same concept named differently in different requirements (e.g., "user" vs "customer" vs "end user" used interchangeably), or contradictory constraints (e.g., Req 2 says response ≤ 100 ms, Req 7 says ≤ 500 ms for same operation).
Verifiable
Flag: requirements that cannot produce a binary pass/fail test. Words like "should", "may", "could", "appropriately", "sufficiently", and "as required" are red flags. A good verifiable requirement names measurable values, quantities, or observable behaviors.
Feasible
If no project context was given, note the assumption. Flag: requirements that reference technologies not commonly available, extremely tight performance requirements without justification, or contradictory constraints that cannot be simultaneously met. Do not fail a requirement on feasibility without evidence — use ⚠️ Partial to raise a question instead.
Traceable
Flag: requirements with no stated business justification, no reference to a higher-level objective, and no indication of which stakeholder requested it. A user story "so that" clause satisfies this partially. Full traceability requires a link to a business goal, epic, or regulatory requirement.
Atomic
Flag: compound requirements using "and" or ";" to join independent behaviors, requirements that embed multiple distinct constraints, or requirements that implicitly describe both functional and non-functional concerns in one statement.
Positive
Flag: requirements using "shall not", "must not", "will not" as the primary statement rather than as a constraint on an otherwise positive behavior. Exception: security and exclusion requirements are legitimately negative ("the system shall not expose PII to unauthenticated users").
Tone and Style
- Be specific and constructive. Quote the problematic phrase rather than describing it vaguely.
- Avoid condescending language. The issues section should read like a peer review, not a rejection.
- When a requirement is genuinely well-written, say so briefly — don't invent problems.
- Keep the issues section focused: one issue per characteristic per requirement. Combine closely related points.
- If the overall quality is high (Overall Score ≥ 8.0), open the report with a brief positive note.
