Good requirements are the foundation of good systems engineering - but "good" is hard to enforce by hand across hundreds of requirements. The EARS Requirement Scorer is a GENESYS script that reads a requirement, grades how well it conforms to the EARS notation and general requirements-quality rules, and writes back a letter grade, a numeric score, and a list of specific findings with suggested fixes. Select one or more Requirement entities, click a ribbon command, and every selected requirement is scored in place.

This post explains what the tool checks, how the grade and score are calculated, and what you need to set up before running it.

Download the EARS Score import file here

A quick primer on EARS

EARS (Easy Approach to Requirements Syntax) is a lightweight convention for writing clear, testable requirements using a small set of keywords in a fixed clause order. Every EARS requirement follows the shape:

While <state>, when <trigger>, the <system> shall <response>.

Not every clause is always present. The keywords you use determine the pattern:

The EARS ruleset says a requirement has zero or more preconditions, zero or one trigger, exactly one system name, and one or more system responses. The scorer parses your requirement into these clauses, figures out which pattern it is, and checks that the structure holds together.

New to EARS? The method was created by Alistair Mavin and colleagues - the authoritative reference, with all the patterns and examples, is at alistairmavin.com/ears.

The grading scale

The headline result is a single letter grade, written to the earsGrade attribute:

·      A - Conforms. No issues found. The requirement is well-formed EARS with no quality flags.

·      B - Advisory. Structurally valid EARS, but one or more quality concerns were found (vague wording, an un-quantified value, a missing model trace, etc.). Worth a look, but not broken.

·      C - Structural violation. The requirement breaks an EARS structural rule - no shall, an unclassifiable pattern, a missing system name, and so on. These need fixing.

The rule of thumb: structural problems drive a C; quality problems cap you at B; a clean requirement earns an A.

The numeric score

Alongside the grade, the tool writes a 0–100 score to earsScore. Where the letter grade tells a writer how good a requirement is, the score is a finer-grained metric you can trend across a project or a baseline over time.

It starts at 100 and deducts points per finding, by severity:

The score is floored at 0. Because a single structural finding costs 40 points, a C-grade requirement lands well below a merely-advisory B - so the number reinforces the letter.

The findings breakdown

The real value is in the earsFinding attribute: an itemized list of what's wrong and how to fix it. Each finding has an ID, a plain-English explanation, and a suggested rewrite. Findings fall into four families.

Structural (EARS conformance)

The backbone checks - any one of these forces a C:

·      Missing shall, or multiple shall clauses (a compound requirement that should be split)

·      Wrong clause order (e.g. when before while)

·      If without then

·      An empty trigger, state, or feature clause

·      No system name, or no response after shall

Lexical (wording quality)

Deterministic dictionary checks that cap you at B:

·      Vague / weasel words - fast, adequate, robust, user-friendly, significantly …

