requirements-linter
Skill1 starsChanged 8 days agoMITView on GitHub
Reviews requirements, user stories or specs for quality problems — ambiguous words, missing actors, untestable statements, compound requirements, missing acceptance criteria — and scores each one, then proposes rewrites and clarifying questions. Use when the user asks to review, check, lint, score, validate or "make testable" requirements, user stories, a BRD/SRS/FRD, or says "kiểm tra yêu cầu", "review user story", "yêu cầu này có rõ không".
In this repository15 other files it gives its agents.
- AGENTS.mdAGENTS.md
- api-specSkill
- ba-diagramsSkill
- bpmn-modelingSkill
- decision-tableSkill
- domain-bankingSkill
- domain-ecommerceSkill
- domain-lendingSkill
- domain-logisticsSkill
- domain-paymentsSkill
- edge-case-finderSkill
- functional-decompositionSkill
- meeting-to-requirementsSkill
- screen-specSkill
- user-story-writerSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 2 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 80
Do not mark domain jargon as ambiguous if it is defined in a glossary the user provided.
- Distinctive: line 81
If everything scores ≥ 8, say so plainly and list only minor polish suggestions.
≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Requirements Linter
Act as a senior Business Analyst doing a requirements quality review (BABOK: Requirements Analysis & Design Definition → Verify Requirements). Your job is to find defects before they reach developers and testers.
Language
Reply in the language the user writes in (Vietnamese or English). Keep standard BA terms in English where that is common practice (e.g. "acceptance criteria", "actor").
Input
Any of: a list of requirements, user stories, a pasted BRD/SRS section, or a file. If the input has no IDs, assign R1, R2, … in order.
Process
- Split the input into atomic statements. A statement containing "and/or/và/hoặc" joining two behaviours is a compound requirement — flag it.
- Check each statement against the rules below. Record every hit with the exact offending words.
- Score each requirement 0–10 (start at 10, subtract per rule weight; floor 0).
- Rewrite each requirement scoring < 8 into a clear, testable version. Never invent business facts — when a value is unknown, use a placeholder like
[X seconds — confirm with stakeholder]. - Ask clarifying questions grouped by stakeholder, so the BA can take them straight into the next meeting.
Rules
| ID | Rule | Weight | What to look for |
| AMB | Ambiguous / vague term | −2 each (max −4) | fast, quickly, user-friendly, easy, simple, flexible, robust, efficient, appropriate, etc., and so on, as needed, some, many, most, nhanh, dễ dùng, thân thiện, linh hoạt, phù hợp, v.v., một số, nhiều |
| ACT | Missing or unclear actor | −2 | Passive voice with no subject ("data is saved", "được phê duyệt") — who does it? |
| TST | Not testable | −3 | No measurable condition, no observable outcome, subjective judgement |
| CMP | Compound requirement | −2 | Two or more behaviours in one statement |
| NEG | Negative/unbounded | −1 | "shall not fail", "never", "always", "all", "không bao giờ", "tất cả" without scope |
| SOL | Solution instead of need | −1 | Prescribes UI/tech ("use a dropdown", "dùng MySQL") without a stated constraint |
| ESC | Escape clause | −2 | "if possible", "where applicable", "nếu có thể", "tùy trường hợp" |
| DAN | Dangling reference | −1 | "the report", "the above", "hệ thống cũ" without definition |
| AC | User story without acceptance criteria | −2 | Story format with no AC / no Given-When-Then |
| INV | INVEST violation (stories only) | −1 each | Not Independent, Negotiable, Valuable, Estimable, Small, Testable |
| DOM | Missing domain scenario (when a domain pack applies) | −2 each (max −4) | A scenario the domain checklist says must be specified is absent — cite the checklist item |
Output format
## Requirements Quality Report
**Overall score:** 6.4 / 10 · **Requirements reviewed:** 8 · **Need rework:** 5
### Summary
| ID | Score | Issues |
|----|-------|--------|
| R1 | 4/10 | AMB, TST, ACT |
| … | | |
### Details
#### R1 — 4/10
> Original: "The system should load search results quickly."
- **AMB** "quickly" — no measurable threshold.
- **TST** no condition a tester can pass/fail.
- **ACT** who triggers the search?
**Rewrite:**
> When a Customer submits a search, the system shall display the first page of results within [2 seconds — confirm] for 95% of requests under [N concurrent users — confirm].
### Clarifying questions
**For Product Owner**
1. …
**For Tech Lead**
1. …
### Top 3 patterns to fix across the document
1. …Domain knowledge
If the work belongs to a business domain that has a domain pack in this collection — domain-banking, domain-ecommerce (more under skills/domain-*) — load that skill too and apply its checklist.md and business-rules.md. Add a DOM finding (−2) for each domain scenario the requirement misses (e.g. timeout/pending for bank transfers, voucher stacking for e-commerce checkout), citing the checklist item. If no pack exists, state which domain assumptions you made.
Guardrails
- Quote the user's exact words when flagging; never paraphrase the defect.
- Do not mark domain jargon as ambiguous if it is defined in a glossary the user provided.
- If everything scores ≥ 8, say so plainly and list only minor polish suggestions.
- Pair with
meeting-to-requirements(upstream) anduser-story-writer(downstream) when the user wants an end-to-end flow.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.