·      Vague-verb anti-patterns - shall support, shall handle, shall process, shall manage, shall accommodate (these don't say what the system actually does)

·      Capability phrasing - shall be capable of … (states what the system can do, not what it does)

·      Open-ended / escape clauses - etc., as appropriate, where feasible, best effort …

·      Placeholders - TBD, XX, ???

·      Subjective / superlative terms - seamless, best, state-of-the-art

·      Non-conformant modals - should / must used in place of shall

Heuristic (advisory, best-effort)

Pattern-based nudges that also cap at B:

·      Passive-voice responses ("shall be stored by …")

·      A threshold word with no number ("respond within a reasonable time")

·      Compound responses bundling several actions with and

·      Negative requirements ("shall not …") flagged for verifiability

·      A pronoun used as the system name ("it shall …")

Model (traceability)

A GENESYS-native check that a requirement is connected to the model. A well-formed requirement should trace to a real model element through a specifies relationship (to a Component, Function, Item, Link, Mode, Port, Product, ProgramElement, State, or Verification Event) or a basis of relationship (to a Function, Mitigation Activity, ProgramActivity, UseCase, VerificationActivity, VerificationRequirement, or VerificationRequirementGroup). If a valid target is found, the scorer names it in the output; if not, it raises a model advisory.

Example

"The system shall be capable of processing requests quickly."

·      Grade: B

·      Score: 76 (−12 for the capability phrase, −12 for "quickly")

·      Findings: L4 - capability phrasing "shall be capable of" states what the system can do, not what it does; L2 - vague term "quickly."

Rewritten as "When a request is received, the request processor shall return a response within 2 seconds," and traced to the appropriate Function, the same requirement scores an A / 100.

The real test: verifiability

A grade from this tool measures conformance to EARS structure and wording hygiene - it does not prove a requirement is correct. The ultimate test of a good requirement is verifiability: you should be able to write a clear, objective success criterion - a test, inspection, analysis, or demonstration - that determines whether the system meets it.

Before you accept any requirement, even an A, ask: what is the pass/fail criteria, and how would we confirm it?

If you can't state how you'd verify it, the requirement isn't finished - no matter how clean its syntax. A well-formed requirement that can't be verified is still a bad requirement.

Limitations - what the tool doesn't do

The scorer is a first-pass aid, not a replacement for engineering judgment or peer review. It is not comprehensive, and it's important to understand what it can't catch:

·      It checks form, not meaning. A requirement can be flawless EARS and still be wrong, ambiguous in context, infeasible, redundant, or untestable.

·      There are escapes. The lexical and heuristic checks rely on curated word lists and pattern matching, so a poorly written requirement can slip through and score higher than it deserves - giving the false impression that it's well written. A high grade means "no problems the tool recognized," not "this is a good requirement."

·      Heuristics are best-effort. The advisory checks can miss issues and occasionally over-flag.

·      It doesn't judge correctness, completeness, consistency across a set, feasibility, or necessity.

Treat the grade as a fast way to catch obvious problems and standardize style. Whether a requirement is actually good still comes down to review and - above all - verifiability.

Schema changes you'll need

The scorer writes its results to three custom attributes on the Requirement class. Add these in the GENESYS schema before running the command (the script checks for them and warns you if they're missing):

A couple of tips:

·      You can give the attributes friendlier display aliases (e.g. show earsFinding as "EARS Results") - the alias is cosmetic and doesn't affect the script.

·      Because earsFinding is a Text attribute, it's a good place to paste a short legend of the finding catalog into the attribute's schema description, so reviewers always have the rule reference at hand.

The model traceability check uses the standard specifies and basis of relationships, which already exist in the GENESYS schema - no additional relationship setup is required.

Installing the script

The scorer ships as a ready-to-import GENESYS file - there's no code to create or paste. You import it, wire it to a ribbon button, and you're done.

Before you start: make sure the three output attributes (earsGrade, earsScore, earsFinding) are defined on the Requirement class - see Schema changes above. The script warns you and stops if they're missing.

1. Import the script. Use the GENESYS import command to bring in the provided .gnsx file. GENESYS adds an EARS Score folder to the Scripts section of the Project Explorer, containing the scorer - nothing to copy, edit, or compile.

2. Add a ribbon button. Open the Custom Ribbon editor - the small screwdriver-and-wrench icon on the right side of the Project Explorer, next to the help button. Click Add to create a ribbon group (e.g. "Requirements Quality"), select the new group, and click Add again to create a button. Give it a short name (e.g. "EARS Score"), pick a 32×32 icon, and assign the imported script from the EARS Score folder.

3. Run it. Click OK, and a new Custom tab appears in the ribbon with your button. Select one or more Requirement entities in the browser, click the button, and the scorer grades each one - writing the grade, score, and findings straight back to the entities.

Putting it to work

Once the attributes are in place and the command is installed, scoring is a two-click routine: select the requirements you want to check - one, a folder's worth, or a whole package - run the command, and watch the progress bar as each is graded. Results are written straight to the entities and summarized in a dialog, so you can triage the C's, tidy up the B's, and track your project's requirements quality as it improves.